CLI command reference
This page is generated from the real command-line parser; a drift test fails if it falls behind the shipped CLI, so what you read here is exactly 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.html
Network behavior: offline. This command has no network-capable path.sbomflow quickstart#
text
usage: sbomflow quickstart [-h] [--output OUTPUT] [--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION] [--no-init] [--zip] [--tour]
[--as-of AS_OF] [--ci {github}] [--force] [--yes] [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.
First the scope (scan root, output, detected inputs, bounded count,
network posture, what already exists) is disclosed BEFORE the
first write.
Asks only when no target is given: naming a directory, or --yes,
proceeds without a question, so scripts and CI never prompt.
Network never.
Exit 0 ok (including a declined confirmation) · 2 usage/input error.
positional arguments:
target Project directory to scan (default: the current
directory).
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.
--tour After the summary, print a numbered, copy-paste guided
tour through the release workflow, filled with this
run's real paths. Pure print, CI-safe.
--as-of AS_OF Pinned timestamp for a reproducible first run.
--ci {github} Instead of auditing, emit a ready-to-commit CI
workflow (offline audit + gate + PR annotations +
evidence upload). Currently: github.
--force With --ci, overwrite an existing workflow file
(default: refuse).
--yes Accept the disclosed scope without being asked. Only a
run with no target given is ever asked; the disclosure
itself is always printed.
Examples:
sbomflow quickstart .
sbomflow quickstart --yes
no target: accept the disclosed scope
Next: open <output>/evidence-bundle.html · sbomflow review <output>
Network behavior: offline. This command has no network-capable path.sbomflow doctor#
text
usage: sbomflow doctor [-h] [--json] [--pilot] [--fix] [--apply]
[--release-manifest RELEASE_MANIFEST] [--public-key PUBLIC_KEYS]
[--vulndb-dir VULNDB_DIR] [--analysis-control PATH]
[--observed-at TIMESTAMP] [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, unless --fix or --pilot is given (see below).
Network never.
Exit 0 ok · non-zero when a blocking problem is found.
--pilot adds the machine-checkable half of the PILOT.md checklist: a
smoke analysis of a synthetic product, a pinned determinism double-run,
disk space, and target writability (a temporary directory and a
deleted write-probe in the target). It reports whether the ENVIRONMENT
is ready — never the product, the evidence, or the review workflow.
--fix prints a plan of provably safe, reversible remediations (a
mischosen config-key casing, a missing inert *.TEMPLATE.json review
scaffold) — never a reviewer decision file or evidence artifact.
--apply executes only the actions still valid at apply time; a
precondition that has drifted since the plan was built is skipped
with a reason, and every other action still proceeds.
--analysis-control PATH runs the offline runtime control receipt: a
packaged reserved synthetic corpus is executed in a throwaway
directory and PATH records which named controls THIS INSTALLATION
could perform. It reads no customer project and reaches no verdict
about one. Exit 0 only when every declared control passed; a written
degraded/failed/indeterminate receipt exits 6.
positional arguments:
target Target dir or config file.
options:
-h, --help show this help message and exit
--json Emit machine-readable doctor output.
--pilot Also run the design-partner pilot preflight: smoke
analysis, pinned determinism double-run, disk space,
and target writability. Checks the environment only,
never product or evidence readiness.
--fix Print a plan of safe, reversible remediations. Print-
first: plans nothing to disk by itself.
--apply With --fix, execute the plan's still-valid actions
(skips any with a drifted precondition).
--release-manifest RELEASE_MANIFEST
Signed release-manifest.json to compare the installed
version and local vulndb snapshot against, fully
offline (never fetched, never auto-updated).
--public-key PUBLIC_KEYS
PEM public key to trust for --release-manifest
verification (repeatable).
--vulndb-dir VULNDB_DIR
Local vulndb snapshot directory for --release-manifest
freshness comparison (default: .sbomflow-vulndb,
matching `sbomflow vulndb --dir`).
--analysis-control PATH
Run the offline runtime control receipt against the
packaged reserved diagnostic corpus and write it to
PATH. Reads no customer project, writes nothing else,
and reaches no verdict about any product.
--observed-at TIMESTAMP
Observation time to record on the --analysis-control
receipt (RFC 3339). Omitted, no time is recorded
rather than invented.
Example:
sbomflow doctor .
sbomflow doctor . --pilot
sbomflow doctor . --fix
sbomflow doctor . --fix --apply
sbomflow doctor . --analysis-control analysis-control-receipt.json
Next: sbomflow quickstart . · sbomflow audit . --output evidence
Network behavior: offline. This command has no network-capable path.sbomflow init#
text
usage: sbomflow init [-h] [--force] [--with-review-templates]
[--with-source-stubs] [--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.
--with-source-stubs Write TEMPLATE gap-owner routing and reviewer-role
policy stubs (no 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.
Network behavior: offline. This command has no network-capable path.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 exit
Network behavior: offline. This command has no network-capable path.sbomflow audit#
text
usage: sbomflow audit [-h] [--report-theme {light,dark}] --output OUTPUT
[--on-existing-output {overlay,clean,refuse}] [--config CONFIG]
[--store DIR] [--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]
[--import-custom-manifest IMPORT_CUSTOM_MANIFESTS]
[--supplier-vex SUPPLIER_VEX] [--test-results TEST_RESULTS]
[--ai-manifest AI_MANIFEST]
[--debian-tracker-snapshot DEBIAN_TRACKER_SNAPSHOT]
[--alpine-secdb-snapshot ALPINE_SECDB_SNAPSHOTS]
[--build-provenance BUILD_PROVENANCE]
[--build-provenance-public-key BUILD_PROVENANCE_PUBLIC_KEY]
[--support-policy SUPPORT_POLICY] [--offline] [--use-osv]
[--use-sample-feed] [--osv-snapshot OSV_SNAPSHOT]
[--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]
[--gate-dry-run] [--fail-on-gaps] [--fail-on-unreviewed]
[--fail-on-vulnerabilities] [--fail-on-kev] [--fail-on-denied-license]
[--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-mlbom] [--emit-aibom] [--emit-traceability]
[--share-profile {importer,distributor,customer}] [--emit-metrics]
[--emit-issues-csv] [--emit-pdf] [--zip]
[--scan-cache-dir SCAN_CACHE_DIR] [--scan-jobs N] [--strict]
[--break-stale-lock] [--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.
Shorter view: `sbomflow help audit` — required inputs, common options and the
option groups by job; `sbomflow help audit <group>` opens one group. Nothing
is hidden there: that layer is shorter, not smaller.
positional arguments:
target Product source/build directory to scan.
options:
-h, --help show this help message and exit
--report-theme {light,dark}
Palette for generated HTML surfaces (default: light).
Print output is always light.
--break-stale-lock Remove a provably-stale .sbomflow.lock (crashed run)
from the output directory before running. Never
automatic; confirm no other run is active first.
product identity & config:
--output OUTPUT Directory for evidence outputs.
--on-existing-output {overlay,clean,refuse}
What to do when --output already holds a previous run:
overlay (default, write over it), clean (first remove
SBOMFlow's own artifacts, never your files), or refuse
(write nothing, exit 2).
--config CONFIG Path to a sbomflow.yaml/.json config file.
--store DIR Local evidence store holding prior releases of this
product. When given, writes cross-release context
(offline, read-only): evidence-aging.json (releases
since a human last accepted each requirement),
finding-regressions.json (resolved findings that
reappeared), and carry-forward.json (prior human
decisions on findings seen again here).
--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.
--import-custom-manifest IMPORT_CUSTOM_MANIFESTS
Import a local SBOMFlow custom manifest (explicit
component + dependency evidence). Repeatable; offline.
--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.
--ai-manifest AI_MANIFEST
Read a local declared AI manifest (models, datasets,
prompts, services, agents) and record it beside what
the scan observed, in `ai-evidence.json`. Offline: one
local file, no lookup. A declaration is what somebody
SAID; where it disagrees with an observation both are
kept and the disagreement is surfaced for a human,
never resolved.
--debian-tracker-snapshot DEBIAN_TRACKER_SNAPSHOT
Read a pinned local Debian security-tracker JSON
snapshot and annotate findings with the distro's
patched-status (no network).
--alpine-secdb-snapshot ALPINE_SECDB_SNAPSHOTS
Read a pinned local Alpine secdb branch file and
annotate findings with the distro's patched-status (no
network). 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.
--use-sample-feed Use the bundled SYNTHETIC sample advisory feed (CVE-
SAMPLE-*). Illustrative demo/example data only, never
intelligence about your product.
--osv-snapshot OSV_SNAPSHOT
Local OSV-format advisory snapshot (JSON list,
{'vulns': [...]}, or JSONL) matched offline with the
range engine instead of the non-real sample feed.
Config: osv.snapshot. Never a live lookup.
--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.
--gate-dry-run Rehearse the gate: evaluate and report fully, mark
release-gate.json dry_run, and always exit 0 (never
blocks). For CI adoption before enforcing.
--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-denied-license
Exit non-zero if a component declares a license on
your policy's license_policy.deny list (engineering
context against your own list, never legal advice;
only for single valid SPDX expressions).
--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-mlbom Also write cyclonedx-mlbom.json (CycloneDX 1.6 ML-BOM;
BOM-Linked to the SBOM).
--emit-aibom Also write spdx3-aibom.json (SPDX 3.0.1 AI + Dataset
profiles).
--emit-traceability Also write traceability.json (cross-entity node/edge
index; a derived view).
--share-profile {importer,distributor,customer}
Also write a redacted evidence-sharing pack for the
chosen profile (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 --gate
Network behavior: opt-in-network. The default path is offline; only the listed
flags/config enable egress. Gates: --use-osv, --use-nvd, --use-kev,
--use-epss, --resolve-west-imports, config: osv/nvd enabled with
scan.offline=false, config: exploitation.use_kev/use_epss=true.sbomflow analyze#
text
usage: sbomflow analyze [-h] [--report-theme {light,dark}] --output OUTPUT
[--on-existing-output {overlay,clean,refuse}] [--config CONFIG]
[--store DIR] [--product-name PRODUCT_NAME]
[--product-version PRODUCT_VERSION]
[--product-class {default,important-class-i,important-class-ii,critical}]
[--use-osv] [--use-sample-feed] [--osv-snapshot OSV_SNAPSHOT] [--offline]
[--resolve-west-imports] [--west-import-dir DIR]
[--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]
[--ai-manifest AI_MANIFEST]
[--debian-tracker-snapshot DEBIAN_TRACKER_SNAPSHOT]
[--alpine-secdb-snapshot ALPINE_SECDB_SNAPSHOTS]
[--tree-sitter-reachability] [--ssvc-context SSVC_CONTEXT]
[--incident-awareness-at INCIDENT_AWARENESS_AT]
[--incident-measure-available-at INCIDENT_MEASURE_AVAILABLE_AT]
[--incident-notification-submitted-at INCIDENT_NOTIFICATION_SUBMITTED_AT]
[--import-sbom IMPORT_SBOMS]
[--import-custom-manifest IMPORT_CUSTOM_MANIFESTS]
[--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]
[--gate-dry-run] [--fail-on-gaps] [--fail-on-unreviewed]
[--fail-on-vulnerabilities] [--fail-on-kev] [--fail-on-denied-license]
[--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-vdr] [--emit-techdoc] [--emit-incident-report] [--emit-ssvc]
[--emit-sarif] [--emit-spdx3] [--emit-mlbom] [--emit-aibom]
[--drift-html] [--emit-traceability] [--emit-issues-csv] [--emit-pdf]
[--emit-bundle] [--share-profile {importer,distributor,customer}]
[--emit-metrics] [--break-stale-lock] [--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.
Shorter view: `sbomflow help analyze` — required inputs, common options and
the option groups by job; `sbomflow help analyze <group>` opens one group.
Nothing is hidden there: that layer is shorter, not smaller.
positional arguments:
target Product source/build directory to scan.
options:
-h, --help show this help message and exit
--report-theme {light,dark}
Palette for generated HTML surfaces (default: light).
Print output is always light.
--output OUTPUT Directory for evidence outputs.
--on-existing-output {overlay,clean,refuse}
What to do when --output already holds a previous run:
overlay (default, write over it), clean (first remove
SBOMFlow's own artifacts, never your files), or refuse
(write nothing, exit 2).
--config CONFIG Path to a sbomflow.yaml/.json config file.
--store DIR Local evidence store holding prior releases of this
product. When given, writes cross-release context
(offline, read-only): evidence-aging.json (releases
since a human last accepted each requirement),
finding-regressions.json (resolved findings that
reappeared), and carry-forward.json (prior human
decisions on findings seen again here).
--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).
--break-stale-lock Remove a provably-stale .sbomflow.lock (crashed run)
from the output directory before running. Never
automatic; confirm no other run is active first.
--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.
--use-sample-feed Use the bundled SYNTHETIC sample advisory feed (CVE-
SAMPLE-*). Illustrative demo/example data only, never
intelligence about your product: artifacts mark it
synthetic and it never counts as usable intelligence.
Without a real source (--use-osv/--osv-snapshot) and
without this flag, no advisory matching is performed
at all.
--osv-snapshot OSV_SNAPSHOT
Local OSV-format advisory snapshot (JSON list,
{'vulns': [...]}, or JSONL) matched offline with the
range engine instead of the non-real sample feed.
Config: osv.snapshot. Never a live lookup.
--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-import-dir DIR
Resolve Zephyr west 'import:' directives from a local
mirror instead of the network: DIR holds one checkout
per project (DIR/<project>/west.yml). Stays OFFLINE
and never falls back to the network. Mutually
exclusive with --resolve-west-imports.
--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.
--ai-manifest AI_MANIFEST
Read a local declared AI manifest (models, datasets,
prompts, services, agents) and record it beside what
the scan observed, in `ai-evidence.json`. Offline: one
local file, no lookup. A declaration is what somebody
SAID; where it disagrees with an observation both are
kept and the disagreement is surfaced for a human,
never resolved.
--debian-tracker-snapshot DEBIAN_TRACKER_SNAPSHOT
Read a pinned local Debian security-tracker JSON
snapshot and annotate findings with the distro's
patched-status (no network).
--alpine-secdb-snapshot ALPINE_SECDB_SNAPSHOTS
Read a pinned local Alpine secdb branch file and
annotate findings with the distro's patched-status (no
network). Repeatable.
--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.
--incident-awareness-at INCIDENT_AWARENESS_AT
Instant the manufacturer recorded becoming aware.
Starts the CRA Article 14 24-hour and 72-hour windows
shown in --emit-incident-report. Recorded by you;
never inferred, and never a decision that anything is
reportable.
--incident-measure-available-at INCIDENT_MEASURE_AVAILABLE_AT
Instant a corrective or mitigating measure became
available. Starts the Article 14(2)(c) 14-day final-
report window (actively exploited vulnerability track)
— which does NOT run from awareness.
--incident-notification-submitted-at INCIDENT_NOTIFICATION_SUBMITTED_AT
Instant the manufacturer recorded submitting the
Article 14(4)(b) incident notification, elsewhere.
Starts the Article 14(4)(c) one-month final-report
window (severe-incident track). Recording it here is a
note to yourself; SBOMFlow never submits anything.
--import-sbom IMPORT_SBOMS
Import a local supplier CycloneDX/SPDX JSON SBOM as
observed component evidence. Repeatable; offline and
local-file-only.
--import-custom-manifest IMPORT_CUSTOM_MANIFESTS
Import a local SBOMFlow custom manifest (sbomflow-
custom-manifest v1): explicit component + dependency
evidence a manufacturer declares directly. Repeatable;
offline and local-file-only. See
docs/CUSTOM_MANIFEST.md.
--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):
--gate-dry-run Rehearse the gate: evaluate and report fully, mark
release-gate.json dry_run, and always exit 0 (never
blocks). For CI adoption before enforcing.
--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-denied-license
Exit non-zero if a component declares a license on
your policy's license_policy.deny list (engineering
context against your own list, never legal advice;
only for single valid SPDX expressions).
--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-vdr Also write cyclonedx-vdr.json (CycloneDX Vulnerability
Disclosure Report: every known finding, including
untriaged ones, which carry no analysis).
--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.
--emit-mlbom Also write cyclonedx-mlbom.json: a CycloneDX 1.6 ML-
BOM over the AI evidence graph. Links to the software
SBOM by BOM-Link; never copies its components. An
inventory, not a safety or conformity claim.
--emit-aibom Also write spdx3-aibom.json: an SPDX 3.0.1 AI +
Dataset profile document over the same AI evidence
graph. Add --emit-spdx3 to have it import that
document's product element instead of restating it.
--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,customer}
Also write a redacted evidence-sharing pack for the
chosen profile (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 out
Network behavior: opt-in-network. The default path is offline; only the listed
flags/config enable egress. Gates: --use-osv, --use-nvd, --use-kev,
--use-epss, --resolve-west-imports, config: osv/nvd enabled with
scan.offline=false, config: exploitation.use_kev/use_epss=true.sbomflow review#
text
usage: sbomflow review [-h] [--template CISA_JUSTIFICATION] [--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]
[--renew-waiver-gap GAP_ID] [--renew-waiver-finding VULN_ID]
[--revoke-waiver-gap GAP_ID] [--revoke-waiver-finding VULN_ID]
[--dispute-match FINDING_KEY] [--reason REASON] [--expires-at EXPIRES_AT]
[--start KEY] [--as ROLE] [--force] [--bulk FILE] [--reviewer REVIEWER]
[--note NOTE] [--reviewed-at REVIEWED_AT] [--idempotency-key KEY]
[--assign ROLE] [--as-of AS_OF] [--filter EXPR|@name] [--store DIR]
[--json] [--digest] [--since SINCE] [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.
Shorter view: `sbomflow help review` — required inputs, common options and the
option groups by job; `sbomflow help review <group>` opens one group. Nothing
is hidden there: that layer is shorter, not smaller.
positional arguments:
output_dir Directory produced by 'analyze'/'audit' (omit only
with --template).
options:
-h, --help show this help message and exit
--template CISA_JUSTIFICATION
Print a starting justification scaffold for the given
CISA category and exit (you edit it into a real
explanation; it is never submitted).
--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).
--idempotency-key KEY
Optional stable key so a retried vulnerability triage
converges to ONE operation instead of recording a
second one. Same key + same decision returns the
existing operation; same key + a different decision is
refused. 1-128 chars [A-Za-z0-9._-]. SCOPE:
convergence is per OUTPUT DIRECTORY — the same key
used against a different output dir is a separate
operation, not a retry (TASK-FT-AUTH-03).
--assign ROLE Annotate the queue with an assigned reviewer role.
--as-of AS_OF Pinned timestamp for the queue / audit event.
--filter EXPR|@name Narrow the queue view with comma-joined FIELD OP VALUE
terms (severity/epss/kev/status/ssvc/kind/assigned/com
ponent), e.g. 'severity>=high,kev=true'; or @name for
a filter saved under review.filters in sbomflow.yaml.
A filter narrows what you look at — it never changes a
decision, a status, or the gate.
--store DIR Local evidence store to read prior reviewer decisions
from (offline). Surfaces this product's earlier per-
finding decisions as review context; it never
suppresses a finding or changes VEX status.
--json Emit the review queue as JSON.
--digest Print a session digest of decisions recorded in this
audit log (accepted/rejected/needs-more-evidence,
findings triaged, waivers, approvals), grouped with
event-hash references, and write session-digest.md.
Read-only; records nothing.
--since SINCE With --digest: only include decisions recorded at or
after this ISO-8601 timestamp.
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).
--renew-waiver-gap GAP_ID
Renew the existing waiver for this gap id with a fresh
--reason and a later --expires-at (the reason must
differ from the one it renews).
--renew-waiver-finding VULN_ID
Renew the existing waiver for this finding id with a
fresh --reason and a later --expires-at (the reason
must differ from the one it renews).
--revoke-waiver-gap GAP_ID
Revoke the existing waiver for this gap id (requires
--reason and --reviewer). The record stays in
waivers.json marked revoked — history preserved — and
immediately stops applying; a revoked waiver cannot be
renewed (record a fresh waiver instead).
--revoke-waiver-finding VULN_ID
Revoke the existing waiver for this finding id
(requires --reason and --reviewer). The record stays
in waivers.json marked revoked — history preserved —
and immediately stops applying; a revoked waiver
cannot be renewed (record a fresh waiver instead).
--dispute-match FINDING_KEY
Dispute the advisory match itself for this finding_key
(requires --reason and --reviewer: a dispute
suppresses a blocking finding, so it must name the
human who asserted the match is wrong). Distinct from
VEX: excludes the finding from vex.json/cyclonedx-
vex.json/csaf-vex.json entirely, labels it (never
excludes it) in cyclonedx-vdr.json, and suppresses it
from the gate under its own disputed_matches list;
reappears automatically if the match evidence
(aliases/range/purl) changes on a later run.
--reason REASON Mandatory reason recorded with a waiver, a waiver
revocation, or a match dispute.
--expires-at EXPIRES_AT
Mandatory ISO expiry recorded with a waiver.
--start KEY Claim an evidence key, vulnerability id, or gap id:
moves it to 'in_review' so two reviewers don't
silently duplicate work (requires --as ROLE). A claim
carries no evidence authority — it never accepts
evidence or sets a status.
--as ROLE Reviewer role claiming the item with --start.
--force With --start: reclaim an item already claimed by
someone else (the prior claim stays in the audit log).
--bulk FILE Record many VEX triage decisions from a pre-reviewed
.csv or .json worksheet (columns/keys: finding_key,
status, justification, reviewer, note, evidence_ref —
finding_key is the vulnerability id, same as
--triage). Each row is validated and recorded
independently with its own audit event; invalid rows
are listed and skipped, valid rows still apply. There
is no 'accept all' — every row states its own status
and justification.
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@org
Network behavior: offline. This command has no network-capable path.sbomflow approve#
text
usage: sbomflow approve [-h] [--approvals APPROVALS] [--require-role ROLE]
[--policy POLICY] [--role ROLE] [--revoke] [--override]
[--reviewer REVIEWER] [--author AUTHOR] [--delegate-of REVIEWER]
[--expires-at EXPIRES_AT] [--reason REASON] [--note NOTE]
[--idempotency-key KEY] [--as-of AS_OF] [--json] [--export-audit DIR]
[--format {csv,json}] [--share-profile {importer,distributor,customer}]
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.
Shorter view: `sbomflow help approve` — required inputs, common options and
the option groups by job; `sbomflow help approve <group>` opens one group.
Nothing is hidden there: that layer is shorter, not smaller.
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. MANDATORY
when approving a role and when recording --override:
an unattributed approval satisfies no role, and an
unattributed override suppresses nothing. Optional
only for --revoke, which withdraws authority and so
fails closed.
--author AUTHOR Declared release author (separation of duties: an
approver may not be the author).
--delegate-of REVIEWER
Record this approval as a delegate standing in for
REVIEWER (e.g. a release manager on leave). Requires
--expires-at (delegation is always time-boxed);
delegating for someone who is themselves currently
delegating is refused (one hop only).
--expires-at EXPIRES_AT
ISO expiry. Optional for an approval; MANDATORY for
--override and with --delegate-of.
--reason REASON Reason for a revocation, or the mandatory override
reason.
--note NOTE Optional note recorded with an approval.
--idempotency-key KEY
Optional stable key so a retried approval or
revocation converges to ONE operation instead of
recording a second. Same key + same action returns the
existing operation; same key + a different action is
refused. 1-128 chars [A-Za-z0-9._-]. SCOPE:
convergence is per OUTPUT DIRECTORY — the same key
used against a different output dir is a separate
operation, not a retry (TASK-FT-AUTH-03).
--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).
auditor export (restates recorded sign-offs; writes nothing to the ledger):
--export-audit DIR Export the approvals ledger for an auditor to
DIR/approvals-audit-export.* instead of showing or
recording status (refuses on a tampered audit chain).
--format {csv,json} Format for --export-audit (default: csv).
--share-profile {importer,distributor,customer}
Redaction profile for --export-audit (redacts reviewer
identity and reason text).
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`
Network behavior: offline. This command has no network-capable path.sbomflow explain#
text
usage: sbomflow explain [-h]
(--gap GAP_ID | --finding VULN_ID | --gate | --ai-entity ENTITY_ID | --explain-terms [TERM] | --warning [CODE])
[output_dir]
Print a sourced, human-readable explanation of one gap, finding, the
gate decision, or a scan-warning code - 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' (not needed for
--explain-terms).
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.
--ai-entity ENTITY_ID
Explain one AI evidence entity end to end: what was
observed, what was declared, where each fact came
from, and what is being asked of a reviewer. A unique
id prefix is accepted.
--explain-terms [TERM]
Plain-language definitions of the core vocabulary
(SBOM, VEX, CVSS, purl, gate, KEV, EPSS, SSVC, ...).
Omit TERM for all of them; needs no output directory.
--warning [CODE] Explain a scan-warning code and this run's occurrences
(omit CODE to list the codes seen in this run).
Examples:
sbomflow explain ./evidence --gate
sbomflow explain ./evidence --finding CVE-2024-29041
sbomflow explain ./evidence --warning unpinned_requirements
sbomflow explain ./evidence --warning
lists the warning codes this run actually emitted
sbomflow explain --explain-terms kev
no output directory needed
Next: sbomflow review ./evidence to record the human decision.
Network behavior: offline. This command has no network-capable path.sbomflow bundle#
text
usage: sbomflow bundle [-h] [--zip ZIP] [--as-of AS_OF] [--with-prov] 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.
--with-prov Also map the run's traceability.json to a W3C PROV-DM subset
(prov-mapping.json) and include it in the bundle (requires
the run to have been produced with --emit-traceability).
Example:
sbomflow bundle ./evidence --zip ./evidence/evidence-bundle.zip
Next: sbomflow verify-bundle ./evidence · share the ZIP with your reviewer
Network behavior: offline. This command has no network-capable path.sbomflow validate#
text
usage: sbomflow validate [-h] [--json] output_dir
positional arguments:
output_dir Directory produced by 'analyze'.
options:
-h, --help show this help message and exit
--json Machine-readable report on stdout (schema_version sbomflow-
validate-report-v1); same exit codes as the human output.
Network behavior: offline. This command has no network-capable path.sbomflow compare-releases#
text
usage: sbomflow compare-releases [-h] [--report-theme {light,dark}]
--previous PREVIOUS --current CURRENT --output OUTPUT [--html]
[--release-notes FILE] [--release-notes-format {markdown,cyclonedx,both}]
[--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
--report-theme {light,dark}
Palette for generated HTML surfaces (default: light).
Print output is always light.
--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.
--release-notes FILE Also write template-locked engineering security
release notes (markdown): counts plus the list of
fixed advisory ids. No free prose, no severities, and
no still-open advisory ids.
--release-notes-format {markdown,cyclonedx,both}
Which rendering(s) of the release note to write.
'markdown' (the default) is --release-notes FILE
alone. 'cyclonedx' writes only engineering-release-
notes.cdx.json - a standalone CycloneDX 1.7 document -
into --output. 'both' writes both, and then --release-
notes names the markdown destination. Both renderings
project one normalized view, so they carry the same
facts; the CycloneDX document adds no claim of its
own.
--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/v2
Network behavior: offline. This command has no network-capable path.Every 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.
config Inspect the effective product configuration (offline).
examples Print worked examples that are executed by the test suite.
Core evidence loop:
audit Run analyze + full opt-in packs + bundle + validation in one command.
analyze Analyze a product directory.
batch-run Run analyze across every product declared in one batch manifest.
explain Explain one gap, finding, gate decision, or warning from existing artifacts.
migrate-in Import another tool's estate as origin-labelled CLAIMS (offline; never decisions).
next-actions Release-scoped ship-readiness line plus the top few outstanding actions.
review Show the review queue for an output dir, or record a human sign-off decision (writes review-queue.json + an audit event).
review-merge Merge two reviewer decision files by key, reporting conflicts (offline).
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).
decisions Inspect and recover crash-interrupted human decision transactions (offline).
gate Release-gate tools that record nothing (read-only, offline).
policy Inspect or diff release-gate policy profiles (read-only, offline).
store Local, file-based evidence store: accumulate release outputs and query across products/releases. Deterministic, offline, no database.
emit-user-info Emit an UNSIGNED CRA Annex II user-information draft from an output directory (offline).
Compare & track releases:
compare-releases Compare two SBOMFlow output directories and write release-drift.json.
recheck Re-evaluate a shipped release against newer local advisory data (offline).
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.
release-chain Verify a hash-linked chain of release records across output directories (tamper-evident release history).
backfill Register past releases in the store as DECLARED records (operator-asserted history), never observed audit runs — for products shipped before SBOMFlow.
report Derived, read-only planning reports composed from a finished run.
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-annexii-model Validate the packaged or supplied CRA Annex II information-to-users 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).
schema Show the field structure of SBOMFlow's own output artifacts (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.
passport Product-security assurance passport: a signed, self-contained, redaction-audited handoff per release that the recipient verifies offline. Proves issuance + integrity + recorded human decisions — never conformity.
standards-view Group an output's CRA coverage by EN 18031 section (PROVISIONAL, offline).
regime-view Read an existing verified pack through a versioned regime profile (read-only, offline; never a conformity claim).
regime-profile Author, validate, inspect and carry a LOCAL customer-authored regime profile (offline; never legal advice and never a conformity claim).
Integrations / sync:
annotate Render an output directory's gate verdict as native CI annotations (offline).
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).
ingest-codex-security Import a LOCAL completed Codex Security scan directory as external AI-assisted observations (offline; never runs or authenticates to the scanner, and never a gate, VEX or approval).
ingest-trivy Ingest a Trivy JSON report as sourced observations (offline; never native findings/VEX/gate).
ingest-grype Ingest a Grype JSON report as sourced observations (offline; never native findings/VEX/gate).
elf-evidence Read ELF binaries' declared structure — SONAME, DT_NEEDED, build-id (offline; never executed).
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).
Post-market case workflow (experimental):
case Post-market PSIRT case workflow (experimental): open a case, intake a local advisory, correlate it against the store into exposure candidates, and record human triage. Offline; drafts and records only — never an 'affected' verdict, never a filing.
Maintenance:
upgrade Inspect/plan/migrate-copy/validate old output dirs to the current schemas (offline; never in place).
license Read-only, offline verification of a signed entitlement file. Never enforces licensing — an absent/expired entitlement blocks nothing.
support-bundle Package sanitized diagnostics for a bug report (offline, redaction-audited).
help Show grouped help, help for one command, or `help error`/`exit`/`warning <code>` (offline).
Docs: https://sbomflow.com/docs · `sbomflow help <command>` for details
`sbomflow help <command> <group>` opens one option group; `sbomflow <command> --help` still lists every option.
`sbomflow help error <code>`, `sbomflow help exit <code>` and `sbomflow help warning <code>` explain error, exit and warning codes offline.