@stll/provenance

provenance is a CLI that generates SBOMs and third-party notices for JavaScript and Rust repositories, and checks that committed outputs stay current.

It is designed to be deterministic, repo-friendly, and boring to operate.

Scope

The current baseline focuses on:

• JavaScript projects and workspaces
• Rust crates and workspaces
• Mixed JS/Rust repositories
• Optional container image SBOM generation via syft

The workflow is file-based:

• one config file
• deterministic generated outputs
• no direct CI pushes to main
• repo-friendly generate, check, and diff flows

Boundaries

• THIRD-PARTY-NOTICES is a generated inventory of detected third-party components and declared license identifiers. It is not legal advice, and some licenses may require additional attribution text at distribution time.
• The safest canonical outputs come from a controlled CI or release environment, especially when your dependency graph includes platform-specific packages.
• notice.internal_scopes can be used to exclude first-party scoped packages from generated notices and repo SBOM component inventories.
• The JavaScript SBOM reflects whatever is present in node_modules at generation time. Install production dependencies only before running (for example bun install --frozen-lockfile --production, or npm ci --omit=dev) so the generated SBOM and notices describe the shipped closure and do not include development-only dependencies. For JavaScript projects the tool does not pass cdxgen --required-only, because for bun lockfiles that flag drops shipped transitive dependencies (and production dependencies imported only from type-declaration or test files) instead of dev dependencies. Non-JavaScript projects (for example Rust crates) keep --required-only; mixed JavaScript/Rust projects apply the equivalent required-scope filter only to Cargo components after generation.
• sbom.exclude_regexes can be used to exclude generated runtime artifacts such as wasm/dist/ outputs or root-level *.wasi-browser.js files from SBOM evidence so post-build checks stay deterministic.
• output_dir must point to a dedicated directory such as provenance; the tool refuses to write managed outputs directly into the repository root.

Installation

Download a pinned binary from GitHub Releases for CI and automation.

Example for Linux x64:

curl -fsSL -o /tmp/provenance.tar.gz \
  https://github.com/stella/provenance/releases/download/v0.1.0/provenance-v0.1.0-x86_64-unknown-linux-gnu.tar.gz
tar -xzf /tmp/provenance.tar.gz -C /tmp
install /tmp/provenance-v0.1.0-x86_64-unknown-linux-gnu/provenance ~/.local/bin/provenance

To build or install from source instead:

cargo install --git https://github.com/stella/provenance --locked

For local development:

cargo install --path .

Runtime prerequisites

The CLI itself is a single Rust binary. Analysis still depends on ecosystem tooling:

• cdxgen for JavaScript and Rust SBOM generation
  • supported discovery order: cdxgen, bunx @cyclonedx/cdxgen, npx --yes @cyclonedx/cdxgen
• syft for optional container SBOMs

You can also point the CLI at explicit binaries:

• PROVENANCE_CDXGEN=/path/to/cdxgen
• PROVENANCE_SYFT=/path/to/syft

Quick Start

provenance init
provenance generate

provenance init discovers JavaScript and Rust projects under the current root and writes .provenance.yml.

provenance generate writes deterministic compliance artifacts into the configured output directory.

For ongoing verification:

provenance check
provenance diff

Generated outputs

For a single-project repo:

• provenance/sbom.cdx.json
• provenance/THIRD-PARTY-NOTICES.txt

For multi-project repos:

• provenance/projects/<id>/sbom.cdx.json
• provenance/projects/<id>/THIRD-PARTY-NOTICES.txt

For each configured container:

• provenance/containers/<name>/sbom.cdx.json
• provenance/containers/<name>/THIRD-PARTY-NOTICES.txt

Repo-level outputs:

• provenance/report.json

When there is more than one project or any configured containers:

• provenance/THIRD-PARTY-NOTICES.repo.txt

CI model

The recommended flow is:

1. run provenance generate when dependency inputs change
2. commit the generated outputs
3. run provenance check in CI

This repo follows that model directly in GitHub Actions.

Development

cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --test integration_real -- --ignored
cargo doc --no-deps
cargo deny check
cargo package --locked