93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# Unknowns Registry
|
|
|
|
**Status:** Implemented
|
|
**Source:** `src/Unknowns/`
|
|
**Owner:** Signals Guild, Policy Guild
|
|
|
|
## Purpose
|
|
|
|
The Unknowns Registry provides bitemporal ambiguity tracking for security scan gaps where reachability or applicability cannot be determined with confidence. It models Unknown-Reachable and Unknown-Unreachable states as first-class risk signals, enabling uncertainty-aware scoring and triage prioritization.
|
|
|
|
## Components
|
|
|
|
**Services:**
|
|
- Unknowns registry and tracking service
|
|
- Integration with Policy Engine for risk scoring
|
|
- Signals correlation for unknowns decay
|
|
|
|
**Libraries:**
|
|
- `StellaOps.Policy.Unknowns` - Unknowns budget and scoring logic
|
|
- Unknown state modeling and confidence tracking
|
|
|
|
## Key Features
|
|
|
|
- **First-class Unknown state:** Explicit modeling of uncertainty (not hidden as false negatives)
|
|
- **Bitemporal tracking:** Valid-time and transaction-time for ambiguity windows
|
|
- **Risk scoring integration:** `unknowns_pressure` factor in Policy Engine
|
|
- **Decay heuristics:** Unknowns decay over time with configurable policies
|
|
- **Triage queue:** Dedicated UI view for unknowns requiring investigation
|
|
- **Confidence budgets:** Policy gates can enforce maximum acceptable unknowns
|
|
|
|
## Configuration
|
|
|
|
**Unknowns Budget Options** (`UnknownBudgetOptions.cs`):
|
|
- Maximum unknowns threshold per finding
|
|
- Decay policies and timeouts
|
|
- Scoring weight multipliers
|
|
|
|
**Unknowns Decay Options** (`UnknownsDecayOptions.cs`):
|
|
- Decay curve parameters
|
|
- Confidence floor values
|
|
- Re-evaluation triggers
|
|
|
|
**Unknowns Rescan Options** (`UnknownsRescanOptions.cs`):
|
|
- Automatic rescan scheduling
|
|
- Priority queue management
|
|
|
|
## Integration Points
|
|
|
|
**Policy Engine:**
|
|
- Unknowns budget gate enforcement
|
|
- Confidence-based disposition selection
|
|
- Risk score adjustments based on unknowns count
|
|
|
|
**Signals:**
|
|
- Runtime signal correlation can resolve unknowns
|
|
- Automatic unknowns decay on new evidence
|
|
|
|
**UI:**
|
|
- Unknowns chips in findings display
|
|
- Dedicated triage queue for unknowns
|
|
- Confidence meter visualization
|
|
|
|
## Storage
|
|
|
|
- **Schema:** Part of `policy` schema in PostgreSQL
|
|
- **Tables:** Unknowns tracking, decay history, resolution events
|
|
|
|
## Dependencies
|
|
|
|
- PostgreSQL (unknowns tracking and audit)
|
|
- Policy Engine (scoring integration)
|
|
- Signals (runtime correlation)
|
|
- Triage UI (operator workflows)
|
|
|
|
## Related Documentation
|
|
|
|
- Unknowns decay heuristics: `../../operations/unknowns-triage.md`
|
|
- Policy gates: `../policy/gates.md`
|
|
- Confidence model: `../policy/confidence-model.md`
|
|
- UI triage guide: `../ui/triage-unknowns.md`
|
|
|
|
## Implementation Status
|
|
|
|
**Completed:**
|
|
- Unknowns registry with bitemporal tracking
|
|
- Policy Engine integration with budget gates
|
|
- UI chips and triage queue
|
|
- Decay heuristics and automatic resolution
|
|
- Confidence-based scoring adjustments
|
|
|
|
**Key Differentiator:**
|
|
Unlike other scanners that hide uncertainty, StellaOps makes "what we don't know" visible and policy-addressable. This is critical for air-gapped deployments and zero-day scenarios where external validation is unavailable.
|