CLI command reference
This page is generated from the real command-line parser by scripts/generate_cli_docs.py; a test fails if it drifts from the shipped CLI, so what you read here is what --help prints. It covers the primary operator workflow in order. Every other specialist command stays discoverable through the grouped index at the end and sbomflow help <command>.
Offline
Every command here is offline by default. Network access happens only on the
explicit, named flags shown in each command's help (--use-osv, --use-nvd,--use-kev, --use-epss, --resolve-west-imports, or a sync/notify--apply).
sbomflow setup
text
usage: sbomflow setup [-h] [--no-input] [--no-color] [--as-of AS_OF]
[--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION]
[--product-class {default,important-class-i,important-class-ii,critical}]
[--output OUTPUT]
[--style {system,dark,light,high-contrast,ansi,none}]
[target]
Guided, interactive first-run onboarding: detect the product, confirm
identity and output location, preview exactly what will be written, then
run the first offline audit and explain the result.
Reads the target directory.
Writes sbomflow.yaml and the first evidence pack - only after showing
a preview; it refuses to overwrite without confirmation.
Network never.
Exit 0 ok · 2 not a real terminal (use --no-input guidance or
`sbomflow quickstart .` in CI/automation).
Requires a real terminal; it never prompts in CI or redirected IO.
positional arguments:
target Product directory.
options:
-h, --help show this help message and exit
--no-input, --non-interactive
Never prompt; exit with guidance to the scriptable
path (for CI/automation).
--no-color Disable ANSI color output.
--as-of AS_OF Optional ISO timestamp for a deterministic first
audit.
--product-name PRODUCT_NAME
Use this as the editable detected-name default.
--product-version PRODUCT_VERSION
Use this as the editable detected-version default.
--product-class {default,important-class-i,important-class-ii,critical}
Use this as the editable declared-class default;
SBOMFlow does not classify the product.
--output OUTPUT Use this as the editable output-directory default.
--style {system,dark,light,high-contrast,ansi,none}
Use this terminal output style without prompting for a
style.
Example:
sbomflow setup
Next: sbomflow review <output-dir> · open the evidence-bundle.htmlsbomflow quickstart
text
usage: sbomflow quickstart [-h] [--output OUTPUT]
[--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION] [--no-init]
[--zip] [--as-of AS_OF]
[target]
The fastest first run: detect the project type, scaffold sbomflow.yaml
(unless --no-init), run a fully offline audit, and print a short summary.
Reads the target directory only.
Writes sbomflow.yaml next to the project (never overwrites an existing
one) and the evidence pack into --output.
Network never. Non-interactive and CI-safe; it never prompts.
Exit 0 ok · 2 usage/input error.
positional arguments:
target Project directory to scan.
options:
-h, --help show this help message and exit
--output OUTPUT Directory for the evidence pack (default:
<target>/sbomflow-evidence).
--product-name PRODUCT_NAME
Override the auto-detected product name.
--product-version PRODUCT_VERSION
Override the auto-detected product version.
--no-init Do not scaffold sbomflow.yaml (audit with detected
defaults only).
--zip Also write the deterministic bundle zip.
--as-of AS_OF Pinned timestamp for a reproducible first run.
Example:
sbomflow quickstart .
Next: open <output>/evidence-bundle.html · sbomflow review <output>sbomflow doctor
text
usage: sbomflow doctor [-h] [--json] [target]
Report local environment and config facts before a first run: Python
version, optional extras, config discovery/validity, and what a scan
would pick up. It fabricates nothing and changes nothing.
Reads the target directory (or a config file).
Writes nothing.
Network never.
Exit 0 ok · non-zero when a blocking problem is found.
positional arguments:
target Target dir or config file.
options:
-h, --help show this help message and exit
--json Emit machine-readable doctor output.
Example:
sbomflow doctor .
Next: sbomflow quickstart . · sbomflow audit . --output evidencesbomflow init
text
usage: sbomflow init [-h] [--force] [--with-review-templates]
[--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION]
[--product-class {default,important-class-i,important-class-ii,critical}]
[target]
positional arguments:
target Directory to initialize.
options:
-h, --help show this help message and exit
--force Overwrite an existing sbomflow.yaml.
--with-review-templates
Write TEMPLATE reviewer files with no real decisions.
--product-name PRODUCT_NAME
Initial product.name value.
--product-version PRODUCT_VERSION
Initial product.version value.
--product-class {default,important-class-i,important-class-ii,critical}
Initial declared product.class value.sbomflow validate-config
text
usage: sbomflow validate-config [-h] path
positional arguments:
path Config file to validate.
options:
-h, --help show this help message and exitsbomflow audit
text
usage: sbomflow audit [-h] --output OUTPUT [--config CONFIG]
[--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION]
[--product-class {default,important-class-i,important-class-ii,critical}]
[--as-of AS_OF] [--import-sbom IMPORT_SBOMS]
[--supplier-vex SUPPLIER_VEX]
[--test-results TEST_RESULTS]
[--build-provenance BUILD_PROVENANCE]
[--build-provenance-public-key BUILD_PROVENANCE_PUBLIC_KEY]
[--support-policy SUPPORT_POLICY] [--offline]
[--use-osv] [--osv-timeout OSV_TIMEOUT]
[--osv-base-url OSV_BASE_URL]
[--osv-cache-dir OSV_CACHE_DIR] [--use-nvd]
[--nvd-file NVD_FILE] [--nvd-timeout NVD_TIMEOUT]
[--nvd-base-url NVD_BASE_URL] [--use-kev]
[--kev-file KEV_FILE] [--use-epss]
[--epss-file EPSS_FILE] [--resolve-west-imports]
[--west-name-allowlist WEST_NAME_ALLOWLIST]
[--west-name-blocklist WEST_NAME_BLOCKLIST]
[--release-id RELEASE_ID]
[--release-channel RELEASE_CHANNEL]
[--release-variant RELEASE_VARIANT]
[--build-id BUILD_ID]
[--source-repository SOURCE_REPOSITORY]
[--source-revision SOURCE_REVISION]
[--build-started-at BUILD_STARTED_AT]
[--build-finished-at BUILD_FINISHED_AT]
[--support-period-ends-at SUPPORT_PERIOD_ENDS_AT]
[--previous-output PREVIOUS_OUTPUT] [--reviews REVIEWS]
[--vulnerability-reviews VULNERABILITY_REVIEWS]
[--reachability-evidence REACHABILITY_EVIDENCE]
[--tree-sitter-reachability] [--approvals APPROVALS]
[--waivers WAIVERS] [--require-role ROLE]
[--policy POLICY] [--policy-profile NAME]
[--fail-on-gaps] [--fail-on-unreviewed]
[--fail-on-vulnerabilities] [--fail-on-kev]
[--fail-on-reachable-vulnerabilities]
[--fail-on-new-vulnerabilities] [--fail-on-new-kev]
[--fail-on-new-reachable-vulnerabilities]
[--fail-on-new-critical-or-high]
[--fail-on-evidence-regression]
[--fail-on-support-period-missing]
[--fail-on-missing-approvals]
[--epss-threshold EPSS_THRESHOLD]
[--severity-threshold {none,low,medium,high,critical}]
[--emit-sarif] [--emit-spdx3] [--emit-traceability]
[--share-profile {importer,distributor}]
[--emit-metrics] [--emit-issues-csv] [--emit-pdf]
[--zip] [--scan-cache-dir SCAN_CACHE_DIR]
[--scan-jobs N] [--strict] [--json]
target
One-command release audit: analyze the build, emit the default evidence
artifacts plus the reviewer bundle, and validate everything it wrote.
Reads the product/build directory, optional sbomflow.yaml, and any
local evidence inputs supplied below.
Writes the evidence pack, SBOMs, reports, and evidence-bundle.* into
--output. It never modifies the scanned tree.
Network none by default. Only the explicit --use-* flags reach the
named public sources; local *-file snapshots stay offline.
Exit 0 ok · 1 enforced gate block · 2 usage/input error ·
3 validation failure · 5 --strict warnings-as-errors.
The audit composes existing deterministic artifacts; it adds no authority
and makes no conformity claim. Human review stays separate and explicit.
positional arguments:
target Product source/build directory to scan.
options:
-h, --help show this help message and exit
product identity & config:
--output OUTPUT Directory for evidence outputs.
--config CONFIG Path to a sbomflow.yaml/.json config file.
--product-name PRODUCT_NAME
Override the product name.
--product-version PRODUCT_VERSION
Override the product version.
--product-class {default,important-class-i,important-class-ii,critical}
Declared product class to record. The engine does not
classify the product.
--as-of AS_OF ISO timestamp to use as 'now' (for
reproducible/freshness-pinned runs).
local evidence inputs (offline; hashed as provenance):
--import-sbom IMPORT_SBOMS
Import a local supplier CycloneDX/SPDX JSON SBOM as
observed evidence. Repeatable.
--supplier-vex SUPPLIER_VEX
Import a local supplier OpenVEX/CSAF VEX document as
context only. Repeatable.
--test-results TEST_RESULTS
Attach a local JUnit XML or TAP result file as
observed test evidence. Repeatable.
--build-provenance BUILD_PROVENANCE
Local in-toto/SLSA-shaped statement or DSSE envelope
to record.
--build-provenance-public-key BUILD_PROVENANCE_PUBLIC_KEY
Local PEM public key for optional DSSE signature
verification (sbomflow[attest]).
--support-policy SUPPORT_POLICY
Local support-policy artifact to hash into the release
record.
advisory & exploitation sources (offline snapshots by default; --use-* reaches the network):
--offline Force offline mode, overriding config.
--use-osv Query the real OSV API (osv.dev) over the network. Off
by default.
--osv-timeout OSV_TIMEOUT
OSV request timeout in seconds.
--osv-base-url OSV_BASE_URL
Override the OSV API base URL.
--osv-cache-dir OSV_CACHE_DIR
Directory to cache OSV records (keyed by id,
invalidated by modified time).
--use-nvd Enrich CVE findings from the live NIST NVD API
(network). Off by default.
--nvd-file NVD_FILE Local NVD API JSON snapshot to enrich offline (no
network).
--nvd-timeout NVD_TIMEOUT
NVD request timeout in seconds.
--nvd-base-url NVD_BASE_URL
Override the NVD CVE API base URL.
--use-kev Enrich findings against the live CISA KEV catalog
(network). Off by default.
--kev-file KEV_FILE Local CISA KEV catalog JSON snapshot to enrich offline
(no network).
--use-epss Enrich findings with live FIRST EPSS scores (network).
Off by default.
--epss-file EPSS_FILE
Local FIRST EPSS snapshot (.csv or .json) to enrich
offline (no network).
--resolve-west-imports
Resolve Zephyr west 'import:' manifests over the
network. Off by default.
--west-name-allowlist WEST_NAME_ALLOWLIST
Comma-separated project names to include from resolved
west imports.
--west-name-blocklist WEST_NAME_BLOCKLIST
Comma-separated project names to exclude from resolved
west imports.
release metadata (declared by you/CI; local/offline):
--release-id RELEASE_ID
Manufacturer/CI-declared release id.
--release-channel RELEASE_CHANNEL
Release channel, e.g. stable/beta.
--release-variant RELEASE_VARIANT
Hardware/software release variant.
--build-id BUILD_ID CI/build-system identifier for this release.
--source-repository SOURCE_REPOSITORY
Source repository URL or local identifier.
--source-revision SOURCE_REVISION
Source revision used for this release.
--build-started-at BUILD_STARTED_AT
Build start timestamp from CI metadata.
--build-finished-at BUILD_FINISHED_AT
Build completion timestamp from CI metadata.
--support-period-ends-at SUPPORT_PERIOD_ENDS_AT
Manufacturer-declared support-period end.
--previous-output PREVIOUS_OUTPUT
Previous SBOMFlow output directory; enables release-
drift.json.
human review & approvals (read here; written by review/approve):
--reviews REVIEWS Evidence reviewer-decisions file to apply.
--vulnerability-reviews VULNERABILITY_REVIEWS
Vulnerability VEX-triage decisions file to apply.
--reachability-evidence REACHABILITY_EVIDENCE
Manufacturer-supplied reachability evidence inputs
(context, never a decision).
--tree-sitter-reachability
Opt in to bounded Tree-sitter C/C++ call-context
observations (sbomflow[reachability]).
--approvals APPROVALS
Release-approval ledger (approvals.json) consulted by
the gate.
--waivers WAIVERS Reviewer-owned waivers file; an unexpired waiver marks
its item 'waived' (still listed).
--require-role ROLE Required release-approval role (repeatable); additive
over a policy profile.
release-gate policy (informational unless a flag is set):
--policy POLICY Standalone named/versioned release-gate policy profile
(.json/.yaml).
--policy-profile NAME
Apply a shipped, versioned policy preset by name.
Overridden by --policy.
--fail-on-gaps Exit non-zero if missing-evidence gaps meet the
severity threshold.
--fail-on-unreviewed Exit non-zero if observed evidence has not been human-
reviewed.
--fail-on-vulnerabilities
Exit non-zero if advisory findings meet the severity
threshold.
--fail-on-kev Exit non-zero if any finding is in the CISA KEV
catalog (known exploited).
--fail-on-reachable-vulnerabilities
Exit non-zero for source-referenced findings meeting
the threshold/policy context.
--fail-on-new-vulnerabilities
Exit non-zero when release drift contains new advisory
findings.
--fail-on-new-kev Exit non-zero when release drift contains newly known-
exploited findings.
--fail-on-new-reachable-vulnerabilities
Exit non-zero when release drift contains newly
source-referenced findings.
--fail-on-new-critical-or-high
Exit non-zero when release drift contains new or
escalated critical/high findings.
--fail-on-evidence-regression
Exit non-zero when release drift contains new gaps,
regressions, or re-review needs.
--fail-on-support-period-missing
Exit non-zero when current release metadata lacks
support_period_ends_at.
--fail-on-missing-approvals
Exit non-zero when required approval roles are unmet
and no override is recorded.
--epss-threshold EPSS_THRESHOLD
Exit non-zero if any finding's FIRST EPSS score is >=
this value (0..1).
--severity-threshold {none,low,medium,high,critical}
Severity floor for --fail-on-gaps / --fail-on-
vulnerabilities (default: low).
extra outputs & sharing (all optional):
--emit-sarif Also write findings.sarif (SARIF 2.1.0) for observed
gaps and findings.
--emit-spdx3 Also write spdx3-sbom.json (SPDX 3.0.1 JSON-LD).
--emit-traceability Also write traceability.json (cross-entity node/edge
index; a derived view).
--share-profile {importer,distributor}
Also write a redacted importer/distributor evidence-
sharing pack (sharing-pack.json/html/zip). Adds no
authority and no conformity claim.
--emit-metrics Also write local metrics.json (aggregate counts, gate
state, phase durations, tool metadata, and declared
release metadata).
--emit-issues-csv Also write issues.csv, a spreadsheet-friendly
projection of issues.json.
--emit-pdf Also write evidence-summary.pdf and include it in the
bundle.
--zip Write evidence-bundle.zip.
performance & cache (never change output bytes):
--scan-cache-dir SCAN_CACHE_DIR
Optional content-addressed scan cache for faster
repeat scans of unchanged files.
--scan-jobs N Hash files with N parallel workers (default 1);
ignored with --scan-cache-dir.
machine output & strictness:
--strict Enforce the manufacturer's strict policy set. This is
not a CRA conformity determination.
--json Emit one machine-readable summary.
Examples:
sbomflow audit . --output evidence --zip
sbomflow audit ./firmware --output out --kev-file kev.json --fail-on-kev
Next: sbomflow review evidence · sbomflow explain evidence --gatesbomflow analyze
text
usage: sbomflow analyze [-h] --output OUTPUT [--config CONFIG]
[--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION]
[--product-class {default,important-class-i,important-class-ii,critical}]
[--use-osv] [--offline] [--resolve-west-imports]
[--west-name-allowlist WEST_NAME_ALLOWLIST]
[--west-name-blocklist WEST_NAME_BLOCKLIST]
[--osv-timeout OSV_TIMEOUT]
[--osv-base-url OSV_BASE_URL]
[--osv-cache-dir OSV_CACHE_DIR]
[--scan-cache-dir SCAN_CACHE_DIR] [--scan-jobs N]
[--use-nvd] [--nvd-file NVD_FILE]
[--nvd-timeout NVD_TIMEOUT]
[--nvd-base-url NVD_BASE_URL] [--policy POLICY]
[--policy-profile NAME] [--use-kev]
[--kev-file KEV_FILE] [--use-epss]
[--epss-file EPSS_FILE] [--reviews REVIEWS]
[--vulnerability-reviews VULNERABILITY_REVIEWS]
[--reachability-evidence REACHABILITY_EVIDENCE]
[--tree-sitter-reachability]
[--ssvc-context SSVC_CONTEXT]
[--import-sbom IMPORT_SBOMS]
[--supplier-vex SUPPLIER_VEX]
[--test-results TEST_RESULTS] [--as-of AS_OF]
[--release-id RELEASE_ID]
[--release-channel RELEASE_CHANNEL]
[--release-variant RELEASE_VARIANT]
[--build-id BUILD_ID]
[--source-repository SOURCE_REPOSITORY]
[--source-revision SOURCE_REVISION]
[--build-started-at BUILD_STARTED_AT]
[--build-finished-at BUILD_FINISHED_AT]
[--support-period-ends-at SUPPORT_PERIOD_ENDS_AT]
[--support-policy SUPPORT_POLICY]
[--previous-output PREVIOUS_OUTPUT]
[--build-provenance BUILD_PROVENANCE]
[--build-provenance-public-key BUILD_PROVENANCE_PUBLIC_KEY]
[--fail-on-gaps] [--fail-on-unreviewed]
[--fail-on-vulnerabilities] [--fail-on-kev]
[--fail-on-reachable-vulnerabilities]
[--fail-on-new-vulnerabilities] [--fail-on-new-kev]
[--fail-on-new-reachable-vulnerabilities]
[--fail-on-new-critical-or-high]
[--fail-on-evidence-regression]
[--fail-on-support-period-missing]
[--fail-on-missing-approvals] [--require-role ROLE]
[--approvals APPROVALS] [--waivers WAIVERS]
[--epss-threshold EPSS_THRESHOLD]
[--severity-threshold {none,low,medium,high,critical}]
[--emit-vex] [--emit-techdoc] [--emit-incident-report]
[--emit-ssvc] [--emit-sarif] [--emit-spdx3]
[--drift-html] [--emit-traceability]
[--emit-issues-csv] [--emit-pdf] [--emit-bundle]
[--share-profile {importer,distributor}]
[--emit-metrics] [--strict [STRICT_WARNINGS]]
target
Scan one product/build directory and write the default deterministic
evidence artifacts (evidence pack, SBOMs, coverage, gate, report, ...).
`sbomflow audit` wraps this with the reviewer bundle and validation.
Reads the target directory, optional sbomflow.yaml, and any local
inputs supplied below. It never modifies the scanned tree.
Writes the evidence artifacts into --output.
Network none by default; only the explicit --use-* flags reach the
named public sources.
Exit 0 ok · 1 enforced gate block · 2 usage/input error ·
5 --strict warnings-as-errors.
positional arguments:
target Product source/build directory to scan.
options:
-h, --help show this help message and exit
--output OUTPUT Directory for evidence outputs.
--config CONFIG Path to a sbomflow.yaml/.json config file.
--product-name PRODUCT_NAME
Override the product name.
--product-version PRODUCT_VERSION
Override the product version.
--product-class {default,important-class-i,important-class-ii,critical}
Declared product class to record. The engine does not
classify the product.
--policy POLICY Standalone named/versioned release-gate policy profile
(.json/.yaml).
--policy-profile NAME
Apply a shipped, versioned policy preset by name (cra-
critical, cra-default, cra-important, strict-ci).
Overridden by --policy; CLI --fail-on-* flags are
additive.
--as-of AS_OF ISO timestamp to use as 'now' (for
reproducible/freshness-pinned runs).
--strict [STRICT_WARNINGS]
Treat scan warnings as errors after artifacts are
written. Use --strict for any warning or
--strict=code1,code2 to scope by warning code
(distinct exit code 5).
OSV advisory lookup & west resolution (network only when enabled):
--use-osv Query the real OSV API (osv.dev) over the network. Off
by default.
--offline Force offline mode (never query OSV or resolve west
imports), overriding config.
--resolve-west-imports
Resolve Zephyr west 'import:' directives over the
network (like --use-osv): fetch each imported manifest
and add its modules as components. Off by default;
dropped under --offline.
--west-name-allowlist WEST_NAME_ALLOWLIST
Comma-separated project names to include from resolved
west imports.
--west-name-blocklist WEST_NAME_BLOCKLIST
Comma-separated project names to exclude from resolved
west imports.
--osv-timeout OSV_TIMEOUT
OSV request timeout in seconds.
--osv-base-url OSV_BASE_URL
Override the OSV API base URL.
--osv-cache-dir OSV_CACHE_DIR
Directory to cache OSV records (keyed by id,
invalidated by modified time).
performance & cache (never change output bytes):
--scan-cache-dir SCAN_CACHE_DIR
Directory for an optional content-addressed scan cache
that speeds repeat scans of unchanged files. The cache
only speeds up scanning; output is byte-identical with
or without it.
--scan-jobs N Hash files with N parallel workers for large trees
(default 1). Output is byte-identical to a single-
threaded scan; ignored when --scan-cache-dir is set.
NVD CVE enrichment (CVSS/CPE context; off by default):
--use-nvd Enrich CVE findings from the live NIST NVD API
(network). Off by default.
--nvd-file NVD_FILE Local NVD API JSON snapshot to enrich offline (no
network).
--nvd-timeout NVD_TIMEOUT
NVD request timeout in seconds.
--nvd-base-url NVD_BASE_URL
Override the NVD CVE API base URL.
exploitation intelligence (CISA KEV / FIRST EPSS; off by default):
--use-kev Enrich findings against the live CISA KEV catalog
(network). Off by default.
--kev-file KEV_FILE Local CISA KEV catalog JSON snapshot to enrich offline
(no network).
--use-epss Enrich findings with live FIRST EPSS scores (network).
Off by default.
--epss-file EPSS_FILE
Local FIRST EPSS snapshot (.csv or .json) to enrich
offline (no network).
local evidence & review inputs (offline; hashed as provenance):
--reviews REVIEWS Path to an evidence reviewer-decisions file.
--vulnerability-reviews VULNERABILITY_REVIEWS
Path to a vulnerability VEX-triage decisions file (for
--emit-vex).
--reachability-evidence REACHABILITY_EVIDENCE
Path to manufacturer-supplied reachability evidence
inputs.
--tree-sitter-reachability
Opt in to bounded Tree-sitter C/C++ call-context
observations. Requires sbomflow[reachability]; regex
scanning remains the baseline.
--ssvc-context SSVC_CONTEXT
Path to manufacturer SSVC context (Automatable /
Mission & Well-being defaults and optional per-finding
overrides) for --emit-ssvc.
--import-sbom IMPORT_SBOMS
Import a local supplier CycloneDX/SPDX JSON SBOM as
observed component evidence. Repeatable; offline and
local-file-only.
--supplier-vex SUPPLIER_VEX
Import a local supplier OpenVEX/CSAF JSON VEX document
as context for matching findings. Repeatable; never
suppresses gates by itself.
--test-results TEST_RESULTS
Attach a local JUnit XML or TAP test-result file as
observed security-test evidence for human review.
Repeatable; offline only.
release history metadata (local/offline):
--release-id RELEASE_ID
Manufacturer/CI-declared release id.
--release-channel RELEASE_CHANNEL
Release channel, e.g. stable/beta.
--release-variant RELEASE_VARIANT
Hardware/software release variant.
--build-id BUILD_ID CI/build-system identifier for this release.
--source-repository SOURCE_REPOSITORY
Source repository URL or local identifier.
--source-revision SOURCE_REVISION
Source revision used for this release.
--build-started-at BUILD_STARTED_AT
Build start timestamp from CI metadata.
--build-finished-at BUILD_FINISHED_AT
Build completion timestamp from CI metadata.
--support-period-ends-at SUPPORT_PERIOD_ENDS_AT
Manufacturer-declared support-period end.
--support-policy SUPPORT_POLICY
Local support-policy artifact to hash into the release
record.
--previous-output PREVIOUS_OUTPUT
Previous SBOMFlow output directory used to emit
release-drift.json.
--build-provenance BUILD_PROVENANCE
Local in-toto/SLSA-shaped statement or DSSE envelope
to record.
--build-provenance-public-key BUILD_PROVENANCE_PUBLIC_KEY
Local PEM public key for optional DSSE build-
provenance signature verification. Requires
sbomflow[attest].
release gate (non-blocking unless a flag is set):
--fail-on-gaps Exit non-zero if missing-evidence gaps meet the
severity threshold.
--fail-on-unreviewed Exit non-zero if observed evidence has not been human-
reviewed.
--fail-on-vulnerabilities
Exit non-zero if advisory findings meet the severity
threshold.
--fail-on-kev Exit non-zero if any finding is in the CISA KEV
catalog (known exploited).
--fail-on-reachable-vulnerabilities
Exit non-zero for source-referenced advisory findings
that meet the severity threshold or enabled KEV/EPSS
policy context.
--fail-on-new-vulnerabilities
Exit non-zero when release drift contains new advisory
findings.
--fail-on-new-kev Exit non-zero when release drift contains newly known-
exploited findings.
--fail-on-new-reachable-vulnerabilities
Exit non-zero when release drift contains newly
source-referenced findings.
--fail-on-new-critical-or-high
Exit non-zero when release drift contains new or
escalated critical/high findings.
--fail-on-evidence-regression
Exit non-zero when release drift contains new gaps,
status regressions, or re-review needs.
--fail-on-support-period-missing
Exit non-zero when current release metadata lacks
support_period_ends_at.
--fail-on-missing-approvals
Exit non-zero when required release-approval roles are
unmet (or a separation-of-duties violation exists) and
no active override is recorded.
--require-role ROLE Required release-approval role (repeatable); additive
over a policy profile.
--approvals APPROVALS
Release-approval ledger (approvals.json) consulted by
the gate.
--waivers WAIVERS Reviewer-owned waivers file (waivers.json) consulted
by the gate. An unexpired waiver moves its exact
gap/finding to 'waived' (still listed); it never
accepts evidence, sets VEX, or claims conformity.
--epss-threshold EPSS_THRESHOLD
Exit non-zero if any finding's FIRST EPSS score is >=
this value (0..1).
--severity-threshold {none,low,medium,high,critical}
Severity floor for --fail-on-gaps / --fail-on-
vulnerabilities (default: low).
extra outputs & exports (all optional):
--emit-vex Also write vex.json (OpenVEX; all statements default
to under_investigation).
--emit-techdoc Also write the CRA Annex VII technical-documentation
pack index and UNSIGNED DRAFT EU declaration
workspace.
--emit-incident-report
Also write the CRA Article 14 UNSIGNED DRAFT
incident/vulnerability notification pack (early
warning / notification / final report). SBOMFlow never
files, transmits, or submits any report.
--emit-ssvc Also write ssvc.json: a suggested CISA SSVC action
priority (Track / Track* / Attend / Act) per finding
for human review. Not a remediation mandate and not a
conformity claim.
--emit-sarif Also write findings.sarif (SARIF 2.1.0) for observed
gaps and vulnerability findings. SARIF level is
severity, not a release decision.
--emit-spdx3 Also write spdx3-sbom.json (SPDX 3.0.1 JSON-LD). SPDX
2.3 remains the default SBOM for broad
interoperability.
--drift-html When release drift is produced (with --previous-
output), also write release-drift.html, a human-
readable release-diff report.
--emit-traceability Also write traceability.json: a cross-entity node/edge
index linking product, release, components,
vulnerabilities, requirements, evidence, gaps, issues,
and scanned source bytes. A derived view that adds no
claims.
--emit-issues-csv Also write issues.csv, a spreadsheet-friendly
projection of issues.json. This is a data export only,
not a release or legal decision.
--emit-pdf Also write evidence-summary.pdf, a deterministic text
summary for auditor handoff. HTML/JSON stay canonical;
the PDF adds no claims.
--emit-bundle Also write evidence-bundle.json/html for reviewer
handoff.
--share-profile {importer,distributor}
Also write a redacted importer/distributor evidence-
sharing pack (sharing-pack.json/html/zip): a
documented SBOM subset plus coverage summary,
declaration-draft status, and support period. Internal
reviewer notes are redacted; it adds no authority and
no conformity claim.
--emit-metrics Also write local metrics.json with aggregate counts,
gate state, phase durations, tool metadata, and
declared release metadata (no source content,
credentials, or contact details; inspect release
metadata before sharing).
Examples:
sbomflow analyze . --output out --product-name Gateway --product-version 2.4.1
sbomflow analyze ./build --output out --previous-output out-prev --drift-html
Next: sbomflow review out · sbomflow explain out --gate · sbomflow bundle outsbomflow review
text
usage: sbomflow review [-h] [--reviews REVIEWS]
[--vulnerability-reviews VULNERABILITY_REVIEWS]
[--accept KEY] [--reject KEY]
[--needs-more-evidence KEY] [--triage VULN_ID]
[--status {affected,fixed,not_affected,under_investigation}]
[--justification JUSTIFICATION]
[--evidence-ref EVIDENCE_REF] [--waive-gap GAP_ID]
[--waive-finding VULN_ID] [--reason REASON]
[--expires-at EXPIRES_AT] [--reviewer REVIEWER]
[--note NOTE] [--reviewed-at REVIEWED_AT]
[--assign ROLE] [--as-of AS_OF] [--json]
output_dir
Show what still needs a human decision, or record exactly one decision.
Reads an existing analyze/audit output directory.
Writes review-queue.json always; a decision appends to reviews.json /
vulnerability_reviews.json / waivers.json plus a hash-chained
audit event. It records YOUR decision - it never decides.
Network never.
Exit 0 ok · 2 usage/invalid decision (e.g. not_affected without a
valid CISA justification is refused).
With no decision flags this is read-only apart from review-queue.json.
positional arguments:
output_dir Directory produced by 'analyze'/'audit'.
options:
-h, --help show this help message and exit
--reviews REVIEWS Evidence reviews file to read/update (default:
<output>/reviews.json).
--vulnerability-reviews VULNERABILITY_REVIEWS
Vulnerability VEX-triage file to read/update (default:
<output>/vulnerability_reviews.json).
--reviewer REVIEWER Reviewer identity recorded with the decision.
--note NOTE Reviewer note recorded with the decision.
--reviewed-at REVIEWED_AT
ISO timestamp for the decision (default: now/--as-of).
--assign ROLE Annotate the queue with an assigned reviewer role.
--as-of AS_OF Pinned timestamp for the queue / audit event.
--json Emit the review queue as JSON.
record one decision (omit all of these to just show the queue):
--accept KEY Accept the evidence item with this key.
--reject KEY Reject the evidence item with this key.
--needs-more-evidence KEY
Mark the evidence item with this key as needing more
evidence.
--triage VULN_ID Record a VEX triage decision for this vulnerability id
(with --status).
--status {affected,fixed,not_affected,under_investigation}
VEX status for --triage.
--justification JUSTIFICATION
CISA justification (required when --status
not_affected).
--evidence-ref EVIDENCE_REF
Optional evidence reference for a VEX triage.
--waive-gap GAP_ID Record a time-boxed waiver for this gap id (requires
--reason and --expires-at).
--waive-finding VULN_ID
Record a time-boxed waiver for this finding id
(requires --reason and --expires-at).
--reason REASON Mandatory reason recorded with a waiver.
--expires-at EXPIRES_AT
Mandatory ISO expiry recorded with a waiver.
Examples:
sbomflow review ./evidence
sbomflow review ./evidence --accept secure_boot_configured \
--reviewer you@example.com --note "Verified fuses."
Next: re-run your gate with --reviews ./evidence/reviews.json, or
sbomflow approve ./evidence --role product-security --reviewer you@orgsbomflow approve
text
usage: sbomflow approve [-h] [--approvals APPROVALS] [--require-role ROLE]
[--policy POLICY] [--role ROLE] [--revoke]
[--override] [--reviewer REVIEWER] [--author AUTHOR]
[--expires-at EXPIRES_AT] [--reason REASON]
[--note NOTE] [--as-of AS_OF] [--json]
output_dir
Show multi-role release-approval status, or record one sign-off action.
Reads an existing analyze/audit output directory.
Writes approvals.json plus a hash-chained audit event when an action
is recorded; status display alone writes nothing.
Network never.
Exit 0 ok · 2 usage error or refused action (separation of duties:
an approver may not be the declared release author, and one
reviewer may not cover two required roles).
SBOMFlow records the sign-off; it never grants an approval itself. An
override lets the gate proceed but never hides the missing roles.
positional arguments:
output_dir Directory produced by 'analyze'/'audit'.
options:
-h, --help show this help message and exit
--approvals APPROVALS
Approval ledger to read/update (default:
<output>/approvals.json).
--require-role ROLE Required role(s) for the status display (repeatable).
--policy POLICY Policy profile supplying required_approval_roles for
the status display.
--reviewer REVIEWER Reviewer identity recorded with the action.
--author AUTHOR Declared release author (separation of duties: an
approver may not be the author).
--expires-at EXPIRES_AT
Optional ISO expiry for an approval or override.
--reason REASON Reason for a revocation, or the mandatory override
reason.
--note NOTE Optional note recorded with an approval.
--as-of AS_OF Pinned timestamp for the status / audit event.
--json Emit the approval status as JSON.
record one action (omit all of these to just show the approval status):
--role ROLE Role to approve, or to revoke with --revoke.
--revoke Revoke the active approval for --role.
--override Record an emergency override of missing approvals
(requires --reason).
Examples:
sbomflow approve ./evidence --require-role product-security
sbomflow approve ./evidence --role product-security --reviewer sec@org
Next: enforce with `sbomflow audit . --output evidence \
--require-role product-security --fail-on-missing-approvals`sbomflow explain
text
usage: sbomflow explain [-h] (--gap GAP_ID | --finding VULN_ID | --gate)
output_dir
Print a sourced, human-readable explanation of one gap, finding, or the
gate decision - composed purely from existing artifacts (no AI).
Reads an existing analyze/audit output directory.
Writes nothing.
Network never.
Exit 0 ok · 2 unknown id / missing artifacts.
positional arguments:
output_dir Directory produced by 'analyze'.
options:
-h, --help show this help message and exit
--gap GAP_ID Explain this evidence gap id.
--finding VULN_ID Explain this advisory finding id/alias.
--gate Explain release-gate.json.
Examples:
sbomflow explain ./evidence --gate
sbomflow explain ./evidence --finding CVE-2024-29041
Next: sbomflow review ./evidence to record the human decision.sbomflow bundle
text
usage: sbomflow bundle [-h] [--zip ZIP] [--as-of AS_OF] output_dir
Create or refresh the portable reviewer handoff (evidence-bundle.json,
evidence-bundle.html, optional deterministic ZIP) for an existing run.
Reads an existing analyze/audit output directory.
Writes evidence-bundle.* into that directory (and the ZIP if asked).
Network never.
Exit 0 ok · 2 usage/input error.
A bundle copies and hashes existing artifacts; it adds no authority and
no new claims.
positional arguments:
output_dir Directory produced by analyze/audit.
options:
-h, --help show this help message and exit
--zip ZIP Optional path for a deterministic evidence ZIP.
--as-of AS_OF Pinned ZIP timestamp.
Example:
sbomflow bundle ./evidence --zip ./evidence/evidence-bundle.zip
Next: sbomflow verify-bundle ./evidence · share the ZIP with your reviewersbomflow validate
text
usage: sbomflow validate [-h] output_dir
positional arguments:
output_dir Directory produced by 'analyze'.
options:
-h, --help show this help message and exitsbomflow compare-releases
text
usage: sbomflow compare-releases [-h] --previous PREVIOUS --current CURRENT
--output OUTPUT [--html] [--as-of AS_OF]
Compare two existing runs of the same product and report what changed:
components, findings, KEV/EPSS, reachability, gaps, reviews to recheck,
support period, artifact hashes, and gate policy.
Reads two analyze/audit output directories.
Writes release-drift.json (and release-drift.html with --html) into
--output.
Network never.
Exit 0 ok · 2 usage/input error.
Drift is comparison context only - it never replaces human review or
closes tracker issues.
options:
-h, --help show this help message and exit
--previous PREVIOUS Previous output directory.
--current CURRENT Current output directory.
--output OUTPUT Directory for release-drift.json.
--html Also write release-drift.html, a human-readable
release-diff report.
--as-of AS_OF Pinned comparison timestamp.
Example:
sbomflow compare-releases --previous out/v1 --current out/v2 \
--output out/drift --html
Next: sbomflow explain out/v2 --gate · review new findings in out/v2Every command, grouped
The full command surface, exactly as sbomflow help prints it:
text
SBOMFlow — offline-by-default cybersecurity release evidence.
Engineering evidence only; not a conformity claim, not legal advice.
Start: sbomflow setup guided interactive onboarding (a real terminal)
sbomflow quickstart . auto-detect, scaffold config, run an offline audit
sbomflow audit . --output evidence full offline evidence pack for one release
Get started:
setup Guided interactive first-run onboarding (a real terminal only; never in CI).
quickstart First run: detect the project, scaffold config, run an offline audit, summarize.
doctor Run offline environment/config preflight checks.
init Scaffold sbomflow.yaml and optional reviewer templates.
validate-config Validate a sbomflow.yaml/.json config file.
Core evidence loop:
audit Run analyze + full opt-in packs + bundle + validation in one command.
analyze Analyze a product directory.
explain Explain one gap, finding, or release gate decision from existing artifacts.
review Show the review queue for an output dir, or record a human sign-off decision (writes review-queue.json + an audit event).
review-view Render a single-file static reviewer console (reviewer.html) for an output dir — queue, evidence, findings, CRA coverage, gate, approvals, and the audit trail. Read-only; no server, no JavaScript, no network.
approve Show release-approval status for an output dir, or record a human approval / revocation / emergency override (writes approvals.json + an audit event).
store Local, file-based evidence store: accumulate release outputs and query across products/releases. Deterministic, offline, no database.
Compare & track releases:
compare-releases Compare two SBOMFlow output directories and write release-drift.json.
index-releases Build a local release-index.json from SBOMFlow output directories.
index Build/validate/query the derived SQLite evidence index (JSON stays canonical).
dashboard Render a static release dashboard from release-index.json or output directories.
portfolio Aggregate several products/releases (from a portfolio config) into a cross-product index + dashboard.
Validate & integrity:
validate Validate a generated evidence output directory.
validate-graph Validate the packaged or supplied CRA requirement graph.
validate-techdoc-model Validate the packaged or supplied CRA Annex VII technical-documentation model.
validate-article14-model Validate the packaged or supplied CRA Article 14 reporting model.
validate-ssvc-model Validate the packaged or supplied CISA SSVC coordinator decision model.
verify-package-artifacts Verify lockfile-recorded digests against operator-supplied local package cache directories. Offline and observation-only.
provenance-check Check an in-toto/SLSA provenance statement against expectations (offline; no SLSA level claimed).
reproducible-compare Compare two independent build-output trees by artifact digest (offline).
Share / auditor handoff:
bundle Create or refresh reviewer evidence-bundle artifacts for an output dir.
sign-bundle Sign evidence-bundle.json with a local PEM private key (optional sbomflow[sign] extra).
verify-bundle Verify an evidence bundle's integrity (stdlib tamper check) and, with --key, its signature.
auditor-pack Build a self-contained, read-only auditor package (auditor-pack.zip) an auditor opens in a browser with no SBOMFlow install: the redacted sharing pack + the reviewer console behind a landing page, with file hashes.
Integrations / sync:
sync-issues Sync evidence-gap issues to GitHub (dry run by default; --apply to push).
sync-jira Export (or, with --apply, sync) a Jira issue plan from issues.json.
sync-servicenow Export (or, with --apply, sync) a ServiceNow Table API plan from issues.json.
sync-dependencytrack Plan or upload cyclonedx-sbom.json to OWASP Dependency-Track.
notify Plan (and optionally deliver) review-queue/gate notifications for an output dir.
Embedded & build inputs:
cmake-evidence Import a CMake File API reply into deterministic build evidence (offline).
linker-map-evidence Parse a GNU ld / LLVM lld map into a deterministic object/section graph (offline).
zephyr-evidence Import a Zephyr `west spdx` set into deterministic build evidence (offline).
twister-evidence Import Zephyr Twister results (twister.json) into deterministic test evidence (offline).
esp-idf-evidence Import ESP-IDF build outputs into deterministic evidence (offline; no secrets copied).
oci-evidence Discover manifests/platforms/referrers in a local OCI image layout (offline; layers never executed).
ingest-sarif Ingest a SARIF 2.1.0 log (CodeQL/Semgrep/clang-tidy/…) as sourced observations (offline).
mcuboot-evidence Parse an MCUboot image into deterministic firmware evidence (offline; never executed).
mcuboot-verify Verify an MCUboot image's integrity + (opt-in) signature against an operator key.
firmware-extract Optional: inventory bounded binwalk/unblob extraction output (never executed or retained).
update-manifest-evidence Parse local TUF metadata or an IETF SUIT CBOR envelope into bounded observations.
rauc-evidence Parse an exact RAUC manifest.raucm artifact (offline; no CMS verification).
swupdate-evidence Parse an SWUpdate .swu newc/crc cpio or sw-description artifact.
mender-evidence Inspect a Mender Artifact tar in memory without extracting or executing it.
uptane-evidence Parse separate Uptane Director/Image repository metadata observations.
syft-scan Optional: discover components via Syft and ingest its CycloneDX output (never required).
cosign-verify Optional: verify a blob against a local key + offline Sigstore bundle via cosign (never required).
diffoscope-compare Optional: explain differences between two artifacts via diffoscope (never required).
prov-map Map a traceability.json to a documented W3C PROV-DM subset (model guidance; offline).
Vulnerability data:
vulndb Manage local pinned vulnerability-data snapshots (OSV dump / CVE List V5).
Maintenance:
upgrade Inspect/plan/migrate-copy/validate old output dirs to the current schemas (offline; never in place).
help Show grouped help, help for one command, or `help error <code>` (offline).
Docs: https://sbomflow.com/docs · `sbomflow help <command>` for details
`sbomflow help error <code>` explains an error code offline.