Run a release audit

Produce a release-evidence pack from a build and read it. This page documents every command in the auditing group, in the order sbomflow help auditing lists them. Each command's section is generated from the command itself — its summary, description and options from the parser, and its reads, writes, exit codes, examples and see-also from the command catalog — so it says exactly what sbomflow <command> --help says. Every example below is executed offline by the test suite, and every non-zero exit code is either produced by an executed probe or carries a recorded reason why no offline probe can produce it.

See the CLI overview for how the thirteen groups fit together and the command reference for every command's options in one place.

Overview#

• sbomflow audit <dir> --output <dir> — full offline evidence pack for a release.
• sbomflow analyze <dir> --output <dir> — the analysis stage.
• sbomflow explain <output> --gap <id> — explain an evidence gap.
• sbomflow explain <output> --finding <id> — explain an advisory finding.
• sbomflow explain <output> --gate — explain the release-gate decision.
• sbomflow explain <output> --warning <code> — explain a scan-warning code and the exact inputs that triggered it in this run (omit the code to list the codes seen). See the Warning codes reference.
• sbomflow validate — validate a generated output directory.
• sbomflow next-actions — a sourced worklist for the run you just did; every command it prints is one you can paste and run.

On a large device, validate takes minutes, almost all of it spent checking spdx3-sbom.json against the official SPDX 3.0.1 schema. It announces that step and its expected cost on stderr before starting it, so a long run is distinguishable from a hung one — see validate is taking minutes for the measured figures and how to avoid the cost.

validate is also the tamper check, and a value edited to another JSON type (a string into an array, an object into a number) is a changed artifact like any other: it exits 4 and names the artifact. A check that meets a value of a type it does not read fails that artifact alone, names the check, and lets every other check run. Only when every artifact that check read still holds the bytes the run's completion seal recorded does it end in E099, because then the value is SBOMFlow's own and the fault is a bug to report.

• sbomflow batch-run <manifest> — run analyze for every product declared in one batch manifest, sequentially. Each job gets its own output directory (enforced before anything runs), every job runs even when an earlier one fails, and the exit code is the worst job's — so a batch never looks healthier than its unhealthiest product. A shell loop does the same thing; this adds per-product isolation and partial-failure aggregation. Every row also carries warnings and console_lines (that job's warning count and the number of lines it was counted out of — a clean job keeps its warnings, not its chatter) and network_posture / network_gates / network_posture_reason. The posture is offline, network_enabled or unknown, read from the configuration that job DECLARES: it says what the job was permitted to reach, never that a socket was or was not opened, and unknown means the declaration could not be read rather than that the job stayed offline. A job that exits hard — an argparse refusal inside the in-process re-invocation raises SystemExit — is recorded as that job's error and the estate continues; Ctrl-C still stops the whole batch.
• sbomflow next-actions <output-dir> — the release-scoped ship-readiness line (exit N BECAUSE policy X in mode Y) plus the top few outstanding items, with --json for machine use and --limit to widen the list. Aggregation only: it restates the gate's verdict rather than making one, and always exits 0 — the release gate remains the only machine verdict.

Every action names the pack you actually passed and the real decision key, so the printed command is one you can run rather than a template to fill in. When an input genuinely is not knowable from an output directory, the action says so and names where to get it instead of printing a command that would fail. The JSON carries argv as an array alongside the display string, so a caller never has to re-parse a shell line to run one.

Where an action's examples are things you can open on their own — an AI evidence conflict, an AI item with nothing declared about it — each example also carries its own sbomflow explain … --ai-entity <id> command, in example_commands in the JSON and under per example: in the text. Where they are not (a control name, a drift attribute), the action says why it offers none rather than printing a line that would fail, and the category command above it is still the whole answer.

