SBOM lineage ledger

Overview

• Tracks immutable SBOM versions per artifact reference.
• Exposes history, temporal queries, and deterministic diffs.
• Emits lineage edges to support graph joins and audit trails.

Endpoints

• GET /sbom/ledger/history?artifact=<ref>&limit=50&cursor=0
• GET /sbom/ledger/point?artifact=<ref>&at=<iso8601>
• GET /sbom/ledger/range?artifact=<ref>&start=<iso8601>&end=<iso8601>
• GET /sbom/ledger/diff?before=<versionId>&after=<versionId>
• GET /sbom/ledger/lineage?artifact=<ref>

Lineage relationships

The ledger lineage response uses the names in SbomLineageRelationships (src/SbomService/StellaOps.SbomService/Models/SbomLedgerModels.cs):

• parent: explicit parent version link (supplied at ingest, for example parentArtifactDigest).
• build: versions emitted from the same CI build ID (from upload provenance).
• base is defined but not emitted by /sbom/ledger/lineage. Base-image relationships supplied at upload (baseImageDigest) are persisted as digest-keyed sbom.lineage_edges rows and appear in the lineage graph API (GET /api/v1/lineage/{artifactDigest}).

Example lineage response

{
  "artifactRef": "example.com/app:1.2.3",
  "nodes": [{ "versionId": "v1", "sequenceNumber": 1, "digest": "sha256:..." }],
  "edges": [{ "fromVersionId": "v1", "toVersionId": "v2", "relationship": "build" }]
}

Notes

• Ledger storage is durable PostgreSQL (sbom.ledger_versions, sbom.ledger_chains, sbom.lineage_edges in database stellaops_sbomservice). In-memory repositories are used only by the explicit Development/Testing local harness.
• Every ledger read requires sbom:read and is scoped to the authenticated tenant; each (tenant, artifact) pair has its own chain.
• Ordering is deterministic by sequence number, then timestamp.
• See also ledger-lineage.md and architecture.md.