stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
0536a4f7d49d70626da316f42b66c6c6019d128c
git.stella-ops.org/docs/modules/sbomservice/ledger-lineage.md

1.5 KiB
Raw Blame History

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.