Share and hand off
Hand a finished pack to a reviewer, auditor or customer. This page documents every command in the sharing group, in the order sbomflow help sharing 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 bundle/sbomflow sign-bundle/sbomflow verify-bundle/sbomflow auditor-pack— portable reviewer/auditor handoffs.
Who this is for: suppliers, recipients, auditor liaisons and release engineers.
sbomflow bundle#
Create or refresh reviewer evidence-bundle artifacts for an output dir.
Create or refresh the portable reviewer handoff (evidence-bundle.json,
evidence-bundle.html, optional deterministic ZIP) for an existing run.
A bundle copies and hashes existing artifacts; it adds no authority and
no new claims.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | an existing analyze or audit output directory. |
| Writes | artifact-manifest.json (with evidence-bundle.json and evidence-bundle.html, into the directory); the deterministic ZIP with --zip |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 usage or input error |
| Machine output | artifact-suffices — writes evidence-bundle.json / .zip, the portable reviewer handoff |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | Directory produced by analyze/audit. |
--zip | ZIP | none | any | no | Optional path for a deterministic evidence ZIP. |
--as-of | AS_OF | none | any | no | Pinned ZIP timestamp. |
--with-prov | (flag) | false | — | no | 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). |
Examples
Assemble a portable reviewer handoff from an existing run.
sbomflow bundle outAlso write the deterministic evidence ZIP inside the run.
sbomflow bundle out --zip out/evidence-bundle.zipWrite the ZIP beside the run, with a pinned timestamp.
sbomflow bundle out --zip evidence-bundle.zip --as-of 2026-07-01T00:00:00ZSee also: sbomflow sign-bundle, sbomflow verify-bundle, sbomflow auditor-pack, sbomflow help goal handoff.
sbomflow sign-bundle#
Sign evidence-bundle.json with a local PEM private key (optional sbomflow[sign] extra).
Sign an output directory's evidence-bundle.json with a local PEM private key
(Ed25519, Ed448, EC or RSA), writing evidence-bundle.sig.json, or with
--format in-toto a DSSE envelope. It needs the optional sign extra
(cryptography). A signature proves integrity and who signed; it adds no
authority to the evidence.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | an output directory's evidence-bundle.json and a PEM private key. |
| Writes | evidence-bundle.sig.json, or with --format in-toto evidence-bundle.intoto.jsonl |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 no bundle, an unusable key, or no signing extra |
| Machine output | artifact-suffices — writes detached signature envelope files (formats: sbomflow, in-toto) |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | Directory with evidence-bundle.json. |
--key | KEY | none | any | yes | PEM private key path. |
--key-id | KEY_ID | none | any | no | Optional key identifier recorded in the signature. |
--as-of | AS_OF | none | any | no | Pinned signed_at timestamp. |
--format | {sbomflow,in-toto} | sbomflow | sbomflow, in-toto | no | 'sbomflow' writes evidence-bundle.sig.json (default); 'in-toto' writes a DSSE envelope evidence-bundle.intoto.jsonl for standard in-toto verifiers. Same key, same guarantee — integrity/authenticity only. |
Examples
Sign the reviewer bundle with a private key.
sbomflow sign-bundle out --key keys/example-signing-key.pemWrite a DSSE envelope for standard in-toto verifiers instead.
sbomflow sign-bundle out --key keys/example-signing-key.pem --format in-totoRecord a key identifier and a pinned signing time.
sbomflow sign-bundle out --key keys/example-signing-key.pem --key-id release-2026 --as-of 2026-07-01T00:00:00ZSee also: sbomflow bundle, sbomflow verify-bundle, sbomflow passport issue.
sbomflow verify-bundle#
Verify an evidence bundle's integrity (stdlib tamper check) and, with --key, its signature.
Verify an evidence bundle, a directory or a ZIP. Without --layered it is the
manifest check plus, with --key, the signature; --layered runs all four layers
(content, envelope, semantics, authority), and a tampered listed member fails
even when the signature is intact. A failed verification exits 3; with
--require-layers, a well-formed report that misses a required layer exits 7,
and with --refuse-extras so does a bundle holding a member its manifest does
not list.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | a directory or ZIP holding an evidence bundle and, for a signature, a PEM public key. |
| Writes | stdout (the verification result; --json prints JSON) |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 a missing bundle, or a usage error · 3 the signature or a listed file failed verification · 7 --layered: a layer --require-layers named did not verify, or --refuse-extras found a member the manifest does not list |
| Machine output | has-json — verification detail, per-layer under --layered; parity with passport verify --json. Version skew stays context, changing no status and no exit code |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | Directory (or a .zip) with a signed evidence bundle. |
--key | KEY | none | any | no | PEM public key path for signature verification. |
--json | (flag) | false | — | no | Emit the verification detail as one JSON document (per-layer under --layered), parity with passport verify --json. |
--layered | (flag) | false | — | no | Full four-layer verification (content/envelope/semantics/authority) instead of the manifest-only signature check. Accepts a directory or a .zip; a tampered listed member fails even when the signature is intact. |
--authorized-key-sha256 | SHA256 | none | any | no | Operator trust policy: sha256 of a public-key PEM authorised to sign (repeatable). With --layered, a valid signature from a key not listed is reported valid_but_unauthorized and is not trusted. |
--require-layers | LAYERS | none | any | no | Automation contract for --layered: comma-separated layer names (content,envelope,semantics,authority) that MUST verify. Exit 7 when a well-formed report does not meet them; the full layer report is still printed. Unknown names and use without --layered are refused (exit 2) before verification. Without this flag exit codes are unchanged. |
--refuse-extras | (flag) | false | — | no | With --layered: a member the bundle manifest does not list fails the content layer's expectation (exit 7), instead of verifying with extras_present. For automation that must not accept anything added to a bundle; the default audit -> bundle -> auditor-pack flow writes such members by design. Use without --layered is refused (exit 2). |
Examples
Check the four verification layers of an unsigned bundle.
sbomflow verify-bundle out --layeredVerify a signed bundle against the signer's public key.
sbomflow verify-bundle out --key keys/example-signing-key.pub.pemAll four layers as JSON, with the signer's key.
sbomflow verify-bundle out --layered --key keys/example-signing-key.pub.pem --jsonRequire the envelope layer: an unsigned bundle does not meet it and exits 7. Exits 7.
sbomflow verify-bundle out --layered --require-layers envelopeSee also: sbomflow sign-bundle, sbomflow bundle, sbomflow passport verify, sbomflow help exit.
sbomflow auditor-pack#
Build auditor-pack.zip, a read-only package an auditor opens in a browser.
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 and the reviewer console behind a landing page, with file hashes.
The redaction profile withholds reviewer identity and free-form reason
text.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | an existing analyze or audit output directory. |
| Writes | auditor-pack.zip: the redacted share subset and reviewer console behind a landing page |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 missing or unusable directory |
| Machine output | artifact-suffices — writes auditor-pack.zip, a self-contained read-only package |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | Directory produced by 'analyze'/'audit'. |
--share-profile | {importer,distributor,customer} | importer | importer, distributor, customer | no | Redaction profile for the included shared data subset AND for the reviewer console: reviewer identity and free-form reason text are withheld, the same fields 'approve --export-audit --share-profile' withholds (default: importer). |
--as-of | AS_OF | none | any | no | Pinned timestamp for the deterministic package. |
Examples
Build a read-only package an auditor opens in a browser.
sbomflow auditor-pack outRedact for a customer, at a pinned time.
sbomflow auditor-pack out --share-profile customer --as-of 2026-07-01T00:00:00ZRedact for a distributor.
sbomflow auditor-pack out --share-profile distributorSee also: sbomflow bundle, sbomflow passport issue, sbomflow review-view, sbomflow help goal handoff.
sbomflow passport#
Issue or verify a product-security assurance passport (offline).
A product-security assurance passport is a signed, self-contained,
redaction-audited handoff per release that the recipient verifies
offline. It proves issuance, integrity and the recorded human decisions,
never conformity. Name a verb, or the group prints its usage and exits 2.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | nothing itself; its verbs read an output directory or a passport. |
| Writes | nothing itself; each verb's help names what it writes |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 a verb ran and returned 0 · 2 no verb given, or the verb refused |
| Machine output | human-only-by-design — group dispatcher: prints usage/guidance only; the machine surfaces are its nested verbs |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
Examples
Issue an unsigned passport for a finished run.
sbomflow passport issue out --issuer 'Example Devices Ltd' --issued-at 2026-07-01T00:00:00ZVerify a passport as its recipient would.
sbomflow passport verify out/passport.zipName no verb: print the group's usage and exit 2. Exits 2.
sbomflow passportSee also: sbomflow passport issue, sbomflow passport verify, sbomflow help goal handoff.
sbomflow passport issue#
Issue the passport for an analyzed output directory.
Issue the passport for an analyzed output directory: a passport.zip and its
manifest, written into the directory. With --sign-key it is signed (the
optional sign extra); without one it is issued honestly unsigned and says so.
The issuer and issue time are recorded as stated.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | an existing analyze or audit output directory and, to sign, a PEM private key. |
| Writes | passport.zip and its manifest, into the directory |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 missing or unusable directory, or an unusable key |
| Machine output | artifact-suffices — writes the signed passport files; passport verify (with --json) is the read side |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | Directory produced by 'analyze'/'audit'. |
--issuer | ISSUER | none | any | yes | Issuing organisation printed on the manifest. |
--issued-at | ISSUED_AT | none | any | no | Issuance timestamp (default: now, UTC). |
--sign-key | SIGN_KEY | none | any | no | PEM private key (Ed25519 recommended; needs the 'sign' extra). Omit for an honestly-unsigned passport. |
--key-id | KEY_ID | none | any | no | Key identifier recorded beside the signature. |
Examples
Issue an unsigned passport, honestly marked as unsigned.
sbomflow passport issue out --issuer 'Example Devices Ltd' --issued-at 2026-07-01T00:00:00ZIssue a signed passport.
sbomflow passport issue out --issuer 'Example Devices Ltd' --sign-key keys/example-signing-key.pem --key-id release-2026Refuse a directory that does not exist. Exits 2.
sbomflow passport issue missing-dir --issuer 'Example Devices Ltd'See also: sbomflow passport verify, sbomflow sign-bundle, sbomflow auditor-pack.
sbomflow passport verify#
Recipient-side offline verification of a passport directory or zip.
Verify a passport as its recipient does, fully offline: every attested member
against the manifest and, with --public-key, the signature (the optional sign
extra). A member that no longer matches, or a signature that does not, exits
4.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | stable |
| Regime | any |
| Reads | a passport.zip, or a directory holding only a passport's own members. |
| Writes | stdout (the verification report; --json prints JSON) |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 ok · 2 not a passport, or unreadable · 4 an attested member or the signature no longer matches |
| Machine output | has-json — read/status surface; one versioned JSON document on stdout |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
path | path | none | any | yes | passport.zip, or a directory holding only a passport's own members. To check the analysed output directory passport issue wrote into, verify the passport.zip there. |
--public-key | PUBLIC_KEY | none | any | no | PEM public key to verify the signature (needs the 'sign' extra). |
--json | (flag) | false | — | no | Print the verification report as JSON. |
Examples
Verify a passport as its recipient would.
sbomflow passport verify out/passport.zipThe report as JSON.
sbomflow passport verify out/passport.zip --jsonVerify a signed passport against the issuer's public key.
sbomflow passport verify out/passport.zip --public-key keys/example-signing-key.pub.pemSee also: sbomflow passport issue, sbomflow verify-bundle, sbomflow help goal handoff.
sbomflow supplier-package#
Emit the package a customer's supplier intake reads (offline).
Cut a supplier package from one verified output directory for a customer whose
SBOMFlow reads suppliers/<dir>/intake.json. Offline; nothing is sent.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | experimental |
| Regime | any |
| Reads | nothing itself; its verb reads one analyze output directory. |
| Writes | nothing itself; its verb's help names what it writes |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 a verb ran and returned 0 · 2 no verb given, or the verb refused |
| Machine output | human-only-by-design — group dispatcher: prints usage/guidance only; the machine surfaces are its nested verbs |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
Examples
Emit the package a customer's supplier intake reads, from one run whose pack and gate verify.
sbomflow supplier-package emit out --to supplier-handoff --supplier gateway-module --scope 'gateway module release'See also: sbomflow supplier-package emit, sbomflow help sharing.
sbomflow supplier-package emit#
Write intake.json, the shared SBOMs and (optionally) reviewed VEX into a directory.
Write DIR/intake.json, the shared projections of cyclonedx-sbom.json and spdx-
sbom.json, and emitted-from.json (the release id, the pack digest, and any
stated validity date or superseded package). With --include-vex, vex.json
carries only reviewer decisions the release applied: a finding nobody reviewed
has no statement, observed statuses are never emitted, and reviewer identities
are withheld. The output directory must verify against its run-completion seal
and its gate must have decided over its pack, and every member passes the
share-boundary preflight, before anything is written. `received` is left for
the recipient to state.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | experimental |
| Regime | any |
| Reads | one analyze or audit output directory whose pack and gate verify against its run seal; with --include-vex, the reviewer decisions that run applied. |
| Writes | intake.json, the shared SBOMs, emitted-from.json and, with --include-vex, vex.json in --to; the recipient states received when the package arrives |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 the package was written · 2 a usage error, an output that does not verify, no applied decision for --include-vex, or an occupied --to; nothing is written |
| Machine output | artifact-suffices — writes intake.json, the shared SBOMs, emitted-from.json and (with --include-vex) vex.json into --to; those files are the machine surface |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | An output directory produced by sbomflow analyze or audit. |
--to | DIR | none | any | yes | Where the package is written: absent or empty, never a symlink, outside EVIDENCE_DIR. |
--supplier | ID | none | any | yes | Contact-free supplier id the recipient's intake accepts ([a-z0-9][a-z0-9._-]{0,63}). |
--scope | TEXT | none | any | yes | What this evidence covers, in words the recipient will read. |
--valid-until | DATE | none | any | no | Date (YYYY-MM-DD) until which you state this package is current; recorded in emitted-from.json. |
--supersedes | ID | none | any | no | The earlier package this one replaces, recorded verbatim in emitted-from.json. |
--include-vex | (flag) | false | — | no | Also write vex.json (OpenVEX) from the reviewer decisions the release applied. |
Examples
Emit the package a customer's supplier intake reads, from one run whose pack and gate verify.
sbomflow supplier-package emit out --to supplier-handoff --supplier gateway-module --scope 'gateway module release'State how long the package is valid; it travels in emitted-from.json, never as a key the intake does not read.
sbomflow supplier-package emit out --to supplier-handoff --supplier gateway-module --scope 'gateway module release' --valid-until 2027-06-30A supplier id that is not an operator id (here a space and an address) is refused before anything is written. Exits 2.
sbomflow supplier-package emit out --to supplier-handoff --supplier 'a b@x' --scope 'gateway module release'See also: sbomflow supplier-package, sbomflow analyze, sbomflow help sharing.
sbomflow export-cle#
Write the declared support history as a lifecycle-event document (offline).
Write one Common Lifecycle Enumeration (ECMA-428, CLE 1.0.0) document for the
one product a store or output directory holds, and a receipt beside it (cle-
export-receipt.json in FILE's directory). Events come only from what the
release records declare: an endOfSupport event per release from its
security_updates promise end, or its kind-less support end when it states no
promise; a released event only for a declared record (sbomflow backfill),
whose recorded time is the declared release date. A release that declares no
support end gets no endOfSupport event, and a hardware_availability or
software_maintenance date never becomes one. Each release's end is its own
event: when a later release declares an earlier end, both events are kept and
neither is rewritten. Stored records are checked against the store index, an
output directory's against its run-completion seal, and both files pass the
share-boundary preflight before either is written.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | experimental |
| Regime | any |
| Reads | one evidence store, or one analyze or audit output directory, and the release records it holds; each record is checked against the store index or its run seal. |
| Writes | the lifecycle-event document at --output, an external format no SBOMFlow schema family describes; cle-export-receipt.json (beside it, in the same directory); stdout (the events written and any release that gave none, with why) |
--output names | one file |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 the document and its receipt were written · 2 a usage error, an input that is not a store or output directory, more than one product, nothing declared to export, a record that does not verify, or material the share preflight refuses; nothing is written |
| Machine output | artifact-suffices — writes the lifecycle-event document at --output and cle-export-receipt.json beside it; those files are the machine surface |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
STORE_OR_EVIDENCE_DIR | STORE_OR_EVIDENCE_DIR | none | any | yes | An evidence store (index.json) or an output directory from sbomflow analyze or audit. |
--output | FILE | none | any | yes | Write the lifecycle document here (file): a path outside the input, replaced if present; one export per directory. |
Examples
Export the support end one analysed release declared, as a lifecycle-event document with its receipt beside it.
sbomflow export-cle out --output handoff/lifecycle.cle.jsonExport from a store: every stored release of the one product it holds, each checked against the digest the store recorded.
sbomflow export-cle .sbomflow-store --output handoff/lifecycle.cle.jsonA security-updates promise becomes the end of support; the hardware-availability date the same release declared never does.
sbomflow export-cle supported --output handoff/lifecycle.cle.jsonDeclared releases (backfill) also get a released event, on the release date the operator declared.
sbomflow export-cle history --output handoff/history.cle.jsonReleases on two channels are two products here, and a lifecycle document describes one, so this store is refused and nothing is written. Exits 2.
sbomflow export-cle two-channels --output handoff/history.cle.jsonSee also: sbomflow backfill, sbomflow store add, sbomflow supplier-package emit, sbomflow help sharing.
sbomflow export-reqif#
Write one release's requirements, gaps, findings and evidence as ReqIF (offline).
Write one OMG ReqIF 1.2 document for the release an output directory holds,
and reqif-export-receipt.json beside it. SpecObjects of type
SBOMFlowRequirement (the requirement nodes the run's requirement regime
assessed and any user-supplied catalog's requirements), SBOMFlowGap,
SBOMFlowFinding and SBOMFlowEvidence, linked by evidenced_by and
affects_component. Each IDENTIFIER is derived from a fact stable across
releases, so the next release's export updates the same objects. Attributes
carry the engine's state verbatim, the human review status apart from it, a
reference id and URL (never quoted text) and artifact digests. The release
record must match its run-completion seal, and both files pass the share-
boundary preflight before either is written.| Fact | Value |
|---|---|
| Group | sharing — Share & hand off |
| Stability | experimental |
| Regime | any |
| Reads | one analyze or audit output directory: its release record, checked against the run-completion seal, and the evidence pack the record states the digest of. |
| Writes | the ReqIF 1.2 document at --output, an external format no SBOMFlow schema family describes; reqif-export-receipt.json (beside it, in the same directory); stdout (the object counts and the exploitation-delta state) |
--output names | one file |
| Network | offline — This command has no network-capable path. |
| Exit codes | 0 the ReqIF document and its receipt were written · 2 a usage error, an input that is not a sealed output directory, a record or pack that does not verify, an output inside the input, or material the share preflight refuses; nothing is written |
| Machine output | artifact-suffices — writes the ReqIF document at --output and reqif-export-receipt.json beside it; those files are the machine surface |
Options
| Option | Value | Default | Allowed | Required | Help |
|---|---|---|---|---|---|
-h, --help | (flag) | none | — | no | show this help message and exit |
EVIDENCE_DIR | EVIDENCE_DIR | none | any | yes | An output directory from sbomflow analyze or audit. |
--output | FILE | none | any | yes | Write the ReqIF document here (file): a path outside the input, replaced if present; one export per directory. |
--as-of | AS_OF | none | any | no | Pinned CREATION-TIME and LAST-CHANGE (default: the evidence pack's own generated_at). |
--exploitation-delta | FILE | none | any | no | A delta store exploitation-delta wrote (sbomflow-exploitation-delta-v1). Each finding it names for this release carries sbomflow.exploitation_delta. Read offline and bounded; a file of another schema is refused. Without it no delta is read (none is guessed) and the receipt says not_available. |
Examples
Export one analysed release's requirement nodes, gaps, findings and evidence as a ReqIF document, with its receipt beside it.
sbomflow export-reqif out --output handoff/release.reqifRefused (exit 2): an export is handed on, so it is never written inside the output directory it restates; nothing is written. Exits 2.
sbomflow export-reqif out --output out/inside.reqifSee also: sbomflow export-cle, sbomflow bundle, sbomflow help sharing.