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.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsan existing analyze or audit output directory.
Writesartifact-manifest.json (with evidence-bundle.json and evidence-bundle.html, into the directory); the deterministic ZIP with --zip
Networkoffline — This command has no network-capable path.
Exit codes0 ok · 2 usage or input error
Machine outputartifact-suffices — writes evidence-bundle.json / .zip, the portable reviewer handoff

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesDirectory produced by analyze/audit.
--zipZIPnoneanynoOptional path for a deterministic evidence ZIP.
--as-ofAS_OFnoneanynoPinned ZIP timestamp.
--with-prov(flag)false—noAlso 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.

sh
sbomflow bundle out

Also write the deterministic evidence ZIP inside the run.

sh
sbomflow bundle out --zip out/evidence-bundle.zip

Write the ZIP beside the run, with a pinned timestamp.

sh
sbomflow bundle out --zip evidence-bundle.zip --as-of 2026-07-01T00:00:00Z

See 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).

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsan output directory's evidence-bundle.json and a PEM private key.
Writesevidence-bundle.sig.json, or with --format in-toto evidence-bundle.intoto.jsonl
Networkoffline — This command has no network-capable path.
Exit codes0 ok · 2 no bundle, an unusable key, or no signing extra
Machine outputartifact-suffices — writes detached signature envelope files (formats: sbomflow, in-toto)

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesDirectory with evidence-bundle.json.
--keyKEYnoneanyyesPEM private key path.
--key-idKEY_IDnoneanynoOptional key identifier recorded in the signature.
--as-ofAS_OFnoneanynoPinned signed_at timestamp.
--format{sbomflow,in-toto}sbomflowsbomflow, in-totono'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.

sh
sbomflow sign-bundle out --key keys/example-signing-key.pem

Write a DSSE envelope for standard in-toto verifiers instead.

sh
sbomflow sign-bundle out --key keys/example-signing-key.pem --format in-toto

Record a key identifier and a pinned signing time.

sh
sbomflow sign-bundle out --key keys/example-signing-key.pem --key-id release-2026 --as-of 2026-07-01T00:00:00Z

See 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.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsa directory or ZIP holding an evidence bundle and, for a signature, a PEM public key.
Writesstdout (the verification result; --json prints JSON)
Networkoffline — This command has no network-capable path.
Exit codes0 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 outputhas-json — verification detail, per-layer under --layered; parity with passport verify --json. Version skew stays context, changing no status and no exit code

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesDirectory (or a .zip) with a signed evidence bundle.
--keyKEYnoneanynoPEM public key path for signature verification.
--json(flag)false—noEmit the verification detail as one JSON document (per-layer under --layered), parity with passport verify --json.
--layered(flag)false—noFull 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-sha256SHA256noneanynoOperator 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-layersLAYERSnoneanynoAutomation 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—noWith --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.

sh
sbomflow verify-bundle out --layered

Verify a signed bundle against the signer's public key.

sh
sbomflow verify-bundle out --key keys/example-signing-key.pub.pem

All four layers as JSON, with the signer's key.

sh
sbomflow verify-bundle out --layered --key keys/example-signing-key.pub.pem --json

Require the envelope layer: an unsigned bundle does not meet it and exits 7. Exits 7.

sh
sbomflow verify-bundle out --layered --require-layers envelope

See 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.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsan existing analyze or audit output directory.
Writesauditor-pack.zip: the redacted share subset and reviewer console behind a landing page
Networkoffline — This command has no network-capable path.
Exit codes0 ok · 2 missing or unusable directory
Machine outputartifact-suffices — writes auditor-pack.zip, a self-contained read-only package

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesDirectory produced by 'analyze'/'audit'.
--share-profile{importer,distributor,customer}importerimporter, distributor, customernoRedaction 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-ofAS_OFnoneanynoPinned timestamp for the deterministic package.

Examples

Build a read-only package an auditor opens in a browser.

sh
sbomflow auditor-pack out

Redact for a customer, at a pinned time.

sh
sbomflow auditor-pack out --share-profile customer --as-of 2026-07-01T00:00:00Z

