git.stella-ops.org/docs/sbom/remediation-heuristics.md

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.