# 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:

{
  "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.