SBOM Context Hand-off for Advisory AI

Advisory AI grounds its remediation reasoning in SBOM context — the dependency paths and timelines that show where a vulnerable component lives and how it reaches the surface. That context is produced by the SBOM Service and handed to Advisory AI over a deterministic, hashed contract. This guide defines that contract, its headers and failure modes, and the smoke test that proves the hand-off works in both connected and offline tenants.

Audience: operators wiring Advisory AI to the SBOM Service, and engineers maintaining the SBOM context contract.

Status & Next Steps (2025-12-08)

• ✅ 2025-12-08: Real SbomService /sbom/context run (dotnet run --no-build on http://127.0.0.1:5090) using sample-sbom-context.json scope. Response hash sha256:0c705259fdf984bf300baba0abf484fc3bbae977cf8a0a2d1877481f552d600d captured with timeline + dependency paths.
  • Evidence: evidence-locker/sbom-context/2025-12-05-smoke.ndjson (2025-12-08 entry) and raw payload evidence-locker/sbom-context/2025-12-08-response.json.
  • Offline kit mirror: offline-kit/advisory-ai/fixtures/sbom-context/2025-12-08/ (CLI guardrail fixtures, new sbom-context-response.json, and SHA256SUMS manifest).
• 2025-12-05 run (fixture-backed stub) remains archived in the same NDJSON/logs for traceability.

Contract

• Endpoint (SBOM Service): /sbom/context
• Request (minimal):

{
  "artifactId": "registry.stella-ops.internal/runtime/api",
  "purl": "pkg:oci/runtime-api@sha256:d2c3...",
  "timelineClamp": 500,
  "dependencyPathClamp": 200
}

• Response (summarised):

{
  "schema": "stellaops.sbom.context/1.0",
  "generated": "2025-11-19T00:00:00Z",
  "packages": [
    {"name":"openssl","version":"1.1.1w","purl":"pkg:deb/openssl@1.1.1w"},
    {"name":"zlib","version":"1.2.11","purl":"pkg:deb/zlib@1.2.11"}
  ],
  "timeline": 8,
  "dependencyPaths": 5,
  "hash": "sha256:421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18"
}

• Determinism: clamp values fixed unless overridden; generated timestamp frozen per fixture when offline.
• Headers: X-StellaOps-TenantId required; X-StellaOps-ApiKey optional for bootstrap.

Smoke test (tenants/offline)

1. Start SBOM Service with fixture data loaded (or use sample-sbom-context.json).
2. Run: curl -s -H "X-StellaOps-TenantId: demo" -H "Content-Type: application/json" \ -d @out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json \ http://localhost:8080/sbom/context | jq .hash (expect sha256:421a...9d18).
3. Configure Advisory AI:
   • AdvisoryAI:SBOM:BaseAddress=http://localhost:8080
   • AdvisoryAI:SBOM:ApiKey=<key-if-required>
4. Call Advisory AI cache-only: stella advise run remediation --advisory-key csaf:redhat:RHSA-2025:1001 --artifact-id registry.stella-ops.internal/runtime/api --timeout 0 --json.
   • Expect exit 0 and sbomSummary.dependencyPaths=5 in response.
5. Record the hash and endpoint in ops log; mirror fixture + hashes into Offline Kit under offline-kit/advisory-ai/fixtures/sbom-context/.

Failure modes

• 409 advisory.contextHashMismatch — occurs when the returned hash differs from the LNM linkset provenanceHash; refresh context or re-export.
• 403 — tenant/api key mismatch; check X-StellaOps-TenantId and API key.
• 429 — clamp exceeded; reduce timelineClamp/dependencyPathClamp or narrow artifactId.

References

• SBOM Service remediation heuristics — blast-radius scoring.
• Advisory AI guardrails & evidence — the evidence contract this hand-off feeds.
• CLI guardrail artefacts (2025-11-19) — fixture hashes.
• Packaging & SBOM Bundle — how the SBOM context client config ships in the Offline Kit.