Integrity, provenance and reproducibility

Check signatures, provenance and reproducible bytes. This page documents every command in the integrity group, in the order sbomflow help integrity 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#

mcuboot-verify, cosign-verify, provenance-check, verify-package-artifacts, reproducible-compare, diffoscope-compare and prov-map check signatures, provenance statements and reproducible bytes. Each records what it observed; none is a certification. sbomflow help integrity lists them.

Who this is for: bootloader engineers, supply-chain engineers, build engineers, release engineers, dependency owners and traceability owners.

`sbomflow mcuboot-verify`#

Verify an MCUboot image's integrity + (opt-in) signature against an operator key.

text

Read an MCUboot image's header and TLVs, check its hash, and, opt-in, its
signature against an operator-supplied public key, plus any expectations
given: a key hash, an algorithm, a minimum security counter, encryption. The
verdict is the exit code: an image that cannot be verified, or an expectation
not met, exits 1; the document is still printed.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	one MCUboot image and, opt-in, an operator-supplied public key.
Writes	stdout (the verification document, or to the file --output names)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` the image met every expectation checked · `1` the image could not be verified, or an expectation was not met · `2` a missing or unreadable image
Machine output	machine-native — prints its verification observations as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead; the exit code carries the verdict

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`path`	`path`	none	any	yes	An MCUboot image file.
`--public-key`	`PUBLIC_KEY`	none	any	no	Operator-supplied PEM public key (opt-in).
`--expect-key-sha256`	`EXPECT_KEY_SHA256`	none	any	no	Expected KEYHASH (hex) to require.
`--expect-algorithm`	`EXPECT_ALGORITHM`	none	any	no	Expected signature algorithm (e.g. ecdsa-sig).
`--min-security-counter`	`MIN_SECURITY_COUNTER`	none	any	no	Minimum acceptable security counter.
`--require-encrypted`	(flag)	false	—	no	Require an ENCRYPTED_* flag.
`--output`	`OUTPUT`	none	any	no	Write mcuboot-verification.json here (file; default stdout).

Examples

Read an MCUboot image's TLVs; with no key to check it against it is unverifiable and exits 1. Exits 1.

sbomflow mcuboot-verify firmware/image.bin

Require an algorithm and a minimum security counter, writing the document to a file; this image reports an integrity mismatch, so it exits 1. Exits 1.

sbomflow mcuboot-verify firmware/image.bin --expect-algorithm ecdsa-sig --min-security-counter 1 --output mcuboot-verification.json

Bytes that carry no MCUboot header are reported as such.

sbomflow mcuboot-verify firmware/firmware.bin

See also: sbomflow mcuboot-evidence, sbomflow cosign-verify, sbomflow provenance-check.

`sbomflow cosign-verify`#

Optional: verify a blob against a local key + offline Sigstore bundle via cosign (never required).

text

Optional: verify a blob against an operator-supplied local key and an offline
Sigstore bundle by running the local cosign; never required, and nothing is
fetched. With no cosign available the document still prints, recording
`available: false`.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	a blob, an operator-supplied public key and an offline Sigstore bundle; it runs the local cosign.
Writes	stdout (the verification document, or to the file --output names)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` the document was written, including when cosign is not available · `2` usage error
Machine output	machine-native — prints its verification observations as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead; with cosign absent it still prints the document, recording `available: false`

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`target`	`target`	none	any	yes	The blob/artifact to verify.
`--key`	`KEY`	none	any	yes	Operator-supplied local public key.
`--bundle`	`BUNDLE`	none	any	yes	Offline Sigstore bundle.
`--executable`	`EXECUTABLE`	cosign	any	no	cosign executable (default: cosign).
`--output`	`OUTPUT`	none	any	no	Write cosign-verification.json here (file; default stdout).

Examples

Verify a blob offline; with no cosign installed the document says available: false.

sbomflow cosign-verify cosign/blob.bin --key cosign/cosign.pub --bundle cosign/bundle.json --executable no-such-cosign

Write the document to a file.

sbomflow cosign-verify cosign/blob.bin --key cosign/cosign.pub --bundle cosign/bundle.json --executable no-such-cosign --output cosign-verification.json

See also: sbomflow mcuboot-verify, sbomflow provenance-check, sbomflow verify-bundle.

`sbomflow provenance-check`#