A preserved artifact's review key is printed under its original's file name in the text (e.g. boot-to-idle.psf with the key on the next line, and For boot-to-idle.psf alone: above that artifact's own command), read from preserved-artifacts.json in the directory you passed. sbomflow review does the same in its queue (- boot-to-idle.psf, then the key, then Original verified). The --json document keeps file names out, as before, because it is meant to be shared.

What has LEFT the worklist is recorded too, in terminal_history: count and three examples as before, and now items — every identifier a decision recorded since the analysis run has covered, per category and in total. The worklist is capped because a person reads it; this record is not, because "the finding I decided yesterday — was it handled, or lost?" is a question about the fourth item as much as the first.

A preserved scheme record — a scheme's certificate or a scheme test tool's report, recorded with its kind — whose stated firmware version is not string-equal to the release version this run declares is listed as a scheme_record_names_other_version item. The JSON records list carries each record's review key with the version it states and the version this release declares, and the text shows both beside each example. It is two statements disagreeing, compared as text: the item decides nothing about whether the record still applies, and it stays listed while the two differ, even after a reviewer records a decision about that file (see runtime-and-test-evidence.md).

An entry of the evidence plan in sbomflow.yaml (preserved_artifact_expectations:) that fewer declared rows match than it names — absent, or not_evaluable when rows that state no kind leave the count undecided — is listed in one preserved_artifact_expectation_unmet item. The JSON records list carries each entry's id, kind, minimum, matching row count and state, and the text shows them beside each example. It offers no command: the fix is in sbomflow.yaml or in the records, followed by a new run. It compares a plan you wrote with the rows declared and says nothing about whether the plan is sufficient (see runtime-and-test-evidence.md).

The list also declares what it rests on, in a freshness block:

- live_decisions — the reviewer decision file beside the pack was re-read for this run, so a decision recorded since the analysis run is already reflected, and findings that were ruled on appear under already decided rather than in the worklist; - snapshot_only — no decision file sits beside the pack, so the list rests on the frozen analysis snapshot and names that fact; - snapshot_unreadable_overlay — a decision file is there but could not be read. The list falls back to the snapshot; treat items as possibly stale. This is deliberately not the same state as an absent file.

Each action carries its own freshness_basis too, so a category with no live overlay is labelled rather than borrowing the freshness of the ones that have one.

Each entry in freshness.decision_sources also carries an input_state, because several different facts fall back to the snapshot and must not read alike: absent (nothing is there), unreadable (something is there and its bytes were never seen — a permission, a directory in the file's place, a dangling symlink, a document past the size budget), malformed (the bytes were read and are not that family's decisions — including a file whose entries are not themselves decisions, such as {"key": "accepted"}), conflicted (the file records more than one answer for one key, so none of them is applied) and valid. A rejection_reason travels beside it. Only valid lets an overlay remove anything from the worklist, and even then the removal rests on the recorded status: an entry with no status, an unknown status, or a not_affected without a valid CISA justification and an attributed reviewer is downgraded and stays on the list.

AI and model evidence#

Every AI surface below is a command or flag you can run. Nothing here runs, loads, evaluates or scores a model, and nothing observes runtime behaviour.

• sbomflow analyze <dir> — static discovery of model artifacts, agents, tools, services and MCP servers, from framework and deployment configuration, dependency files, imports and environment-variable names. Secret values are never recorded, and every detector publishes what it cannot see beside what it can. ai-evidence.json and ai-evidence-map.json are written on every run, including the run that found nothing. Both are experimental artifacts.
• analyze --ai-manifest <file> / audit --ai-manifest <file> — read your own declaration of the AI in the release. The declaration never overwrites the observation, a disagreement is surfaced and never resolved automatically, and a run without the flag records that nothing was compared. The flag being available does not mean anyone supplied a manifest.
• analyze --emit-mlbom / --emit-aibom (also on audit) — opt-in AI/ML BOMs: CycloneDX 1.6 ML-BOM and the SPDX 3.0.1 AI profile, linked to the software SBOM rather than copied. The software SBOM itself stays CycloneDX 1.6 and SPDX 2.3.
• sbomflow explain <output> --ai-entity <id> — explain one AI entity for review. AI-aware release controls are opt-in and off by default; when one is enforced and cannot run, it blocks with its own reason code rather than passing.

Some AI work landed in v0.5.0 as library foundations with no operator path — see Capabilities.

Who this is for: firmware leads, platform teams, estate owners, developers, release managers, QA engineers and programme managers.

sbomflow audit#

Run analyze + full opt-in packs + bundle + validation in one command.

One-command release audit: analyze the build, emit the default evidence
artifacts plus the reviewer bundle, and validate everything it wrote.

The audit composes existing deterministic artifacts; it adds no authority
and makes no conformity claim. Human review stays separate and explicit.

Options

Examples

Run the full offline evidence pack for one release.

sbomflow audit . --output out

Also write the deterministic evidence-bundle.zip to hand over.

sbomflow audit . --output evidence --zip

Enforce the evidence-gap gate; it blocks this demo and exits 1 with every artifact written. Exits 1.

sbomflow audit . --output evidence --fail-on-gaps

Print one machine-readable summary instead of the text report.

sbomflow audit . --output evidence --json

Audit with no requirement regime assessed.

sbomflow audit . --output evidence --requirement-regime none

Write one release's full offline evidence pack into evidence, the directory the first steps read.

sbomflow audit . --output evidence

See also: sbomflow analyze, sbomflow review, sbomflow bundle, sbomflow explain, sbomflow help auditing, sbomflow help goal sign-off.

sbomflow analyze#

Scan a product directory and write its evidence pack (audit adds the bundle).

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.

Options

Examples

Scan a source tree and write the evidence artifacts.

sbomflow analyze . --output out --product-name Gateway --product-version 2.4.1

Refuse to write into a directory that already holds a run. Exits 2.

sbomflow analyze . --output out --on-existing-output refuse

Emit a VEX document alongside the pack, for downstream consumers.

sbomflow analyze . --output out --emit-vex

Write the SBOMs with no requirement regime assessed.

sbomflow analyze . --output out --requirement-regime none

Compare with the previous release's pack and write the drift report as HTML too.

sbomflow analyze . --output out --previous-output out-prev --drift-html

See also: sbomflow audit, sbomflow review, sbomflow explain, sbomflow compare-releases, sbomflow help auditing, sbomflow help goal sbom.

sbomflow batch-run#

Run analyze across every product declared in one batch manifest.

Run `analyze` for each job in a batch manifest, sequentially, and
aggregate the outcomes. Ergonomics over a shell loop: per-product
isolation and partial-failure aggregation, not new capability. The
exit is 0 only if every job exited 0, else the worst job's code.

Options

Examples

Analyze every product the manifest declares, one after another.

sbomflow batch-run estate/estate.yaml

Print the batch summary as JSON, one row per job.

sbomflow batch-run estate/estate.yaml --json

Refuse a file that is not a batch manifest. Exits 2.

sbomflow batch-run estate/products/sensor/requirements.txt

See also: sbomflow analyze, sbomflow portfolio, sbomflow dashboard.

sbomflow validate#

Validate a generated evidence output directory.

Check one analyze or audit output directory: every artifact it holds is parsed
and checked against its published schema, the recorded hashes are re-verified,
and the run's completion seal is compared with the bytes on disk. It writes
nothing. A malformed or changed artifact exits 4, and so does a pack whose
recorded producer (0.5.0 or later) always writes run-completion.json but has
none; a directory that cannot be used exits 2.

Options

Examples

Check that an output directory is a complete, well-formed run.

sbomflow validate out

Print the same report as one JSON document, with the same exit.

sbomflow validate out --json

Refuse a pack whose evidence-pack.json fails its schema. Exits 4.

sbomflow validate broken-evidence

See also: sbomflow audit, sbomflow verify-bundle, sbomflow store verify, sbomflow help exit.

sbomflow explain#

Explain one gap, finding, gate decision, warning or preserved artifact from existing artifacts.

Print a sourced, human-readable explanation of one gap, finding, the
gate decision, a scan-warning code or a preserved artifact - composed
purely from existing artifacts (no AI).

Options

Examples

Explain why the release gate decided what it decided.

sbomflow explain out --gate

Explain one scan-warning code, sourced from the catalog.

sbomflow explain out --warning unparseable_manifest

Explain one advisory finding: where it matched and what a reviewer decided.

sbomflow explain out --finding CVE-SAMPLE-OPENSSL-001

List the warning codes this run actually emitted.

sbomflow explain out --warning

Define a term; no output directory is needed.

sbomflow explain --explain-terms kev

Explain one preserved artifact in a run that declared it: its record, original, stated identity, the run's checks, the review decision and the files that name it.

sbomflow explain sensor-evidence --preserved-artifact c640b5514933

See also: sbomflow review, sbomflow next-actions, sbomflow help, sbomflow help warning.

sbomflow next-actions#

Release-scoped ship-readiness line plus the top few outstanding actions.

Answer "is this release ready, and what do I deal with first?" by
aggregating facts already in an output directory. Aggregation only -
it invents nothing, decides nothing, and never says ship/do-not-ship.

Options

Examples

Print the ship-readiness line and the three actions to deal with first.

sbomflow next-actions out

Print the next-actions document as JSON.

sbomflow next-actions out --json

Surface five actions instead of three.

sbomflow next-actions out --limit 5

See also: sbomflow explain, sbomflow review, sbomflow report freshness.

sbomflow report#

Derived, read-only planning reports composed from a finished run.

Read-only planning reports composed from a finished run. Each verb reads
artifacts that are already on disk and decides nothing; name a verb, or the
group prints its usage and exits 2.

Options

Examples

Print what lapses next in a finished run, evaluated at a pinned time.

sbomflow report freshness out --as-of 2026-07-01T00:00:00Z

The same horizon as JSON, flagging items that lapse within 30 days.

sbomflow report freshness out --json --as-of 2026-07-01T00:00:00Z --horizon-days 30

Name no verb: print the report group's usage and exit 2. Exits 2.

sbomflow report

See also: sbomflow report freshness, sbomflow next-actions.

sbomflow report freshness#

What goes stale next: one dated horizon composed from a run's artifacts.

Compose one freshness horizon from a finished output directory: accepted
evidence validity windows, advisory-snapshot staleness, waiver expiries,
and the support-period end — all the dated things that lapse, soonest
first.

Read-only and offline. Planning context, not a decision: it changes no
review state and suppresses no gate. Writes freshness-horizon.json into
the directory.

Options

Examples

Print what lapses next, evaluated at a pinned time.

sbomflow report freshness out --as-of 2026-07-01T00:00:00Z

The same horizon as JSON, flagging items that lapse within 30 days.

sbomflow report freshness out --json --as-of 2026-07-01T00:00:00Z --horizon-days 30

Look a year ahead: every dated item lapsing within 365 days is flagged.

sbomflow report freshness out --as-of 2026-07-01T00:00:00Z --horizon-days 365

See also: sbomflow next-actions, sbomflow recheck, sbomflow vulndb retention.