up

docs/policy/effective-severity.md

@@ -0,0 +1,56 @@
+# Effective Severity Selection
+
+Last updated: 2025-11-25 (Docs Tasks Md.V)
+
+## Goal
+Provide a deterministic, explainable way to pick the *effective* severity for a vulnerability or VEX observation when multiple signals exist (CVSS, KEV, exploit intel, VEX status, asset criticality, policy overrides).
+
+## Inputs
+- **Base scores**: CVSS v3/v4 (base + temporal) and ecosystem-native severities (npm/yarn, PyPI, Maven). Missing scores are treated as `null`.
+- **Exploitability**: KEV flag, EPSS probability, in-the-wild sightings, vendor exploit flags.
+- **VEX status**: `not_affected`, `affected`, `fixed`, `under_investigation`, `unknown` (per OpenVEX/CSAF/CycloneDX-VEX).
+- **Context signals**: asset criticality, exposure surface (`internet`, `intranet`, `airgap`), runtime enablement flag, workload type.
+- **Policy overrides**: tenant/org rules (allow lists, waiver ids, force-upgrade requirements, SLA class).
+
+## Algorithm (deterministic)
+1) **Normalize** all scores to a 0–10 float with 3-decimal rounding; store provenance for each signal.
+2) **VEX gate**
+   - `not_affected` → effective severity `None` (score 0). Short-circuit unless override `force_evaluate=true`.
+   - `fixed` → keep score but add mitigation note.
+3) **Exploit boost**: if `KEV=true` or `EPSS >= 0.7`, set `exploit_boost = +1.0` (cap at 10). Record reason.
+4) **Exposure clamp**
+   - `airgap` → max score 7.0 unless override `allow_airgap_breakglass`.
+   - `intranet` → no cap; `internet` → no cap.
+5) **Criticality weight**: multiply by asset criticality weight (default 1.0; high=1.2, medium=1.0, low=0.8). Clamp 0–10.
+6) **Policy override**: apply explicit tenant rules (force severity, waive to `None`, or constrain max). Overrides always log the applied rule id.
+7) **Bucket** into severity bands (stable mapping):
+
+| Score range (inclusive) | Band |
+| --- | --- |
+| 9.0–10.0 | Critical |
+| 7.0–8.9  | High |
+| 4.0–6.9  | Medium |
+| 0.1–3.9  | Low |
+| 0        | None |
+
+All arithmetic uses `decimal` and rounds only when persisted or returned (3 decimals) to stay replayable.
+
+## Examples
+- CVSS 7.5 + KEV + internet + high criticality → base 7.5 → +1.0 exploit → *before clamp* 8.5 → ×1.2 = 10.2 → clamp 10.0 → **Critical**.
+- CVSS 5.0, `not_affected` VEX → short-circuit to **None** (score 0) with rationale `vex:not_affected`.
+- No CVSS, EPSS 0.2, exposure `airgap` → default score 0, band **None**; remains deterministic.
+
+## Observability
+- Emit `stellaops.policy.effective_severity` histogram (0–10) with tags `tenant`, `source`, `vex_status`, `kev`, `epss_bucket`, `criticality`, `override_id`.
+- Log structured event `severity.selected` containing input signals, applied steps, final score/band.
+- Traces: span attribute `severity.score` and `severity.band`; link to upstream ingest span (`traceparent` propagated).
+
+## Determinism & Offline posture
+- No live network lookups during evaluation; KEV/EPSS/VEX feeds must be preloaded from frozen bundles.
+- Sorting of tied severities: break ties by subject id (lexicographic) then source priority (`vex` > `kev` > `cvss` > `ecosystem`).
+- All timestamps are UTC ISO-8601; caches keyed by `(tenant, subject, advisory)`.
+
+## Contract for consumers
+- API and CLI MUST return both the raw inputs and the chosen band/score so auditors can replay decisions.
+- Downstream UIs should surface the rationale chain (steps 2–6) and any overrides applied.
+- Waivers must reference the override id that changed the severity.