Goals
SBOMFlow is the system of record for software and connected-device release evidence (SBOMs, vulnerabilities and VEX, test and runtime evidence, named human review) on a deterministic offline engine; regulatory views such as the EU CRA are optional.
Pick the job you came for. Each goal works on its own, and every goal except the requirement-regime goals needs no requirement regime. The same cards print offline with sbomflow help goals and sbomflow help goal <id>.
Note
This page is generated from the goal registry the CLI reads, so it matchessbomflow help goal exactly. Each command uses stand-ins, listed under it,
for your own paths and names, and the test suite runs every step offline
against a bundled example.
Requirement regimes (optional; CRA available today)
Goals#
Produce SBOMs for a release or a questionnaire#
Goal sbom · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Engineers who owe a customer, a procurement questionnaire or a security team an SBOM for one release.
You bring:
- Your product's source tree, lockfiles or build manifests.
Steps, in order:
# 1. Scan the tree and write CycloneDX and SPDX SBOMs with the evidence pack.
sbomflow analyze . --output evidence --requirement-regime none
# 2. Check the output directory is complete and well formed.
sbomflow validate evidence
# 3. List the inputs the scan could not read, so a gap is visible.
sbomflow explain evidence --warning| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
Outputs: cyclonedx-sbom.json, spdx-sbom.json, evidence-pack.json, scan-warnings.json.
Stays human: Whether the SBOM is complete enough for its reader, and every answer you give from it.
Guide: Evidence outputs.
Triage vulnerabilities with context#
Goal vulnerabilities · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Security engineers who must say which advisories affect a release, and why.
You bring:
- Your product's source tree, lockfiles or build manifests.
- Local advisory data: a vulndb directory with a pinned OSV snapshot (
sbomflow vulndb update --source-type osv --url URL, the one network step), or an OSV snapshot file.
Steps, in order:
# 1. List the local advisory sources and the snapshot each one has pinned.
sbomflow vulndb --dir vuln-data sources
# 2. Match components against the OSV snapshot pinned in that directory (--osv-snapshot also takes a snapshot file) and write a VEX document.
sbomflow analyze . --output evidence --requirement-regime none --osv-snapshot vuln-data --emit-vex
# 3. Print the findings waiting for a human VEX decision.
sbomflow review evidence
# 4. Read one finding: what matched, where, and what is recorded about it.
sbomflow explain evidence --finding CVE-ID
# 5. Build the static reviewer console to work through the queue.
sbomflow review-view evidence| Stand-in | Replace it with |
|---|---|
vuln-data | a local vulnerability-data directory |
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
CVE-ID | an advisory id from the review queue |
Outputs: evidence-pack.json, cyclonedx-vex.json, reviewer.html.
Stays human: Every VEX status and its justification. KEV and EPSS are inputs to that decision, never the decision.
Guide: Observed vs reviewed.
Gate a release in CI#
Goal release-gate · network: none — every step runs offline · requirement regime: none needed.
Who it is for. CI owners who want a build to stop when a release breaks a stated policy.
You bring:
- Your product's source tree, and the policy you want enforced.
Steps, in order:
# 1. Read a built-in gate policy and its content hash.
sbomflow policy show strict-ci
# 2. Run the release with a gate on.
sbomflow audit . --output evidence --requirement-regime none --fail-on-vulnerabilities --zip
# 3. Explain why the gate decided what it did.
sbomflow explain evidence --gate
# 4. Print the verdict as annotations for the pull request.
sbomflow annotate evidence --format githubExit 1 at step 2 means the gate blocked the release: the gate working, not a fault.
| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
Outputs: release-gate.json, evidence-bundle.zip, evidence-pack.json.
Stays human: Which policy a release is held to, and every waiver or override. The gate reports; a person decides to ship.
Guide: Operator CI runbook.
Sign off a release with named human review#
Goal sign-off · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Release owners who need a record of who reviewed what, and who approved the release.
You bring:
- Your product's source tree, and the reviewers and roles who sign.
Steps, in order:
# 1. Build the release's evidence pack and reviewer bundle.
sbomflow audit . --output evidence --requirement-regime none
# 2. Print everything waiting on a named human.
sbomflow review evidence
# 3. Record your acceptance of one evidence item, under your name.
sbomflow review evidence --accept KEY --reviewer REVIEWER
# 4. Record a named release approval for one role.
sbomflow approve evidence --role ROLE --reviewer REVIEWER
# 5. Show which required roles are signed and which are missing.
sbomflow approve evidence --require-role ROLE
# 6. Check every recorded decision against its transaction journal.
sbomflow decisions verify-transactions --store evidence
# 7. See what still stands between this release and shipping.
sbomflow next-actions evidence| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
KEY | an evidence key from the review queue |
REVIEWER | your name or team label, recorded with the decision |
ROLE | the reviewer role a release requires, such as release-manager |
Outputs: reviews.json, approvals.json, audit-log.jsonl, evidence-bundle.html.
Stays human: Every acceptance and every approval. SBOMFlow records who decided and when; it never decides for them.
Guide: Reviewer runbook.
Track what changed between releases#
Goal history · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Teams who answer 'what changed since the last release?' for customers or auditors.
You bring:
- Your product's source tree.
- The previous release's output directory.
Steps, in order:
# 1. Build this release's pack and compare it with the previous one.
sbomflow analyze . --output evidence --requirement-regime none --previous-output evidence-prev
# 2. Write the release drift report and release notes.
sbomflow compare-releases --previous evidence-prev --current evidence --output drift --release-notes drift/RELEASE-NOTES.md
# 3. Keep the release in a local evidence store.
sbomflow store --store .sbomflow-store add evidence
# 4. List the releases the store holds.
sbomflow store --store .sbomflow-store list
# 5. Tell one finding's story across the stored releases.
sbomflow store --store .sbomflow-store timeline --finding CVE-ID
# 6. Check the release records link into one hash chain.
sbomflow release-chain verify evidence-prev evidence| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
evidence-prev | the previous release's output directory |
drift | a new directory for the drift report and release notes |
.sbomflow-store | a local evidence store directory |
CVE-ID | an advisory id from the review queue |
Outputs: release-drift.json, RELEASE-NOTES.md, release-record.json.
Stays human: Whether a change matters, and what you tell anyone about it. Drift is context, never a decision.
Guide: Operating scenarios.
Hand release evidence to a customer or auditor#
Goal handoff · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Anyone who sends a finished pack to someone outside the team who must check it offline.
You bring:
- Your product's source tree, and the name you issue the evidence under.
Steps, in order:
# 1. Build the pack and its reviewer bundle, zipped for sending.
sbomflow audit . --output evidence --requirement-regime none --zip
# 2. Check the bundle's content layer before it leaves.
sbomflow verify-bundle evidence --layered --require-layers content
# 3. Package a read-only auditor pack for a customer.
sbomflow auditor-pack evidence --share-profile customer
# 4. Issue a passport the recipient can verify offline.
sbomflow passport issue evidence --issuer ISSUER
# 5. Verify the passport the way the recipient will.
sbomflow passport verify evidence/passport.zip| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
ISSUER | the organisation issuing the passport |
Outputs: evidence-bundle.zip, auditor-pack.zip, passport.zip.
Stays human: What you share and with whom. Verification re-checks bytes and signatures, never engineering judgement.
Guide: Read an evidence bundle.
Keep runtime and test evidence by identity (experimental)#
Goal custody · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Test, bench and field teams who keep traces, dumps and logs behind a release and must show later that the bytes are unchanged.
You bring:
- The trace, dump, capture or test log files to keep.
- A sbomflow.yaml for the release that declares the set under preserved_artifacts: (- set: custody-set), with the set inside the product directory: a declaration never reaches outside it.
Steps, in order:
# 1. Create an empty custody set for one release.
sbomflow custody init custody-set --set-id SET_ID --release-id RELEASE
# 2. Admit an artifact by its digest, with what was run.
sbomflow custody add custody-set TRACE --release-id RELEASE --scenario SCENARIO
# 3. List what the set holds, with each digest prefix.
sbomflow custody list custody-set
# 4. Show one artifact and its records.
sbomflow custody show custody-set DIGEST
# 5. Record a named reviewer's decision about one artifact.
sbomflow custody review custody-set --accept ARTIFACT_KEY --reviewer REVIEWER --note NOTE
# 6. Re-hash the set's records and check its audit chain.
sbomflow custody verify custody-set
# 7. Package the set for a customer or auditor to verify offline.
sbomflow custody export custody-set --output handover --zip
# 8. Compare what the set and its handover copy record.
sbomflow custody compare custody-set handover
# 9. Run the release whose sbomflow.yaml declares the set; the run joins the set's records and applied decisions.
sbomflow analyze . --output evidence --requirement-regime none
# 10. Compare what the set records with what that release run joined.
sbomflow custody compare custody-set --run evidence| Stand-in | Replace it with |
|---|---|
custody-set | a new custody set directory |
SET_ID | a short name for the custody set |
RELEASE | the release id the evidence belongs to |
TRACE | a trace, dump, capture or test log to keep |
SCENARIO | what was run, such as boot-to-idle |
DIGEST | the artifact's digest prefix, as custody list prints it |
ARTIFACT_KEY | the artifact's full review key, as custody show prints it |
REVIEWER | your name or team label, recorded with the decision |
NOTE | what you concluded about the artifact, and its limits |
handover | a new directory for the handover copy |
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
Outputs: custody-set.json, audit-log.jsonl, custody-export.zip, preserved-artifacts.json.
Stays human: Whether a kept artifact is acceptable evidence. Custody proves byte identity; it does not analyse the artifact.
Guide: Keeping runtime evidence in custody.
Record firmware and embedded build evidence#
Goal firmware · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Embedded teams who ship firmware and must show what went into an image and what was run on it.
You bring:
- Your product's source tree.
- Build outputs: the Zephyr build directory, a linker map, Twister results.
- A capture taken on the image, and the image itself.
- A sbomflow.yaml that declares the record under preserved_artifacts: (- record: preserved/TRACE.preserved-artifact.json, original: the capture, firmware_image: the image), all inside the product directory: a declaration never reaches outside it.
Steps, in order:
# 1. Scan the tree and write the SBOMs and evidence pack.
sbomflow analyze . --output evidence --requirement-regime none
# 2. Read the Zephyr build's SPDX documents into build evidence.
sbomflow zephyr-evidence build --output evidence/zephyr-build-evidence.json
# 3. Parse the linker map into an object and section graph.
sbomflow linker-map-evidence zephyr.map --output evidence/linker-map-evidence.json
# 4. Import Twister results as test evidence.
sbomflow twister-evidence twister-out --output evidence/twister-evidence.json
# 5. Preserve a capture bound to its image, as a record file inside the product directory; declare it in sbomflow.yaml to join a run.
sbomflow ingest-preserved-artifact TRACE --release-id RELEASE --scenario SCENARIO --firmware-image zephyr.elf --output preserved/TRACE.preserved-artifact.json
# 6. Re-run the release whose sbomflow.yaml declares the record under preserved_artifacts: (record, original, firmware_image); the run re-hashes the original and looks up the image among the files it scanned.
sbomflow analyze . --output evidence --requirement-regime none| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
build | your Zephyr build directory |
zephyr.map | the linker map your build wrote |
twister-out | your Twister results directory |
TRACE | a trace, dump, capture or test log to keep |
RELEASE | the release id the evidence belongs to |
SCENARIO | what was run, such as boot-to-idle |
zephyr.elf | the firmware image the capture ran on |
preserved/TRACE.preserved-artifact.json | the record file to write, inside the product directory |
Outputs: cyclonedx-sbom.json, zephyr-build-evidence.json, linker-map-evidence.json, twister-evidence.json, preserved-artifacts.json.
Stays human: Whether the image, the build and the tests are the ones you ship. Every reader records what it read; none judges it.
Guide: Supported inputs.
Work a post-market vulnerability case (experimental)#
Goal post-market · network: none — every step runs offline · requirement regime: none needed.
Who it is for. PSIRT and support engineers who handle an advisory after a release has shipped.
You bring:
- The shipped release's output directory.
- The advisory or report you received, and newer advisory data.
Steps, in order:
# 1. Keep the shipped release in a local evidence store.
sbomflow store --store .sbomflow-store add evidence
# 2. Open a case with a hash-chained journal.
sbomflow case open psirt-case --case-id CASE_ID --actor ACTOR
# 3. Take in the advisory or report, with its provenance.
sbomflow case intake psirt-case ADVISORY --actor ACTOR
# 4. Find which stored releases the advisory may reach.
sbomflow case correlate psirt-case --store .sbomflow-store --advisories ADVISORY
# 5. Show the case: state, assessments and chain check.
sbomflow case show psirt-case
# 6. See what in the shipped release goes stale next, and when.
sbomflow report freshness evidence
# 7. Re-check the shipped release against newer advisory data.
sbomflow recheck evidence --osv-snapshot OSV_SNAPSHOT --output recheck| Stand-in | Replace it with |
|---|---|
.sbomflow-store | a local evidence store directory |
evidence | the output directory for this release's evidence |
psirt-case | a new case directory |
CASE_ID | your case identifier |
ACTOR | the named person or team recording the step |
ADVISORY | a local advisory or report file (OSV, CSAF or CVE JSON) |
OSV_SNAPSHOT | a newer local OSV snapshot file |
recheck | a new directory for the recheck report |
Outputs: case-journal.jsonl, freshness-horizon.json, recheck.json, recheck.md.
Stays human: Every triage outcome, every disclosure and any report to an authority. SBOMFlow sends, files and submits nothing.
Guide: Operating scenarios.
Record AI components and AI scan results (in development)#
Goal ai-evidence · network: none — every step runs offline · requirement regime: none needed.
Who it is for. Teams whose release carries models, datasets or AI services, or who run an AI-assisted scanner.
You bring:
- Your product's source tree.
- A completed Codex Security scan directory, if you ran one.
Steps, in order:
# 1. Scan the tree and write the AI evidence and an SPDX 3 AI BOM.
sbomflow analyze . --output evidence --requirement-regime none --emit-aibom
# 2. Import a finished AI-assisted scan as observations to review.
sbomflow ingest-codex-security SCAN_DIR --output evidence/codex-security-ingest.json
# 3. Check the output directory is complete and well formed.
sbomflow validate evidence| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
SCAN_DIR | a completed Codex Security scan directory |
Outputs: ai-evidence.json, spdx3-aibom.json, codex-security-ingest.json.
Stays human: Every imported result: each is an observation that needs review, and zero findings never means safe.
Guide: Capabilities.
Requirement regimes (optional; CRA available today)#
A requirement regime is a view a run can be executed under. It is optional: nothing above needs one. See Use SBOMFlow without CRA assessment.
Prepare EU CRA release evidence (optional regime)#
Goal cra · network: none — every step runs offline · requirement regime: cra, chosen explicitly; SBOMFlow observes and drafts, and makes no conformity claim.
Who it is for. Manufacturers who choose to assess a release against the EU Cyber Resilience Act requirement graph.
You bring:
- Your product's source tree.
- Your declared product class (default, important-class-i, important-class-ii or critical).
Steps, in order:
# 1. Run the release under the CRA regime with your declared class.
sbomflow audit . --output evidence --requirement-regime cra --product-class default
# 2. Explain the gate and the requirement gaps it read.
sbomflow explain evidence --gate
# 3. Work the gaps and findings with named review.
sbomflow review evidence
# 4. Write the UNSIGNED Annex II user-information draft.
sbomflow emit-user-info evidence
# 5. Check the packaged CRA requirement graph is well formed.
sbomflow validate-graph| Stand-in | Replace it with |
|---|---|
. | your product's source or build directory |
evidence | the output directory for this release's evidence |
Outputs: cra-coverage.json, technical-documentation.md, user-information.DRAFT.json.
Stays human: Your product class, whether any requirement is met, and any report to an authority. Drafts stay UNSIGNED; SBOMFlow files nothing.
Guide: CRA-oriented evidence.