docs consolidation and others
This commit is contained in:
master
326
docs/modules/unknowns/guides/README.md
Normal file
326
docs/modules/unknowns/guides/README.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Uncertainty States & Entropy Scoring
|
||||
|
||||
> **Status:** Implemented v0 for reachability facts (Signals).
|
||||
> **Owners:** Signals Guild · Policy Guild · UI Guild.
|
||||
|
||||
StellaOps treats missing data and untrusted evidence as **first-class uncertainty states**, not silent false negatives. Signals persists uncertainty state entries alongside reachability facts and derives a deterministic `riskScore` that increases when entropy is high.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core states (extensible)
|
||||
|
||||
| Code | Name | Meaning |
|
||||
|------|------|---------|
|
||||
| `U1` | `MissingSymbolResolution` | Unresolved symbols/edges prevent a complete reachability proof. |
|
||||
| `U2` | `MissingPurl` | Package identity/version is ambiguous (lockfile absent, heuristics only). |
|
||||
| `U3` | `UntrustedAdvisory` | Advisory source lacks provenance/corroboration. |
|
||||
| `U4` | `Unknown` | No analyzers have processed this subject; baseline uncertainty. |
|
||||
|
||||
Each state records:
|
||||
|
||||
- `entropy` (0..1)
|
||||
- `evidence[]` list pointing to analyzers/heuristics/sources
|
||||
- optional `timestamp` (UTC)
|
||||
|
||||
---
|
||||
|
||||
## 1.1 Uncertainty Tiers (v1 — Sprint 0401)
|
||||
|
||||
Uncertainty states are grouped into **tiers** that determine policy thresholds and UI treatment.
|
||||
|
||||
### Tier Definitions
|
||||
|
||||
| Tier | Entropy Range | States | Risk Modifier | Policy Implication |
|
||||
|------|---------------|--------|---------------|-------------------|
|
||||
| **T1 (High)** | `0.7 - 1.0` | `U1` (high), `U4` | `+50%` | Block "not_affected", require human review |
|
||||
| **T2 (Medium)** | `0.4 - 0.69` | `U1` (medium), `U2` | `+25%` | Warn on "not_affected", flag for review |
|
||||
| **T3 (Low)** | `0.1 - 0.39` | `U2` (low), `U3` | `+10%` | Allow "not_affected" with advisory note |
|
||||
| **T4 (Negligible)** | `0.0 - 0.09` | `U3` (low) | `+0%` | Normal processing, no special handling |
|
||||
|
||||
### Tier Assignment Rules
|
||||
|
||||
1. **U1 (MissingSymbolResolution):**
|
||||
- `entropy >= 0.7` → T1 (>30% unknowns in callgraph)
|
||||
- `entropy >= 0.4` → T2 (15-30% unknowns)
|
||||
- `entropy < 0.4` → T3 (<15% unknowns)
|
||||
|
||||
2. **U2 (MissingPurl):**
|
||||
- `entropy >= 0.5` → T2 (>50% packages unresolved)
|
||||
- `entropy < 0.5` → T3 (<50% packages unresolved)
|
||||
|
||||
3. **U3 (UntrustedAdvisory):**
|
||||
- `entropy >= 0.6` → T3 (no corroboration)
|
||||
- `entropy < 0.6` → T4 (partial corroboration)
|
||||
|
||||
4. **U4 (Unknown):**
|
||||
- Always T1 (no analysis performed = maximum uncertainty)
|
||||
|
||||
### Aggregate Tier Calculation
|
||||
|
||||
When multiple uncertainty states exist, the aggregate tier is the **maximum** (most severe):
|
||||
|
||||
```
|
||||
aggregateTier = max(tier(state) for state in uncertainty.states)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. JSON shape
|
||||
|
||||
```json
|
||||
{
|
||||
"uncertainty": {
|
||||
"states": [
|
||||
{
|
||||
"code": "U1",
|
||||
"name": "MissingSymbolResolution",
|
||||
"entropy": 0.72,
|
||||
"timestamp": "2025-11-12T14:12:00Z",
|
||||
"evidence": [
|
||||
{
|
||||
"type": "UnknownsRegistry",
|
||||
"sourceId": "signals.unknowns",
|
||||
"detail": "unknownsCount=12;unknownsPressure=0.375"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Risk score math (Signals)
|
||||
|
||||
Signals computes a `riskScore` deterministically during reachability recompute:
|
||||
|
||||
```
|
||||
meanEntropy = avg(uncertainty.states[].entropy) // 0 when no states
|
||||
entropyBoost = clamp(meanEntropy * k, 0 .. boostCeiling)
|
||||
riskScore = clamp(baseScore * (1 + entropyBoost), 0 .. 1)
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `baseScore` is the average of per-target reachability state scores (before unknowns penalty).
|
||||
- `k` defaults to `0.5` (`SignalsOptions:Scoring:UncertaintyEntropyMultiplier`).
|
||||
- `boostCeiling` defaults to `0.5` (`SignalsOptions:Scoring:UncertaintyBoostCeiling`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Policy guidance (high level)
|
||||
|
||||
Uncertainty should bias decisions away from "not affected" when evidence is missing:
|
||||
|
||||
- High entropy (`U1` with high `entropy`) should lead to **under investigation** and drive remediation (upload symbols, run probes, close unknowns).
|
||||
- Low entropy should allow normal confidence-based gates.
|
||||
|
||||
See `docs/modules/reach-graph/guides/lattice.md` for the current reachability score model and `docs/api/signals/reachability-contract.md` for the Signals contract.
|
||||
|
||||
---
|
||||
|
||||
## 5. Tier-Based Risk Score (v1 — Sprint 0401)
|
||||
|
||||
### Risk Score Formula
|
||||
|
||||
Building on §3, the v1 risk score incorporates tier-based modifiers:
|
||||
|
||||
```
|
||||
tierModifier = {
|
||||
T1: 0.50,
|
||||
T2: 0.25,
|
||||
T3: 0.10,
|
||||
T4: 0.00
|
||||
}[aggregateTier]
|
||||
|
||||
riskScore = clamp(baseScore * (1 + tierModifier + entropyBoost), 0 .. 1)
|
||||
```
|
||||
|
||||
Where:
|
||||
- `baseScore` is the average of per-target reachability state scores
|
||||
- `tierModifier` is the tier-based risk increase
|
||||
- `entropyBoost` is the existing entropy-based boost (§3)
|
||||
|
||||
### Example Calculation
|
||||
|
||||
```
|
||||
Given:
|
||||
- baseScore = 0.4 (moderate reachability)
|
||||
- uncertainty.states = [
|
||||
{code: "U1", entropy: 0.72}, // T1 tier
|
||||
{code: "U3", entropy: 0.45} // T3 tier
|
||||
]
|
||||
- aggregateTier = T1 (max of T1, T3)
|
||||
- tierModifier = 0.50
|
||||
|
||||
meanEntropy = (0.72 + 0.45) / 2 = 0.585
|
||||
entropyBoost = clamp(0.585 * 0.5, 0 .. 0.5) = 0.2925
|
||||
|
||||
riskScore = clamp(0.4 * (1 + 0.50 + 0.2925), 0 .. 1)
|
||||
= clamp(0.4 * 1.7925, 0 .. 1)
|
||||
= clamp(0.717, 0 .. 1)
|
||||
= 0.717
|
||||
```
|
||||
|
||||
### Tier Thresholds for Policy Gates
|
||||
|
||||
| Tier | `riskScore` Range | VEX "not_affected" | VEX "affected" | Auto-triage |
|
||||
|------|-------------------|-------------------|----------------|-------------|
|
||||
| T1 | `>= 0.6` | ❌ blocked | ⚠️ review | → `under_investigation` |
|
||||
| T2 | `0.4 - 0.59` | ⚠️ warning | ✅ allowed | Manual review |
|
||||
| T3 | `0.2 - 0.39` | ✅ with note | ✅ allowed | Normal |
|
||||
| T4 | `< 0.2` | ✅ allowed | ✅ allowed | Normal |
|
||||
|
||||
---
|
||||
|
||||
## 6. JSON Schema (v1)
|
||||
|
||||
Extended schema with tier information:
|
||||
|
||||
```json
|
||||
{
|
||||
"uncertainty": {
|
||||
"states": [
|
||||
{
|
||||
"code": "U1",
|
||||
"name": "MissingSymbolResolution",
|
||||
"entropy": 0.72,
|
||||
"tier": "T1",
|
||||
"timestamp": "2025-12-13T10:00:00Z",
|
||||
"evidence": [
|
||||
{
|
||||
"type": "UnknownsRegistry",
|
||||
"sourceId": "signals.unknowns",
|
||||
"detail": "unknownsCount=45;totalSymbols=125;unknownsPressure=0.36"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"code": "U4",
|
||||
"name": "Unknown",
|
||||
"entropy": 1.0,
|
||||
"tier": "T1",
|
||||
"timestamp": "2025-12-13T10:00:00Z",
|
||||
"evidence": [
|
||||
{
|
||||
"type": "NoAnalysis",
|
||||
"sourceId": "signals.bootstrap",
|
||||
"detail": "subject not yet analyzed"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"aggregateTier": "T1",
|
||||
"riskScore": 0.717,
|
||||
"computedAt": "2025-12-13T10:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Pointers
|
||||
|
||||
- **Tier calculation:** `UncertaintyTierCalculator` in `src/Signals/StellaOps.Signals/Services/`
|
||||
- **Risk score math:** `ReachabilityScoringService.ComputeRiskScore()` (extend existing)
|
||||
- **Policy integration:** `docs/policy/dsl.md` §12 for uncertainty gates
|
||||
- **Lattice integration:** `docs/modules/reach-graph/guides/lattice.md` §9 for v1 lattice states
|
||||
|
||||
---
|
||||
|
||||
## 8. Policy Guidance (v1 — Sprint 0401)
|
||||
|
||||
Uncertainty gates enforce evidence-quality thresholds in the Policy Engine. When entropy is too high or evidence is missing, policies block or downgrade VEX decisions.
|
||||
|
||||
### 8.1 Gate Mapping
|
||||
|
||||
| Gate | Uncertainty State | Tier | Policy Action |
|
||||
|------|------------------|------|---------------|
|
||||
| `U1` | `MissingSymbolResolution` | T1/T2 | Block `not_affected`, require review |
|
||||
| `U2` | `MissingPurl` | T2/T3 | Warn on `not_affected`, add review flag |
|
||||
| `U3` | `UntrustedAdvisory` | T3/T4 | Advisory caveat, no blocking |
|
||||
|
||||
### 8.2 Sample Policy Rules
|
||||
|
||||
```dsl
|
||||
// Block not_affected when symbol resolution has high entropy
|
||||
rule u1_gate_high_entropy priority 5 {
|
||||
when signals.uncertainty.level == "U1"
|
||||
and signals.uncertainty.entropy >= 0.7
|
||||
then status := "under_investigation"
|
||||
annotate gate := "U1"
|
||||
annotate remediation := "Upload symbols or close unknowns registry"
|
||||
because "High symbol entropy blocks strong VEX claims";
|
||||
}
|
||||
|
||||
// Tier-based compound gate
|
||||
rule tier1_block_not_affected priority 3 {
|
||||
when signals.uncertainty.aggregateTier == "T1"
|
||||
and vex.any(status == "not_affected")
|
||||
then status := "under_investigation"
|
||||
annotate blocked_reason := "T1 uncertainty requires evidence"
|
||||
because "Maximum uncertainty tier blocks all exclusion claims";
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 YAML Configuration
|
||||
|
||||
```yaml
|
||||
uncertainty_gates:
|
||||
u1_gate:
|
||||
entropy_threshold: 0.7
|
||||
blocked_statuses: [not_affected]
|
||||
fallback_status: under_investigation
|
||||
remediation_hint: "Upload symbols or resolve unknowns"
|
||||
u2_gate:
|
||||
entropy_threshold: 0.4
|
||||
blocked_statuses: [not_affected]
|
||||
warn_on_block: true
|
||||
u3_gate:
|
||||
entropy_threshold: 0.1
|
||||
annotate_caveat: true
|
||||
```
|
||||
|
||||
See `docs/policy/dsl.md` §12 for complete gate rules and tier-aware compound patterns.
|
||||
|
||||
---
|
||||
|
||||
## 9. Remediation Actions
|
||||
|
||||
Each uncertainty state has recommended remediation steps:
|
||||
|
||||
| State | Code | Remediation | CLI Command |
|
||||
|-------|------|-------------|-------------|
|
||||
| MissingSymbolResolution | `U1` | Upload debug symbols, resolve unknowns | `stella symbols ingest --path <symbols>` |
|
||||
| MissingPurl | `U2` | Generate lockfile, verify package coordinates | `stella sbom refresh --resolve` |
|
||||
| UntrustedAdvisory | `U3` | Cross-reference trusted sources | `stella advisory verify --source NVD,GHSA` |
|
||||
| Unknown | `U4` | Run initial analysis | `stella scan --full` |
|
||||
|
||||
### 9.1 Automated Remediation Flow
|
||||
|
||||
```
|
||||
1. Policy blocks decision with U1/U2 gate
|
||||
↓
|
||||
2. Console/CLI shows remediation hint
|
||||
↓
|
||||
3. User runs remediation command (e.g., stella symbols ingest)
|
||||
↓
|
||||
4. Signals recomputes uncertainty states
|
||||
↓
|
||||
5. Risk score updates, tier may drop
|
||||
↓
|
||||
6. Policy re-evaluates, decision may proceed
|
||||
```
|
||||
|
||||
### 9.2 Remediation Priority
|
||||
|
||||
When multiple uncertainty states exist, prioritize by tier:
|
||||
|
||||
1. **T1 states first** — Block all exclusions until resolved
|
||||
2. **T2 states** — May proceed with warnings if T1 cleared
|
||||
3. **T3/T4 states** — Normal flow with caveats
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-12-13 (Sprint 0401).*
|
||||
Reference in New Issue
Block a user