work

docs/sbom/remediation-heuristics.md

@@ -0,0 +1,43 @@
+# Remediation Heuristics for Advisory AI (DOCS-AIAI-31-008)
+
+_Updated: 2025-11-24 · Owners: Docs Guild · SBOM Service Guild · Sprint 0111_
+
+This note defines the deterministic remediation heuristics Advisory AI applies when SBOM context is present. It aligns with `SBOM-AIAI-31-001` (path/timeline endpoints) and the CLI fixtures shipped in `CLI-VULN-29-001`.
+
+## Inputs
+- SBOM context document (schema `stellaops.sbom.context/1.0`), e.g. `out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json` (SHA256 `421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18`).
+- Version timelines from `/sbom/versions?artifactId=...` (clamped to 500 entries by default).
+- Dependency paths from `/sbom/paths?artifactId=...` (clamped to 200 paths by default).
+- Advisory/VEX evidence from Link-Not-Merge (`advisory_observations`, `advisory_linksets`).
+
+## Heuristics (deterministic)
+1) **Blast radius score** per package
+   - `score = (directPaths * 2) + transitivePaths + exposedRuntimeHint`
+   - `exposedRuntimeHint = 3` when the runtime signal `exposure=external` is present, else `0`.
+   - Scores are capped at `20` to keep ordering stable.
+
+2) **Fix candidate ranking**
+   - Prefer vendor fixed versions present in timeline; fall back to highest patch version above current.
+   - Reject candidates that would **increase** blast radius by adding new transitive edges (>10% increase).
+   - If no fix exists, emit `advisory.remediation.noFixAvailable` and cite the timeline.
+
+3) **Configuration-only mitigations**
+   - When VEX status is `not_affected` **and** blast radius score < 5, recommend configuration hardening (feature flags, admission policy) instead of upgrades.
+
+4) **Refusal conditions**
+   - Missing SBOM context → return deterministic remediation with `sbomSummary` counts set to 0 and note `contextUnavailable` in metadata.
+   - Timeline gaps (non-monotonic dates or hashes) → `409 advisory.contextHashMismatch` with the offending hash list.
+
+## Example (offline fixture)
+Using `sample-sbom-context.json`:
+
+| Package | Paths | Blast radius | Suggested action |
+| --- | --- | --- | --- |
+| openssl@1.1.1w | 2 direct, 4 transitive | `(2*2)+4 = 8` | Upgrade to vendor fixed `1.1.1x` (from timeline); verify after replacement. |
+| zlib@1.2.11 | 1 direct, 2 transitive | `(1*2)+2 = 4` | Apply VEX `not_affected` justification if available; otherwise patch to `1.2.12`. |
+
+## Operator checklist
+- Export SBOM context and hashes into Offline Kit (`offline-kit/advisory-ai/fixtures/sbom-context/`).
+- Verify clamps: `timelineClamp=500`, `dependencyPathClamp=200` unless explicitly overridden in `AdvisoryAI:Tasks:Remediation`.
+- Record blast-radius scores in audit logs when remediation is generated (helps replay).
+- Keep fixtures in sync with CLI guardrail artefact hashes and note any override in sprint Execution Log.