Redact for a distributor.

sh
sbomflow auditor-pack out --share-profile distributor

See also: sbomflow bundle, sbomflow passport issue, sbomflow review-view, sbomflow help goal handoff.

sbomflow passport#

Issue or verify a product-security assurance passport (offline).

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsnothing itself; its verbs read an output directory or a passport.
Writesnothing itself; each verb's help names what it writes
Networkoffline — This command has no network-capable path.
Exit codes0 a verb ran and returned 0 · 2 no verb given, or the verb refused
Machine outputhuman-only-by-design — group dispatcher: prints usage/guidance only; the machine surfaces are its nested verbs

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit

Examples

Issue an unsigned passport for a finished run.

sh
sbomflow passport issue out --issuer 'Example Devices Ltd' --issued-at 2026-07-01T00:00:00Z

Verify a passport as its recipient would.

sh
sbomflow passport verify out/passport.zip

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

sh
sbomflow passport

See also: sbomflow passport issue, sbomflow passport verify, sbomflow help goal handoff.

sbomflow passport issue#

Issue the passport for an analyzed output directory.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsan existing analyze or audit output directory and, to sign, a PEM private key.
Writespassport.zip and its manifest, into the directory
Networkoffline — This command has no network-capable path.
Exit codes0 ok · 2 missing or unusable directory, or an unusable key
Machine outputartifact-suffices — writes the signed passport files; passport verify (with --json) is the read side

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesDirectory produced by 'analyze'/'audit'.
--issuerISSUERnoneanyyesIssuing organisation printed on the manifest.
--issued-atISSUED_ATnoneanynoIssuance timestamp (default: now, UTC).
--sign-keySIGN_KEYnoneanynoPEM private key (Ed25519 recommended; needs the 'sign' extra). Omit for an honestly-unsigned passport.
--key-idKEY_IDnoneanynoKey identifier recorded beside the signature.

Examples

Issue an unsigned passport, honestly marked as unsigned.

sh
sbomflow passport issue out --issuer 'Example Devices Ltd' --issued-at 2026-07-01T00:00:00Z

Issue a signed passport.

sh
sbomflow passport issue out --issuer 'Example Devices Ltd' --sign-key keys/example-signing-key.pem --key-id release-2026

Refuse a directory that does not exist. Exits 2.

sh
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.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilitystable
Regimeany
Readsa passport.zip, or a directory holding only a passport's own members.
Writesstdout (the verification report; --json prints JSON)
Networkoffline — This command has no network-capable path.
Exit codes0 ok · 2 not a passport, or unreadable · 4 an attested member or the signature no longer matches
Machine outputhas-json — read/status surface; one versioned JSON document on stdout

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
pathpathnoneanyyespassport.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-keyPUBLIC_KEYnoneanynoPEM public key to verify the signature (needs the 'sign' extra).
--json(flag)false—noPrint the verification report as JSON.

Examples

Verify a passport as its recipient would.

sh
sbomflow passport verify out/passport.zip

The report as JSON.

sh
sbomflow passport verify out/passport.zip --json

Verify a signed passport against the issuer's public key.

sh
sbomflow passport verify out/passport.zip --public-key keys/example-signing-key.pub.pem

See also: sbomflow passport issue, sbomflow verify-bundle, sbomflow help goal handoff.

sbomflow supplier-package#

Emit the package a customer's supplier intake reads (offline).

text
Cut a supplier package from one verified output directory for a customer whose
SBOMFlow reads suppliers/<dir>/intake.json. Offline; nothing is sent.
FactValue
Groupsharing — Share & hand off
Stabilityexperimental
Regimeany
Readsnothing itself; its verb reads one analyze output directory.
Writesnothing itself; its verb's help names what it writes
Networkoffline — This command has no network-capable path.
Exit codes0 a verb ran and returned 0 · 2 no verb given, or the verb refused
Machine outputhuman-only-by-design — group dispatcher: prints usage/guidance only; the machine surfaces are its nested verbs

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit

Examples

Emit the package a customer's supplier intake reads, from one run whose pack and gate verify.

