44 lines
2.8 KiB
Markdown
44 lines
2.8 KiB
Markdown
# 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.
|