Check an in-toto/SLSA provenance statement against expectations (offline; no SLSA level claimed).

text

Read one in-toto or SLSA provenance statement, plain or DSSE, record what it
declares, and check it against the expectations given (predicate type,
builder, build type, source, revision, subject digest). Unset means not
checked; a match is an observation, never a SLSA level. An expectation not met
exits 1.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	one in-toto or SLSA provenance statement, plain or DSSE; nothing is downloaded.
Writes	stdout (the statement's recorded fields and each expectation's verdict, or to --output)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` read, and every expectation given was met · `1` an expectation was not met · `2` a missing or unreadable statement
Machine output	machine-native — prints its provenance-check observations, expectation verdicts included, as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`path`	`path`	none	any	yes	An in-toto/SLSA provenance statement (plain or DSSE) JSON file.
`--expect-predicate-type`	`EXPECT_PREDICATE_TYPE`	none	any	no	Predicate type the statement must declare (for example https://slsa.dev/provenance/v1). Unset means not checked.
`--expect-builder-id`	`EXPECT_BUILDER_ID`	none	any	no	Builder id the statement must name. Unset means not checked; a match is an observation, never a SLSA level.
`--expect-build-type`	`EXPECT_BUILD_TYPE`	none	any	no	Build type the statement must declare. Unset means not checked.
`--expect-source-uri`	`EXPECT_SOURCE_URI`	none	any	no	Source repository URI the statement must name. Unset means not checked.
`--expect-source-revision`	`REVISION`	none	any	no	Source revision (commit) the statement must name. Unset means not checked.
`--expect-subject-sha256`	`EXPECT_SUBJECT_SHA256`	none	any	no	SHA-256 the statement's subject must carry. Unset means not checked; nothing is downloaded to verify it.
`--output`	`OUTPUT`	none	any	no	Write provenance-expectation-check.json here (file; default stdout).

Examples

Record what a SLSA v1 provenance statement declares.

sbomflow provenance-check provenance/slsa_v1.json

Require its predicate type.

sbomflow provenance-check provenance/slsa_v1.json --expect-predicate-type https://slsa.dev/provenance/v1

A builder it does not name fails that expectation and exits 1. Exits 1.

sbomflow provenance-check provenance/slsa_v1.json --expect-builder-id https://example.invalid/builder

See also: sbomflow prov-map, sbomflow cosign-verify, sbomflow analyze.

`sbomflow verify-package-artifacts`#

Verify lockfile-recorded digests against local package cache directories.

text

Check the package digests a run's lockfiles recorded against the
operator-supplied local package cache or registry-export directories.
Offline and observation-only: a package not found in a cache is reported,
never assumed; the result is written beside the evidence pack.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	a run's evidence-pack.json lockfile digests and the local package cache directories named.
Writes	package-artifact-verification.json into the directory, or at --output
`--output` names	one file
Network	offline — This command has no network-capable path.
Exit codes	`0` ok · `2` a missing or unusable evidence pack
Machine output	artifact-suffices — writes digest-verification observations JSON

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 evidence-pack.json file or output directory containing it.
`--artifact-root`	`ARTIFACT_ROOTS`	none	any	yes	Local cache/registry-export directory to search (repeatable).
`--output`	`OUTPUT`	none	any	no	Where the verification document is written (file). Default: package-artifact-verification.json beside the evidence pack.
`--as-of`	`AS_OF`	none	any	no	Pinned generated_at timestamp.

Examples

Check a run's lockfile digests against a local package cache.

sbomflow verify-package-artifacts out --artifact-root rootfs

Write the document to a named file, at a pinned time.

sbomflow verify-package-artifacts out --artifact-root rootfs --output package-artifact-verification.json --as-of 2026-07-01T00:00:00Z

See also: sbomflow analyze, sbomflow provenance-check, sbomflow reproducible-compare.

`sbomflow reproducible-compare`#

Compare two independent build-output trees by artifact digest (offline).

text

Compare two independently produced build-output trees file by file by artifact
digest, optionally recording each build's SOURCE_DATE_EPOCH. Differences are
reported, not refused; --ignore excludes files known to be nondeterministic.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	two build output directories.
Writes	stdout (the per-file comparison, or to the file --output names)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` compared, whether or not the builds match · `2` a missing build directory
Machine output	machine-native — prints the digest comparison of the two build trees as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`build_a`	`build_a`	none	any	yes	First build output directory.
`build_b`	`build_b`	none	any	yes	Second build output directory.
`--ignore`	`GLOB`	none	any	no	Relative-path glob of known-nondeterministic artifacts to ignore (repeatable).
`--source-date-epoch-a`	`SOURCE_DATE_EPOCH_A`	none	any	no	SOURCE_DATE_EPOCH for build A (provenance).
`--source-date-epoch-b`	`SOURCE_DATE_EPOCH_B`	none	any	no	SOURCE_DATE_EPOCH for build B (provenance).
`--output`	`OUTPUT`	none	any	no	Write reproducible-comparison.json here (file; default stdout).

