Your first offline audit

This walks through producing an evidence bundle from a product directory, fully offline.

Fastest path: quickstart#

quickstart auto-detects your project, scaffolds a minimal sbomflow.yaml with placeholders, runs an offline audit, and prints next steps:

sbomflow quickstart .

Before it writes anything, quickstart prints what it is about to do: the resolved scan root, where the evidence pack goes, which build inputs were detected, a bounded count of the in-scope files, the offline network posture, and whether anything already sits at the output path. Nothing is created until that disclosure has been printed and the run is allowed to proceed.

Naming a directory, and what happens if you do not#

Naming a directory is the shape scripts and CI should use, and it is never questioned:

sbomflow quickstart ./my-product

A run with no directory would use whichever directory you happen to be in. That is the ambiguous case, so:

• at a real terminal, quickstart asks you to confirm the scope it just printed;
• with output redirected, in CI, or anywhere without a terminal, it refuses rather than blocking on an answer that can never arrive. Name the directory, or accept the printed scope in advance:

sbomflow quickstart --yes

--yes skips the question, never the disclosure — the scope is still printed in full, so a CI log records what was scanned. Declining the confirmation writes nothing and is not an error: the command exits 0 with nothing created.

Or use the guided, interactive setup (a real terminal only — see Interactive setup):

sbomflow setup

Run a full audit#

sbomflow audit ./my-product \
  --output ./evidence \
  --product-name "My Gateway" \
  --product-version "1.0.0" \
  --product-class default

This writes a directory of provenance-bearing artifacts, including evidence-pack.json, cyclonedx-sbom.json, spdx-sbom.json, cra-coverage.json, issues.json, release-gate.json, and a portable evidence-bundle.*. Add --as-of <ISO-8601> when you need byte-reproducible release artifacts from pinned inputs and run context. See Read an evidence bundle.

Re-running into the same output directory#

Every evidence directory carries an exact .sbomflow-output marker. When that directory is inside the product tree, a later audit records one named excluded_sbomflow_output disposition and does not re-ingest its own reports as product evidence. Re-running an unchanged project with the same --as-of and inputs is therefore safe and byte-reproducible.

The exclusion is deliberately narrow. A lookalike marker is not trusted, and generic build/ or dist/ directories are not hidden wholesale: recognized lockfiles and embedded build evidence inside them are still scanned.

Offline vs. opt-in enrichment#

Exit codes#

The audit uses stable exit codes. A 0 means the run completed or a gate was informational; a 1 means an enforced release gate blocked the run. Common input mistakes return 2 with a stable error code and a fix.

If your first run fails#

The two most common first-run mistakes explain themselves: pointing at a path that does not exist (E001) or at a single file instead of the product directory (E002). Every failure prints its code, a one-line fix, and a docs link — and the same explanation is available offline:

sbomflow help error E001
sbomflow doctor .

doctor reports your environment and config facts (Python version, optional extras, discovered config and its problems) and is the first thing to run when a failure does not explain itself. The troubleshooting guide maps every symptom to a fix.

Next#

Read an evidence bundle · Core concepts