sbom-nexus/README.md

sbom-nexus

SBOM Nexus is the dedicated software-bill-of-materials service for the Coulomb fleet. It captures dependency evidence from repositories, keeps immutable snapshots, evaluates licence risk and freshness, and provides a bounded catch-up queue for automation.

The product direction is defined in INTENT.md. The first delivery contract is in ProductRequirementsDocument.md.

Development

uv sync --dev
uv run pytest
uv run ruff check src tests
uv run sbom-nexus serve --reload

The default API listens on http://127.0.0.1:8010. Local development uses SQLite through SBOM_NEXUS_DATABASE_PATH; production uses SBOM_NEXUS_DATABASE_URL_FILE=/var/run/secrets/.../url and make migrate. The direct SBOM_NEXUS_DATABASE_URL variable remains available for disposable development environments; mounted secret files are preferred for production. The runtime rereads the mounted file for every new database connection and recycles pooled connections every 300 seconds by default, configurable with SBOM_NEXUS_DATABASE_POOL_RECYCLE_SECONDS.

Initial API surface

• GET /state/health
• GET /state/live
• PUT /repositories/{repo_slug}
• GET /sbom/catch-up?limit=3
• POST /sbom/{repo_slug}/ingest
• State Hub-compatible /sbom/ snapshot, entry, repository, and licence routes

Authoritative automation may ingest a controlled forgejo-archive-v1 source_ref pinned to a full commit SHA. Nexus constructs the Forgejo URL, streams and safely extracts the archive within configured limits, records the archive and manifest provenance, and removes the transient directory. It does not accept arbitrary source URLs. Idempotency-Key is durably enforced on repository ingest and skip operations; a matching retry replays the original snapshot outcome and conflicting key reuse returns HTTP 409.

See docs/state-hub-sbom-extraction-review.md for the extraction inventory and cutover dispositions.