sh
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.

text
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.
FactValue
Groupsharing — Share & hand off
Stabilityexperimental
Regimeany
Readsone analyze or audit output directory whose pack and gate verify against its run seal; with --include-vex, the reviewer decisions that run applied.
Writesintake.json, the shared SBOMs, emitted-from.json and, with --include-vex, vex.json in --to; the recipient states received when the package arrives
Networkoffline — This command has no network-capable path.
Exit codes0 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 outputartifact-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

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesAn output directory produced by sbomflow analyze or audit.
--toDIRnoneanyyesWhere the package is written: absent or empty, never a symlink, outside EVIDENCE_DIR.
--supplierIDnoneanyyesContact-free supplier id the recipient's intake accepts ([a-z0-9][a-z0-9._-]{0,63}).
--scopeTEXTnoneanyyesWhat this evidence covers, in words the recipient will read.
--valid-untilDATEnoneanynoDate (YYYY-MM-DD) until which you state this package is current; recorded in emitted-from.json.
--supersedesIDnoneanynoThe earlier package this one replaces, recorded verbatim in emitted-from.json.
--include-vex(flag)false—noAlso 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.

sh
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.

sh
sbomflow supplier-package emit out --to supplier-handoff --supplier gateway-module --scope 'gateway module release' --valid-until 2027-06-30

A supplier id that is not an operator id (here a space and an address) is refused before anything is written. Exits 2.

sh
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).

text
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.
FactValue
Groupsharing — Share & hand off
Stabilityexperimental
Regimeany
Readsone 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.
Writesthe 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 namesone file
Networkoffline — This command has no network-capable path.
Exit codes0 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 outputartifact-suffices — writes the lifecycle-event document at --output and cle-export-receipt.json beside it; those files are the machine surface

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
STORE_OR_EVIDENCE_DIRSTORE_OR_EVIDENCE_DIRnoneanyyesAn evidence store (index.json) or an output directory from sbomflow analyze or audit.
--outputFILEnoneanyyesWrite 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.

sh
sbomflow export-cle out --output handoff/lifecycle.cle.json

Export from a store: every stored release of the one product it holds, each checked against the digest the store recorded.

sh
sbomflow export-cle .sbomflow-store --output handoff/lifecycle.cle.json

A security-updates promise becomes the end of support; the hardware-availability date the same release declared never does.

sh
sbomflow export-cle supported --output handoff/lifecycle.cle.json

Declared releases (backfill) also get a released event, on the release date the operator declared.

sh
sbomflow export-cle history --output handoff/history.cle.json

Releases on two channels are two products here, and a lifecycle document describes one, so this store is refused and nothing is written. Exits 2.

sh
sbomflow export-cle two-channels --output handoff/history.cle.json

See 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).

text
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.
FactValue
Groupsharing — Share & hand off
Stabilityexperimental
Regimeany
Readsone analyze or audit output directory: its release record, checked against the run-completion seal, and the evidence pack the record states the digest of.
Writesthe 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 namesone file
Networkoffline — This command has no network-capable path.
Exit codes0 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 outputartifact-suffices — writes the ReqIF document at --output and reqif-export-receipt.json beside it; those files are the machine surface

Options

OptionValueDefaultAllowedRequiredHelp
-h, --help(flag)none—noshow this help message and exit
EVIDENCE_DIREVIDENCE_DIRnoneanyyesAn output directory from sbomflow analyze or audit.
--outputFILEnoneanyyesWrite the ReqIF document here (file): a path outside the input, replaced if present; one export per directory.
--as-ofAS_OFnoneanynoPinned CREATION-TIME and LAST-CHANGE (default: the evidence pack's own generated_at).
--exploitation-deltaFILEnoneanynoA 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.

sh
sbomflow export-reqif out --output handoff/release.reqif

Refused (exit 2): an export is handed on, so it is never written inside the output directory it restates; nothing is written. Exits 2.

sh
sbomflow export-reqif out --output out/inside.reqif

See also: sbomflow export-cle, sbomflow bundle, sbomflow help sharing.