git.stella-ops.org/docs/advisory-ai/sbom-context-hand-off.md

SBOM Context Hand-off for Advisory AI (SBOM-AIAI-31-003)

Updated: 2025-11-24 · Owners: Advisory AI Guild · SBOM Service Guild · Sprint 0111

Defines the contract and smoke test for passing SBOM context from SBOM Service to Advisory AI /v1/sbom/context consumers. Aligns with SBOM-AIAI-31-001 (paths/timelines) and the CLI fixtures published on 2025-11-19.

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-Tenant 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-Tenant: 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-Tenant and API key.
• 429 — clamp exceeded; reduce timelineClamp/dependencyPathClamp or narrow artifactId.

References

• docs/sbom/remediation-heuristics.md (blast-radius scoring).
• docs/advisory-ai/guardrails-and-evidence.md (evidence contract).
• docs/modules/cli/artefacts/guardrails-artefacts-2025-11-19.md (hashes for fixtures).