56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
# 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.
|
|
|
|
## Contract
|
|
- **Endpoint** (SBOM Service): `/sbom/context`
|
|
- **Request** (minimal):
|
|
```json
|
|
{
|
|
"artifactId": "registry.stella-ops.internal/runtime/api",
|
|
"purl": "pkg:oci/runtime-api@sha256:d2c3...",
|
|
"timelineClamp": 500,
|
|
"dependencyPathClamp": 200
|
|
}
|
|
```
|
|
- **Response** (summarised):
|
|
```json
|
|
{
|
|
"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).
|