Examples

Compare two builds file by file.

sbomflow reproducible-compare builds/build-a builds/build-b

Two builds that differ are reported, not refused.

sbomflow reproducible-compare builds/build-a builds/build-c

Ignore known-nondeterministic files, writing the document to a file.

sbomflow reproducible-compare builds/build-a builds/build-c --ignore '*.bin' --output reproducible-comparison.json

See also: sbomflow diffoscope-compare, sbomflow verify-package-artifacts.

`sbomflow diffoscope-compare`#

Optional: explain differences between two artifacts via diffoscope (never required).

text

Optional: explain the differences between two artifacts by running the local
diffoscope; never required. With no diffoscope available the document still
prints, recording `available: false`.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	two artifacts; it runs the local diffoscope when there is one.
Writes	stdout (the comparison document, or to the file --output names)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` the document was written, including when diffoscope is not available · `2` usage error
Machine output	machine-native — prints its diffoscope comparison observations as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead; with diffoscope absent it still prints the document, recording `available: false`

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`path_a`	`path_a`	none	any	yes	First artifact.
`path_b`	`path_b`	none	any	yes	Second artifact.
`--executable`	`EXECUTABLE`	diffoscope	any	no	diffoscope executable (default: diffoscope).
`--output`	`OUTPUT`	none	any	no	Write diffoscope-comparison.json here (file; default stdout).

Examples

Explain differences between two builds; with no diffoscope the document says so.

sbomflow diffoscope-compare builds/build-a builds/build-c --executable no-such-diffoscope

Write the document to a file.

sbomflow diffoscope-compare builds/build-a builds/build-c --executable no-such-diffoscope --output diffoscope-comparison.json

See also: sbomflow reproducible-compare.

`sbomflow prov-map`#

Map a traceability.json to a documented W3C PROV-DM subset (model guidance; offline).

text

Map a run's traceability.json (from --emit-traceability) onto a documented
subset of the W3C PROV-DM model. Model guidance only: the mapping adds no
evidence and no claim.

Fact	Value
Group	`integrity` — Integrity, provenance & reproducibility
Stability	stable
Regime	any
Reads	one traceability.json, from a run with --emit-traceability.
Writes	stdout (prov-mapping.json, or to the file --output names)
`--output` names	one file (stdout when omitted)
Network	offline — This command has no network-capable path.
Exit codes	`0` ok · `2` a missing or unreadable traceability file
Machine output	machine-native — prints the PROV mapping of a traceability file as JSON on stdout by default, no flag needed; `--output` writes the same document to a file instead

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`path`	`path`	none	any	yes	A traceability.json (from --emit-traceability).
`--output`	`OUTPUT`	none	any	no	Write prov-mapping.json here (file; default stdout).

Examples

Map a run's traceability to a documented W3C PROV-DM subset.

sbomflow prov-map traced/traceability.json

Write the mapping to a file.

sbomflow prov-map traced/traceability.json --output prov-mapping.json

See also: sbomflow provenance-check, sbomflow bundle, sbomflow analyze.

SBOMFlow documentation. Engineering release-evidence support only — not a compliance or conformity claim, and not legal advice.

Integrity, provenance and reproducibility

Overview#

sbomflow mcuboot-verify#

sbomflow cosign-verify#

sbomflow provenance-check#

sbomflow verify-package-artifacts#

sbomflow reproducible-compare#

sbomflow diffoscope-compare#

sbomflow prov-map#

`sbomflow mcuboot-verify`#

`sbomflow cosign-verify`#

`sbomflow provenance-check`#

`sbomflow verify-package-artifacts`#

`sbomflow reproducible-compare`#

`sbomflow diffoscope-compare`#

`sbomflow prov-map`#