42 lines
1.5 KiB
Markdown
42 lines
1.5 KiB
Markdown
# SBOM Lineage Ledger Guide
|
|
|
|
## Purpose
|
|
- Track historical SBOM versions per artifact with deterministic diffs and lineage edges.
|
|
- Support BYOS uploads for SPDX/CycloneDX inputs while preserving audit history.
|
|
|
|
## Upload workflow
|
|
- Endpoint: `POST /sbom/upload` or `POST /api/v1/sbom/upload`.
|
|
- Required fields: `artifactRef`, `sbom` (JSON object) or `sbomBase64`.
|
|
|
|
Example payload:
|
|
```json
|
|
{
|
|
"artifactRef": "acme/app:1.0",
|
|
"sbom": { "bomFormat": "CycloneDX", "specVersion": "1.6", "components": [] },
|
|
"format": "cyclonedx",
|
|
"source": { "tool": "syft", "version": "1.0.0" }
|
|
}
|
|
```
|
|
|
|
## Ledger queries
|
|
- `GET /sbom/ledger/history?artifact=...&limit=...&cursor=...`
|
|
- `GET /sbom/ledger/point?artifact=...&at=...`
|
|
- `GET /sbom/ledger/range?artifact=...&start=...&end=...&limit=...&cursor=...`
|
|
- `GET /sbom/ledger/diff?before=...&after=...`
|
|
- `GET /sbom/ledger/lineage?artifact=...`
|
|
|
|
## Lineage semantics
|
|
- Versions are chained per artifact; parent references create lineage edges.
|
|
- Graph Indexer maps ledger lineage into:
|
|
- `SBOM_VERSION_OF` edges from SBOM to artifact.
|
|
- `SBOM_LINEAGE_*` edges (e.g., `SBOM_LINEAGE_PARENT`).
|
|
|
|
## Retention policy
|
|
- Apply with `POST /internal/sbom/retention/prune`.
|
|
- Settings: `SbomService:Ledger:MaxVersionsPerArtifact`, `MaxAgeDays`, `MinVersionsToKeep`.
|
|
- Audit is available via `GET /internal/sbom/ledger/audit`.
|
|
|
|
## Determinism
|
|
- Versions are ordered by sequence and UTC timestamps.
|
|
- Diffs are ordered by component key for stable output.
|