Remediation Heuristics for Advisory AI

Updated: 2025-11-24 · Owners: Docs Guild, SBOM Service Guild · Ref: DOCS-AIAI-31-008 (Sprint 0111)

This guide defines the deterministic remediation heuristics that Stella Ops Advisory AI applies when SBOM context is available. It is written for SBOM Service and Advisory AI integrators who need to understand — and reproduce — how remediation suggestions are scored and ranked.

The heuristics align with the SBOM path/timeline endpoints (SBOM-AIAI-31-001) and the CLI fixtures shipped in CLI-VULN-29-001. All outputs are deterministic and reproducible offline from the inputs below.

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:

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.