Evidence outputs

Produced by every analyze/audit run, offline, with no flags (the exact count is pinned by a drift-guard test that runs a real analysis and compares it against the published figure, so this page never needs to hard-code it):

A run that assessed no requirement regime (requirement_regime: none)#

The CRA view is one thing SBOMFlow can do, not the frame every run has to sit in. The task-oriented guide is Use SBOMFlow without CRA assessment; this section is the artifact-by-artifact reference. Set requirement_regime: none in sbomflow.yaml, or pass --requirement-regime none to analyze, audit, init or quickstart, and the run derives no requirement graph, builds no gaps and assesses no requirement.

What changes, and nothing else:

• cra-coverage.json and cra-guidance-crosswalk.json are not written. Every other default artifact above is produced exactly as usual.
• audit no longer composes the technical documentation pack, the EU declaration draft or the CRA Article 14 drafts — all of them are derived from a requirement assessment that did not happen. It still writes the reviewer bundle.
• evidence-pack.json carries evidence_gaps: [], requirement_assessments: [], route_info: {}, and a declaration in requirement_graph: {"regime": "none", "selection": "operator_declared", "source": "sbomflow.yaml" | "--requirement-regime", "statement": "No requirement regime was applied by operator choice. Empty evidence_gaps and requirement_assessments mean NOT ASSESSED, never 'no gaps'."}. Read that statement literally. An empty gap list here is not a clean result.
• run-completion.json lists each omitted artifact in declared_not_applicable[] with the reason requirement_regime_none. The key is always present — empty on a cra run — because an absent key could only mean "written by an older build".
• validate exits 0: it subtracts a declared artifact only when the seal and the pack agree. A seal that declares an artifact away over a pack that was assessed, or a declared-absent artifact that is nonetheless present, is reported as torn_overlay. EXPECTED_ARTIFACTS stays 14 for a cra run; a none run's classification reports its own smaller total and the 14 beside it.
• standards-view and emit-user-info refuse such a directory by name. They are views over a CRA requirement assessment and have nothing to read.
• --fail-on-evidence-regression (a flag, or a policy file) is dropped to its review_recheck: part and the drop is recorded in release-gate.json's regime_excluded_policies[], rather than refused: only the new_gap: and status_regression: parts are requirement-derived.
• A gap delta is reported only when both releases carried requirement data. release-drift.json's summary.requirement_regime_comparable is false whenever either side was run under none or could not be read — so none → none, which is every release after your first, is not reported as zero movement — with a named reason (requirement_regime_changed, requirement_regime_none, requirement_regime_not_read) and a note, and both the evidence-gap and requirement-coverage change sets are emptied. These surfaces are routed through one shared predicate and print NOT COMPARED / not assessed instead of a zero: the drift report, the Release Drift table in assessment-report.html, the release notes (Markdown and CycloneDX), START-HERE.md, compare-releases on stdout, the portfolio rollup (its gap rows, and its gap totals when no release contributed) and the portfolio dashboard, which shows those as its not-recorded glyph and says how many releases carry no requirement-gap delta. audit-log.jsonl records new_gaps: null with the reason beside it. Materiality never scores such a comparison. A release that could not be read is recorded as not_read, never answered for.
• evidence-aging.json skips with the state not_applicable_by_operator_choice; its counts are null, never 0 (0 is this vocabulary's value for "a human accepted it in this very run").

A cra run — the default — is unaffected: byte-identical, apart from the one always-present declared_not_applicable key in run-completion.json.

What every reader shows for such a run

Nothing presents an unassessed run as zero. Wherever a surface would show a gap count, a coverage figure or a gaps empty state, it shows "Not assessed — no requirement regime selected by operator choice" instead, or a distinct not-assessed value beside the integer count:

• the analyze/audit transcript keeps its assessing evidence phase and reports not assessed, and the run summary reads evidence gaps: not assessed in both the observed and the review rows;
• assessment-report.html states the absence where the CRA route block would be, shows the statement in place of the requirement and gap tables, reads not assessed on every requirement-derived tile, and its footer drops the CRA sentence for a regime-neutral one;
• START-HERE.md reports Evidence gaps recorded: Not assessed …, the same in its outstanding-decision line, and lists the CRA and CRA-draft groups with a not-applicable note instead of omitting them;
• issues.md says no issue could be derived, and a known-exploited issue's determination sentence names no framework: it asks for a human determination under whatever regime governs the product, instead of stating a CRA Article 14 candidacy;
• evidence-bundle.json, sharing-pack.json and passport.json carry coverage_summary: {"state": "not_applicable_by_operator_choice", …} — on the sharing pack that block replaces the numeric one, never annotates it — plus requirement_regime: "none" and counts.evidence_gaps_state: "not_assessed" beside the integer. Their HTML renderings read the manifest, so a pack opened far from its run directory says the same thing;
• review and reviewer.html read unresolved_gaps=not assessed, and review-queue.json carries summary.unresolved_gaps_state: "not_assessed";
• notify reports gaps: not assessed in every channel body;
• store list prints gaps=not assessed, and store query --min-gaps N excludes such a release with a note naming how many were excluded — including --min-gaps 0, which would otherwise match them as satisfying the threshold;
• the SQLite evidence index carries an additive releases.gaps_state column (assessed | not_assessed, NOT NULL), so COUNT(gaps) can be told apart from "never assessed"; the index is a rebuildable cache and needs no migration;
• the portfolio dashboard shows not assessed in the release's gap cell, leaves the open-gap total unrecorded when no latest release contributed one, and says how many releases applied no requirement regime;
• metrics.json carries counts.evidence_gaps_state and requirement_regime;
• next-actions carries a requirement_regime block (always, cra or none) stating that a none run's list holds no gap action and offers no --fail-on-gaps suggestion, and its terminal rendering prints that statement for a none run. This block is the one key carried on a cra run too — see the note below;
• the quickstart/setup summaries and the setup gap walkthrough say not assessed rather than "a clean result", and explain --gap refuses by naming the declaration instead of an unknown id;
• sync-issues (whose dry run is the default; --apply is the opt-in) says why no missing-evidence issue could be planned;
• sync-issues and sync-jira default their tracker labels to sbomflow,release-evidence instead of sbomflow,cra-evidence, read from the run's own pack rather than the current config; an explicit --labels still wins. This changes the labels in github-issue-plan.json and jira-issue-plan.json, and what --apply pushes, for a none run only.

Every one of these keys is written only for a none run — with exactly one stated exception — which is what keeps a cra run's artifacts byte-identical: the evidence pack and every artifact analyze/audit writes, the reviewer bundle, the sharing pack, the passport, review-queue.json and review stdout, the reviewer console, the notification payload, the release and SQLite indexes, and the portfolio dashboard. Measured file by file against the previous build.

The exception: next-actions --json carries the requirement_regime block on a cra run as well, deliberately — a field that appears only when it has something to say is a field no reader can rely on — so that one document is not byte-identical to a build before this change. next-actions stdout is: the terminal rendering stays silent for cra.

Switching a product to none also refuses the inputs the regime removes, each naming what to take out: a declared product.class other than default, the technical_documentation, annex_i_evidence and due_diligence config keys, --emit-techdoc, --emit-incident-report, the --incident-* options, an explicit --fail-on-gaps, and a policy file that enforces fail_on_gaps. sbomflow init --requirement-regime none writes a config with none of them.

Unknown-input candidates (unknown-input-candidates.json)#

The third state of an input, and the one that used to be invisible.

SBOMFlow already models the two known states: an input it parses, and an input it recognises but cannot parse yet (which it warns about). The state it could not express was a file it recognises as nothing at all — hashed into the manifest, then silently contributing nothing. This artifact is that state, made visible.

A row appears when a file nothing else classified looks like it might carry composition. It is a worklist for a reviewer, and the boundaries are hard:

• Never a component. The Sentinel creates no component, emits no purl, and never guesses an ecosystem from a filename. Nothing here reaches the SBOM. A heuristic that invents inventory is worse than the blindness it replaces, because the invention is invisible.
• A label, never a number. Confidence is one of a fixed vocabulary — likely_manifest, likely_lockfile, likely_build_descriptor, likely_package_database, likely_firmware_or_binary, structured_unknown, low_signal. There is no calibrated model behind a "0.82", and printing one would dress a filename heuristic up as a measurement.
• Two independent signals, or nothing. Rising above low_signal requires at least two corroborating signals that observe genuinely different properties of the file; a rule that promotes on a single property is rejected outright. A Sentinel that flags every JSON file is noise, and noise trains reviewers to ignore the warnings that matter.
• Content is sampled, never recorded. Classification reads a bounded head+tail sample (64 KiB total, however large the file) taken only from files nothing else classified — a parsed or recognised file costs no extra byte. The artifact carries sampled_bytes (an integer) and derived signal names. The sampled bytes themselves are never written anywhere.
• Bounded and honest. The row list is capped; when the cap bites, the document says truncated: true and still reports the true total. Warnings are capped too — a 1,000-candidate tree produces a handful of warnings, not 1,000.
• No gate. Informational (exit 0). --strict can surface it in CI; nothing else blocks on it.
• SBOMFlow's own records are not unknown. A JSON document whose schema_version is one of the schema identifiers this build declares for its own documents — a preserved-artifact record ingest-preserved-artifact wrote into the project, for one — is never a row. Only an exact identifier counts; a lookalike sbomflow-… string this build does not declare stays in the worklist (ruleset version 3).

Nothing decompresses, executes, or reaches the network.

Observation coverage (observation-coverage.json)#

The artifact that makes zero components readable.

Every other SBOM tool can hand you an empty inventory that looks exactly like a clean one. SBOMFlow refuses to: a file it hashes but does not understand is counted, and a run that parses nothing while build descriptors, source, binaries, unsupported inputs or parse failures were present says so out loud (possible_missed_composition, with a machine-readable cause).

What it does not do matters just as much:

• No aggregate score. Each ratio keeps its numerator and denominator apart. A single "87% covered" would hide which dimension was weak and would imply a completeness claim SBOMFlow does not make — no static scanner can prove it found every component.
• No false alarms. The warning comes from a decision table, not from if no components: warn. A genuinely empty tree, a docs-only tree, and a deliberately component-free target whose manifest SBOMFlow did parse all stay silent. A tool that cries wolf gets ignored.
• No gate. Coverage is informational (exit 0). --strict can surface it in CI; nothing else blocks on it.

The signals block also records what the inputs said should have existed. A lockfile implies an installed dependency tree, a Yocto conf/local.conf implies tmp/deploy/, a Buildroot .config implies output/build/; where the implied artifact was not found beside its input, the run counts it under missing_resolved_build rather than staying silent. That is not a claim that the build is wrong — scanning a clean checkout legitimately produces it. It is the fact that whatever would have resolved there could not have been observed by this run, which otherwise reads exactly like a run that looked and found nothing. Where the implied artifact could not be inspected at all rather than found absent, it is counted separately under unreadable_resolved_build: unreadable is not absent, and neither of them is clean. The expectations are a closed table, so what this can say is enumerable rather than inferred from filenames.

sbomflow validate recomputes every total from the per-file rows, so a coverage report whose numbers do not add up is rejected rather than believed.

License evidence (a section of evidence-pack.json)#

Every run records observed license evidence over the scanned tree: LICENSE / LICENCE / COPYING files (by presence and SHA-256 — the full text is not parsed) and SPDX-License-Identifier: header tags in source files. A tag counts only where the SPDX convention puts it — in a comment — so code that merely mentions the tag name is not reported as declaring a license. Each declared tag expression is checked for SPDX syntax validity against a pinned SPDX License List snapshot; a malformed expression becomes an invalid_license_expression warning and an unrecognised identifier an unknown_license_id note — the raw string is always preserved. The assessment-report.html renders the rollup.

This is observed metadata for a reviewer, never a conclusion: it does not state the licence a component or the product is "really" under, and never infers a component's licence from a nearby LICENSE file. Turning a declared licence into a concluded one is a human-reviewed step.

A qualifier the purl cannot carry. A component row states its build configuration in its purl — ?arch=amd64, ?triplet=x64-linux. Several purl types carry no qualifiers at all: pkg:pypi/… never does, and an OS package whose vendor was not observed falls back to pkg:generic/deb/…. Where the rendered purl omits a qualifier the component states, the CycloneDX writer emits it beside the purl instead, one property per key:

It exists so two rows that differ only in a configuration the purl cannot express are still tellable apart. The purl is deliberately not widened for those types: for pypi, npm, golang, cargo, gem and composer the purl string is the osv.dev query payload, so adding a qualifier to it would change advisory matching. See docs/FINDING_IDENTITY.md.

Declared vs concluded in the SBOMs. A component's declared licence reaches SPDX licenseDeclared (and CycloneDX expression) only when it is a single, syntactically valid SPDX expression; its canonical form is emitted with the source recorded (SPDX licenseComments / a sbomflow:license_provenance property). An invalid or multi-licence declaration whose AND/OR relationship the source never states becomes NOASSERTION with every raw string preserved verbatim — never guessed. SPDX licenseConcluded stays NOASSERTION unless a reviewer supplies a license_conclusions file (config license_conclusions:) mapping a purl to a concluded expression; the engine never concludes a licence.

Both halves of that mapping must be text the reviewer wrote. A purl or a conclusion supplied as a JSON/YAML null, number, boolean, list or mapping is reported as license_conclusion_invalid and applied to nothing — the value is never converted to text, because a conversion would put a determination nobody made into the field SPDX reserves for a human's. The warning names the type, so it reads differently from the one for a field left absent or blank: the repair is to quote an expression, not to supply a missing key.

Per-component parser provenance (observed_by, a field of evidence-pack.json components)#

Each component row records which deterministic parser routine produced it in an additive observed_by field — a stable parser id such as cargo-lock, npm-package-lock, container-deb, yocto-manifest, or imported-cyclonedx for a supplier SBOM import. It exists for replay and debugging: "which code path observed this row" is a recorded fact, not a reconstruction. A row merged from several sources keeps the id of the parser that produced its primary source_file; every contributing file remains listed in source_files.

Boundaries: observed_by never affects component identity, merging, advisory matching, origin/claim labels, or any gate. The engine version is recorded once per pack (tool_version), never per component. An empty value means the producing parser was not recorded — hash-identified binary inventory rows stay empty, and packs written by older SBOMFlow versions load with the field absent. Absent provenance is reported as absent; it is never backfilled or guessed.

Supplier-declared external components (supplier_external_declarations, a field of evidence-pack.json components)#

CycloneDX 1.7 lets a supplier state that a component is external — expected to be provided by the environment, not part of the assembly — with isExternal, and give the accepted range with versionRange (vers syntax) instead of a version. When an imported document states either key, the component row carries one entry per stating document:

It is the supplier's statement and nothing more. SBOMFlow does not decide what ships: the component stays in the inventory and is still counted among the supplier-imported components; the range is never parsed, never copied into version and never used to match advisories, so a finding on such a component is still a finding. The import quality row counts declared_external_components (components whose supplier states isExternal: true) against components on the same row. The emitted CycloneDX SBOM (and the VDR, which embeds its component rows) carries sbomflow:supplier_declared_external, sbomflow:supplier_version_range and sbomflow:supplier_version_range_state; the SPDX 2.3 package carries the statement as a fixed-prefix comment line. A row with nothing stated carries no key, so every other run is byte-identical.

Supplier-stated supplier and digests (supplier_statements and declared_hashes, fields of evidence-pack.json components)#

When an imported SBOM states a component's supplier (CycloneDX supplier.name, SPDX 2.x supplier, SPDX 3.0.1 suppliedBy) or its digests (CycloneDX hashes, SPDX 2.x checksums, SPDX 3.0.1 verifiedUsing), the component row carries them, one row per statement, each naming the document that made it:

A lockfile's stated digest takes the same path with no new field: the SRI integrity npm, yarn, pnpm and bun record for the registry tarball (decoded to hex) and a stated Cargo, NuGet or other checksum of a known algorithm and length are read from the provenance the lockfile reader already records, and reach the same SBOM fields labelled "stated by a lockfile (<file>)". A component whose sources state more than one value for an algorithm — a Python lockfile lists a digest per platform wheel — carries none of them in the standard field, because none is the component's hash.

These are the document's statements, carried verbatim: nothing is inferred from a purl namespace, a registry or a URL, and SBOMFlow read none of the bytes a digest describes, so a carried digest is never content-hash identity and never "verified". An algorithm the format does not define, or a value that is not hex of the length its algorithm produces, is named in a malformed_external_sbom_component warning and not carried. The emitted SBOMs carry them in their own fields — CycloneDX supplier and hashes, SPDX 2.3 supplier and checksums, SPDX 3.0.1 suppliedBy (an Organization/Person element) and verifiedUsing — with who stated each in sbomflow:supplier_stated:<n> / sbomflow:declared_hash:<n> (CycloneDX), the package comment (SPDX 2.3) and each Hash's comment (SPDX 3.0.1). A standard field carries a value only when the statements agree: two documents naming different suppliers, or stating different digests for one algorithm, leave the field empty and every statement in the properties. A declared-withheld hash element (product.sbom_withheld_fields) omits the digests as it omits every hash. The NTIA supplier_name element and the BSI TR-03183-2 hash field count these statements, and their notes say who stated them. A row with nothing stated carries neither key, so every other run is byte-identical.

Nested components and a stated scope (CycloneDX import)#

A CycloneDX component nested in another (components[].components) is part of the delivered assembly and is imported as a component, with a dependency edge from the component it sits in — CycloneDX says nesting "is not a dependency tree", and the edge is the containment BSI TR-03183-2 counts as the dependency element. A stated scope is carried as the component's kind: required as runtime, optional as optional, excluded as dev, and the emitted CycloneDX SBOM writes the same scope back. An excluded component stays in the inventory and is still matched; the release gate exempts its findings only under the explicit exclude_dev_dependency_findings policy, as for a lockfile dev dependency. An unknown scope value is named in a warning and not guessed.

A lifecycle scope on an SPDX 3 relationship (SPDX 3.0.1 import)#

SPDX 3.0.1's LifecycleScopedRelationship is a Relationship with a scope (design, development, build, test, runtime, other). OE-core's create-spdx-3.0 class, which Yocto 6.0 uses, writes every binary package's runtime dependencies as one runtime-scoped dependsOn. An imported one is read as the relationship it is — a dependsOn is a dependency edge whatever its scope — and its scope is carried as the kind the same fact takes elsewhere: runtime gives each dependency the kind runtime (as CycloneDX scope: required does); development and test make a package named only that way not shipped (dependency_kind: dev), the SPDX 2.3 DEV_DEPENDENCY_OF and TEST_DEPENDENCY_OF rule; build, design and other state no kind, because a build-time dependency (a static library) can ship — the BUILD_DEPENDENCY_OF rule. runtime anywhere outranks a development or test scope, and any unscoped mention makes the package shipped. A scope outside the vocabulary is named in spdx3_document_not_fully_understood and the edge is still read. A dependsOn whose from is a build or another non-package element is named there too and is not turned into a dependency of the product: the image build's build-scoped dependency on its host tools is not the product's.

Non-purl identifiers (external_identifiers, a field of evidence-pack.json components)#

Each component row carries an additive external_identifiers list holding the CPE 2.3, CPE 2.2, SWID tag id, SWHID and OmniBOR/gitoid values a document stated or an operator declared. Each entry has a type, a canonical value, a source and, when the document's spelling differed from the canonical one, the declared_value it used.

This release produces three source values: imported for a supplier SBOM's own statement, operator_map for identity.cpe_map in your config, and declared_by_build for a build system's own declaration. The one producer of declared_by_build is the default scan's reader for the Yocto create-spdx-3.0 image SBOM: the CPEs a Yocto 5.1+ build writes for the recipes in its own image. The build stated them; SBOMFlow derived none of them.

source is the load-bearing field. "The supplier's SBOM states this CPE" and "our operator mapped this purl to this CPE" are different claims with different owners, and a reviewer deciding whether to trust an NVD cross-check needs to know which one they are reading. Recorded identifiers are re-emitted into the fields each format defines for them: CycloneDX cpe, swid, omniborId and swhid; SPDX 2.3 externalRefs (cpe23Type, cpe22Type, swid, swh, gitoid); SPDX 3.0.1 externalIdentifier. Where a format has room for one value and several are recorded, the rest still travel in the SBOMFlow property or comment namespace, so nothing is dropped.

Merged across sources. When a lockfile row and an imported SBOM describe the same purl, the identifiers from both are kept — deduplicated on (type, value, source) and sorted by it, so the result does not depend on which source was read first. Two sources stating the same CPE collapse to one record; a supplier's CPE and an operator-mapped one stay two.

A package with no purl keeps its identifiers. An SPDX 2.x or 3.0.1 package that declares no purl — the CPE-only shape Buildroot's generator, OE-core and some BSP vendors emit — imports with generic identity and its CPE, SWID, SWHID and gitoid identifiers, exactly as a CycloneDX component with no purl does, with the same external_sbom_component_missing_purl note at info. Two kinds of SPDX package stay out, each because the document says so: the document's subject — the one package it describes, which a CycloneDX document keeps in metadata.component — and a package the document names only as a build, development or test tool or dependency (SPDX 2.3 BUILD_TOOL_OF, DEV_TOOL_OF, TEST_TOOL_OF, TEST_OF, TEST_CASE_OF, DEV_DEPENDENCY_OF, TEST_DEPENDENCY_OF; SPDX 3.0.1 usesTool, hasTest, hasTestCase). Without a purl such a tool is not imported, and the warning names the relationship and the identifiers that went with it; with a purl it imports as before, carried as not shipped (dependency_kind: dev, CycloneDX scope: excluded). BUILD_DEPENDENCY_OF is not a tool role: SPDX 2.3's own example is Maven compile scope, which ships. An SPDX CONTAINS (and CONTAINED_BY, and SPDX 3 contains) between two imported packages, or from the subject, is a dependency edge — BSI TR-03183-2 counts the components a component contains as its dependencies — and a containment of a file is not.

Boundaries. This is identity, not an advisory route: SBOMFlow never creates a finding from a CPE, match_scope is unchanged by anything recorded here, and no gate reads it. The opt-in scan.cpe_candidates report reads it to list candidates for a human in cpe-candidates.json (see below), never findings. Nothing is derived — a CPE is recorded only when a document states it or an operator declares it, never built from a component name, because a guessed vendor is a false-positive source. Three input states stay apart: a well-formed canonical value is recorded; a well-formed non-canonical one is recorded canonicalised with the declared spelling kept beside it and imported_identifier_not_canonical raised; a malformed one records no identity and raises imported_cpe_malformed, because a string that is not a CPE sitting in a CPE field will be believed by the next reader. An empty list means none was stated — not that none exists.

NTIA 2021 minimum-elements presence (a section of evidence-pack.json)#

Every run records an ntia_minimum_elements block. For each of the seven fields in NTIA's minimum elements list — component name, version, a unique identifier (package URL), supplier, dependency relationships, the SBOM author, and a timestamp — it reports whether the field is present, partial (some components carry it), or absent, with counts and missing-component examples.

The 2021 list is the baseline this block measures, not the current authority. CISA's 2026 Minimum Elements for a Software Bill of Materials (SBOM) supersedes it (see the next section), and the block records that lineage in its own reference line so a pack read years from now still says which list its counts were taken against. The 2021 report is kept rather than replaced because packs emitted against it stay readable, and because a great deal of downstream tooling is still built around those seven fields.

This is honest field presence, never a conformance assessment: the block carries no "compliant" / "conforms" / "certified" language, and a field SBOMFlow does not record — a per-component supplier organisation, since SBOMFlow records source/build provenance rather than who produced each component — is reported absent rather than inferred. It answers "which NTIA fields are populated?" in one command; a human judges sufficiency.

CISA 2026 SBOM minimum elements (a validate presence check)#

sbomflow validate runs a presence check for the five data fields CISA's 2026 Minimum Elements for a Software Bill of Materials (SBOM) adds to the NTIA 2021 baseline — SBOM Tool Name, SBOM Generation Context, Component License, Component Hash Value, and Component Hash Algorithm — over SBOMFlow's own emitted CycloneDX 1.6 and SPDX 2.3 documents. For each element it prints whether the SBOM carries it, and names any absent one with the cataloged sbom_minimum_element_missing warning.

This is a presence check — never a conformance certification. CISA, with NSA, FBI and international partners, published *2026 Minimum Elements for a Software Bill of Materials (SBOM) on 2026-07-29, which "updates and replaces"* the NTIA 2021 minimum elements (status checked at the source 2026-08-27 and recorded, with that date, in the guidance-status register SBOMFlow ships). It is **voluntary guidance, not a rule**. SBOMFlow observes which fields its output carries; it never claims the SBOM "conforms to" the guidance, and it never fabricates a value it did not observe. The elements below are named with the 2026 document's own vocabulary, read out of the document after it was retrieved and its digest recorded in the guidance-status register. They are a **strict subset — 5 of the guidance's 17 data fields** — and partial coverage is stated as partial, never as conformity.

Where each element lives, and the honest scope of each check:

Because this observes presence rather than judging conformance, a missing element is surfaced as a validate note (never an error, and never a gate). See the warning reference for sbom_minimum_element_missing.

The two SBOMFlow rows state presence too, never conformance. A withheld declaration adds one sentence to that element's note — the producer declared this element withheld (redaction contact: …); the declaration says nothing about its value — and one summary line per document; the access pointer adds one line that says SBOMFlow did not fetch it.

A declaration omits the element's values from the documents you hand to a recipient, and from nothing else. Declare component_license withheld and cyclonedx-sbom.json carries no component licenses and none of the SBOMFlow licence properties, and spdx-sbom.json carries no component licenseDeclared, licenseConcluded or licenseComments (the described product package keeps its NOASSERTION; SPDX 3 has no licence field to omit). Declare component_hash_value (with or without component_hash_algorithm; the algorithm alone is refused, because each hash entry carries both) and the documents carry no component hashes, lockfile checksum/integrity properties, checksums or verifiedUsing. The CycloneDX VDR (--emit-vdr) embeds the SBOM's component rows and goes to the same recipients, so its components omit the same values and its metadata.properties carry the same withheld markers. The sharing pack's shared SBOMs are cut from the emitted documents and omit them too, and each carries the marker for every declared element — sbomflow:withheld_element in metadata.properties, the Withheld element (declared by the producer): … line in the SPDX comments — so a recipient of a shared SBOM can tell withheld from unknown. The redaction contact does not travel into a sharing pack: it is contact data, which the redaction contract redacts from every pack, so the recipient asks whoever handed them the pack. The two AI-BOMs (cyclonedx-mlbom.json, spdx3-aibom.json) omit the same elements from every AI model, dataset and other AI entity — for component_license the ML-BOM licenses and every licence extension property (the declared licence, its openness class, its restrictions and any licence conflict); for the hash elements the ML-BOM hashes, the SPDX verifiedUsing and every hash or digest extension property (a declared expectedHash, an unverified digest, a chat-template digest, a governing-prompt hash) — and carry the markers and the redaction contact the software SBOM carries (ML-BOM metadata.properties, after the run-level properties; SPDX AI-BOM comment lines). An AI entity's bom-ref, element id and the document serial and namespace are identity and are kept, and so is the sha256:<first 16 hex> NAME an entity receives when nothing else names it; the SPDX AI-BOM's import digest is SBOMFlow's integrity method for its own software document, not a component hash. ai-evidence.json is the AI record of the observation, as the evidence pack is the record of the scan, and keeps every value. The VEX (cyclonedx-vex.json, csaf-vex.json) embeds no component row, so a declaration does not change it. The declaration stays in each SBOM and in the VDR, and validate reads each declared element as declared withheld and not present; no finding — no warning code, because the absence is the producer's statement, not a gap. The same absence without a declaration is still a finding. What is not omitted: the evidence pack, the approval digest and every internal artifact keep what the scan observed (they are the record of the observation; the SBOM is the document you publish), and the content identity a component is referenced by — its purl, or the binary:<sha256> reference of a content-identified file — is identity, not an emitted hash, so the serial number and the SPDX namespaces do not move. The reviewer bundle (evidence-bundle.zip) carries the evidence pack itself, so it carries the observed values; the sharing pack, the auditor pack and the passport do not. Neither row adds a warning code, and a document that states neither prints exactly the notes it printed before. SBOMFlow states which fields a document carries and what its producer declared about them; it never says that an SBOM meets any guidance.

Every per-population element states the population it was checked against, and refuses to make its claim over an empty one. The three per-population elements are universal claims — "every component carries a licence" — and a universal claim over an empty set is vacuously true, so an SBOM inventorying zero components would otherwise report them present, in wording that reads as an achievement. Instead:

• a satisfied element names its denominator, e.g. Component License [22 of 22 components], so you can always see how many members the claim covers;
• an empty population is reported NOT ESTABLISHED on its own line with its own code, sbom_minimum_element_not_established — nothing was examined, which is neither a finding that the element is present nor a finding that it is missing. This includes the ordinary case where a document identifies every component by Package URL: no component is then required to carry a hash, so no hash claim is made either way — and, with no digest recorded, the Component Hash Algorithm question is never asked either.

The three populations are deliberately different — the whole inventory, its content-identified members, and the recorded digests — so an element is never answered out of another element's denominator.

Zero examined is never reported as zero problems.

Supplier intake (a section of evidence-pack.json)#

Every run records a supplier_intake block. When the scanned tree carries the conventional suppliers/<name>/ directories (each with a declared intake.json manifest), the block records every supplier (contact-free id, received date, scope note, declared files with SHA-256s), which merged components and supplier-VEX statements trace back to which supplier (component_attribution / vex_attribution), and any version_conflicts where two suppliers claim one component at different versions — both claims recorded, a warning raised, and a human decides. A manifest whose supplier or scope is not text — a JSON null, a number, a boolean, a list or an object — is reported and the supplier is skipped, rather than read as though somebody had typed the value. Without a suppliers/ directory the block is empty: discovery ran and zero suppliers were intaken.

Attribution is factual origin, never judgment: supplier-declared components remain first-class for advisory matching and gating, and supplier VEX remains context that never suppresses a gate.

A supplier may also declare an AI-BOM (ai_boms in their manifest): a CycloneDX ML-BOM or an SPDX 3.0.1 AI-profile document. Each is read, digested and reported in ai-evidence.json → supplier_ai_boms on every run, and folds nothing into this release's AI evidence until a human records an acceptance for its exact bytes through the ordinary reviews channel. A short fixed list of fields this build has no home for (model-card metrics and considerations, external references, energy figures, a supplier's safety assessment and decision thresholds) is listed as loss when present; most other fields — licences, purls, dataset descriptions, and the AI-profile properties such as ai_domain and ai_typeOfModel — are dropped without being listed, as the BOM family census measures. An accepted entity is DECLARED by that supplier — never an observation of this release. supplier_ai_boms carries each document's acceptance_key, so the artifact itself says what to record to accept it.

Due-diligence records (a section of evidence-pack.json)#

Every run records a due_diligence block. When the due_diligence config key points at a reviewer-owned records file, the block carries the operator's Article 13(6) third-party due-diligence records (which checks were performed per component, when, by which role, with what outcome), a per-supplier rollup, and counts; each latest record also becomes a hashed evidence item attached to its named components. Without a records file the block is empty. The block carries a fixed banner — recording is not adequacy: SBOMFlow hashes and surfaces the records for review and never judges the diligence sufficient.

Component ownership labels (a section of evidence-pack.json)#

Every run records an owner_labels block. When the owners config key points at a local rules file ({"rules": [{"match": "pkg:pypi/*", "owner": "platform-python"}]}), each rule's glob is tried against a component's purl, then its name, then its recorded source file — first matching rule in file order wins — and the block maps each matched component to its team label. The label rides the review queue, issues.json, and tracker sync plans as owner_label so findings route to the right team (Jira and GitHub plans also gain a per-issue owner-<team> label for tracker-side filters). It is strictly separate from the engine's built-in suggested_owner functional-area hint, and it is presentation and routing metadata only: never an assignee, never a decision, never a gate input. An unmatched component simply has no label (no "unknown" noise), a later rule an earlier rule shadows draws a warning rather than a silent skip, and a label that looks like a person instead of a team draws a privacy warning. A rule whose match or owner is not text — a JSON null, a number, a boolean, a list or an object — is reported and skipped rather than converted into a rule nobody wrote; it never reaches the first-match-wins ordering, so it cannot shadow a real rule. Without an owners file the block is empty.

Imported-SBOM quality (a section of evidence-pack.json)#

When you import a supplier's SBOM with --import-sbom / --import-sboms, every run records an imported_sbom_quality list — one entry per imported document — with the same honest field-presence idea as the NTIA check above, but pointed at what your supplier handed you instead of SBOMFlow's own output:

This is counts only, never a grade: no percentage-as-score, no letter grade, no pass/fail verdict — "your supplier's SBOM lacks versions on 6 of 22 components" is a fact you can act on, not a rating. Counts are computed from each document before any merge with your local scan or another imported document, so a component your own build also observed can never inflate what the supplier's document actually declared. For an SPDX 3.0.1 document with_supplier counts packages whose suppliedBy names an Agent the document defines with a name; a reference to an Agent it does not define states no name.

Supplier-declared cryptographic properties (a section of evidence-pack.json)#

A CycloneDX document may attach a cryptoProperties object to a component: the asset type, an object identifier, and sub-objects describing a declared algorithm, certificate, related material or protocol. SBOMFlow used to read none of it — the import named cryptoProperties as a field that had not travelled and discarded every value inside it. Now every value is kept, in a supplier_declared_crypto list with one entry per component that declared one:

This is the supplier's assertion and nothing else. SBOMFlow opened no binary, identified no algorithm, derived no security level, compared no date or key length against any published table, and emits no cryptoProperties of its own. There is no readiness figure and no quantum-safe verdict, because the set examined is one supplier's document and not your firmware. The values are recorded so a person can cross-check them: they never enter component identity, never reach the vulnerability matcher, never open or close a gate, and are never a review status.

The paths in values are derived by walking whatever the document declared, so a field a later CycloneDX revision introduces is preserved by the same code rather than dropped for being unrecognised. A value longer than 512 characters is recorded as its leading prefix with truncated set and declared_chars holding the length before the cut — a shortened value can never be mistaken for a complete one.

BSI TR-03183-2 field presence (bsi-tr03183-2-presence.json)#

The EU-facing counterpart. Every run also writes bsi-tr03183-2-presence.json, reporting each data field of BSI TR-03183-2 (Cyber Resilience Requirements for Manufacturers and Products, Part 2: Software Bill of Materials, v2.1.0) as one of five states:

Two invalid results are expected on a default run. TR-03183-2 states SHA-512 for the deployable component's hash; by default SBOMFlow records a SHA-256 content digest, so a recorded digest is reported invalid rather than quietly accepted. Set scan.file_hash_algorithms: [sha256, sha512] and the scan records a SHA-512 beside the SHA-256 for every file it reads, taken in the same read: CycloneDX hashes[] gains a SHA-512 entry after the SHA-256 one, SPDX 2.3 checksums[] a SHA512 after the SHA256, SPDX 3.0.1 verifiedUsing carries both, and the row then reads present when every component carries a SHA-512, or partial naming the rest. A component identified by coordinates (a purl) carries no digest at all, because SBOMFlow never records a hash of bytes it did not read, so a run mixing lockfile components and inventoried binaries reads partial — which is what it is. sha256 stays required: it is the identity every other artifact keys on.

The creator field is no longer permanent. The guideline states an email address or URL for the SBOM creator, and the producing tool and version is neither — so creator_of_the_sbom reads invalid until you declare product.sbom_author with an email or a url in sbomflow.yaml, after which it reads present. The contact is emitted in CycloneDX metadata.authors and metadata.manufacturer.contact, SPDX 2.3 creationInfo.creators and SPDX 3.0.1 createdBy.

SBOMFlow records only what you declared there. It never reads a contact from git config, from $EMAIL or from the OS user: an inferred contact would publish an address nobody chose to publish, and would make the emitted documents depend on the machine that ran the scan. SBOMFLOW_SBOM_AUTHOR_* is recognised and ignored for the same reason, and you are warned that it was. A declared contact is redacted from the sharing pack (shared-spdx-sbom.json keeps the Tool: creator only), so publishing it is a decision about the full SBOM, not about every artifact a run produces.

Which SBOM format the guideline accepts

TR-03183-2 also states which SBOM formats it accepts, and at which minimum version. The report renders those floors against the documents the same run emitted, in a sbom_format_floors block:

The SPDX row is expected. SBOMFlow emits SPDX 2.3 deliberately — it is the interoperable target and 3.0.1's ecosystem tooling is immature — so that document sits below the version this guideline states, and the report says so plainly rather than leaving you to compare two files by hand.

The same four states are used as for fields, and for the same reason: a format this run did not emit (unknown) and a format emitted at a version that could not be read (invalid) are different facts, and a yes/no would collapse them into one indistinguishable "not met".

Each row is a version comparison against a transcribed number, not a judgement that a document is adequate or acceptable. Which format a given reviewer or customer requires is theirs to decide.

This is field presence, never conformance: the artifact carries no "compliant" / "conforms" / "certified" language, no score and no grade, and presence here is not evidence of CRA conformity. Fields TR-03183-2 requires but SBOMFlow cannot see — the executable/archive/structured properties of a shipped file, a per-component creator's email — are reported unknown, never guessed.

Each appears only when you ask for it; all remain offline unless stated:

Written by the case commands into a case directory or a directory you name, never by analyze. Generated locally for the manufacturer to review and publish; SBOMFlow does not publish, host, sign or upload.

--as-of is what makes a run's artifacts byte-reproducible: it pins the instant every timestamp, age, expiry and window is measured from, so two runs over the same inputs with the same --as-of write the same bytes. Without it, those fields take the run's wall-clock time.

The SOURCE_DATE_EPOCH environment variable (the Reproducible Builds convention, <https://reproducible-builds.org/specs/source-date-epoch/>) sets one thing when no --as-of is given: the embedded creation timestamp of the three SBOM documents — CycloneDX metadata.timestamp, SPDX 2.3 creationInfo.created and SPDX 3.0.1 created — so two analyze/audit runs of the same inputs with the same value write byte-identical SBOMs. It is not the instant anything is evaluated at: the evidence pack's generated_at, and every age, expiry and staleness window, stay the run's own time, because SOURCE_DATE_EPOCH is the date of the source (often the last commit) and measuring a waiver's or an evidence item's validity at it would read an expired item as current. run-receipt.jsonl records the value used (event sbom_timestamp_basis). An explicit --as-of sets every timestamp, the SBOMs' included. A value that is not the decimal seconds date +%s prints is refused (exit 2, E019) before anything is written; an empty value is ignored. For a byte-reproducible pack, set --as-of, for example from the commit time in CI.

update-payload-binding.json (experimental, family update-payload-binding) is written by a run given release.update_payloads in sbomflow.yaml, and only then. For each named payload file it records its SHA-256 (and SHA-512 when scan.file_hash_algorithms includes sha512), the update format its file name selects, the inner image digests that format's parser reports held against the digests recomputed over their bytes (matches, differs, not_compared), and this release's release_id with the SHA-256 of its evidence-pack.json. release-record.json carries an update_payloads summary row per payload and, with --previous-output, update_payload_changes. A payload outside the scan root is kept under external/ and checked by store verify. A payload named inside the scan root that a symlink takes outside it is refused unread (unreadable, reason link_outside_scan_root, symlink_outside_root on stderr) and nothing is copied; name a file kept elsewhere by its real path instead. The record says this payload's bytes were recorded beside this release's evidence, and nothing about any device or rollout; it is never a gate decision or a VEX status. See docs/FIRMWARE_EVIDENCE.md.

The operator produces the file; SBOMFlow never looks at a live system. A release record describes a build. A producer that also operates what it builds — a device maker with a cloud back end, a platform team, a SaaS team, an integrator — is asked which release is deployed, and where. SBOMFlow answers only from the producer's own records: name a declaration file under release in sbomflow.yaml,

release:
  deployed_environment: ops/eu-west-deployed.json   # relative to sbomflow.yaml

and write the file with whatever tooling you already use to take an inventory:

{
  "schema_version": "sbomflow-deployed-environment-declaration-v1",
  "environment": "eu-west production",
  "taken_at": "2026-06-15T09:00:00Z",
  "source": "inventory export written by the platform team's release tooling",
  "entries": [
    {"kind": "image", "reference": "registry.example/gateway", "digest": "sha256:<64 hex>", "count": 12},
    {"kind": "service", "reference": "gateway-api", "version": "1.4.2", "count": 3},
    {"kind": "host_package", "reference": "openssl", "version": "3.0.13", "count": 40}
  ]
}

Each analyze and audit run given the key reads that one local file and contacts nothing: no cluster, registry, orchestrator or host. It writes deployed-environment.json (provenance operator_declared, is_monitoring: false) and a compact deployed_environment block in release-record.json, and prints one summary line with every count beside its denominator, for example 3 of 6 declared entries match this release, 2 of 6 differ from it, 1 of 6 are not comparable.

Each entry is compared with this release only by exact equality:

The result is matches_release, differs_from_release, or not_comparable with the reason (the entry states nothing the release can be compared with, or the release states nothing to compare it with). No range, prefix or name similarity is ever used. A declaration none of whose entries match lists every entry as differs_from_release; it is never shown as an empty or clean view.

taken_at is recorded exactly as written. When it is later than the run's own instant (--as-of, or the run time) it is flagged taken_at_later_than_run and still recorded unchanged. A declaration that cannot be read is the unreadable_file warning, and the view says not_compared; a declaration that is read and is not valid — not JSON, a repeated JSON key, an unknown key, a malformed entry or timestamp, a repeated entry, or text over its bound — refuses the run with E016 before anything is written.

The view says what two records contain. It is context for a reviewer: it never sets a VEX status, never moves the release gate or the approval digest, and says nothing about any instant other than taken_at. The declaration's format is published as the sbomflow-deployed-environment-declaration input schema (sbomflow schema list).

Every supplier VEX document a run is given (supplier_vex: / --supplier-vex, and a supplier intake's VEX) gets a row in evidence-pack.json under vulnerability_scan.supplier_vex_documents, and START-HERE.md restates each row: the document's position among the documents given, its display path and its sha256 (two files outside the product tree both show as outside-scan-root/vex.json; the position and digest keep them two rows), its format (openvex, csaf, cyclonedx, or not_read when it could not be read), and how many statements it carried, how many are naming_a_component (a component purl), naming_an_inventoried_component (a purl this run's inventory holds — the only statements a finding can carry), applied_to_a_finding, and naming_no_component (also warned as supplier_vex_statement_unscoped). A statement bound to a component with no finding for its advisory used to leave no trace anywhere; it is now counted. A statement is context for a reviewer and never a VEX status; nothing here changes a status, a gate or a warning, and a run with no supplier VEX writes no key.

Industrial, energy and building-automation advisories — from a vendor PSIRT or from a national CERT that republishes them — describe the products they are about by a CSAF branch path: vendor, then product_name, then product_version_range or product_version, sometimes with product_identification_helper.model_numbers, and almost never with a purl. SBOMFlow binds a supplier statement to a component by purl only, so such a statement stays supplier_vex_statement_unscoped. Declaring the device under identity.devices (see inputs) makes a run write device-advisory-context.json beside it, from the CSAF documents it already reads as supplier VEX. Nothing is fetched.

Identity is exact. An advisory product yields an observation for a declared device when its vendor branch equals one declared vendor spelling, letter for letter, and either a declared model number matches one of its model-number patterns or a declared product name equals one of its product_name branches. The pattern language follows each document's own CSAF version: under CSAF 2.0, ? is one character and zero or more, and a pattern with no that matches only the start of the declared model is recorded as the separate, weaker basis model_number_abbreviated (CSAF 2.0 lets a model number "stop at any point"); under CSAF 2.1 the pattern must cover the whole model number and \?, \* and \\ are literals. A product that lists model numbers yields nothing for a device whose declared models all miss them, even when the name is equal (model_list_excludes_declared). A vendor, product name or model number that differs only by letter case or outer whitespace, or a CSAF 2.1 model prefix, is listed under near_misses and never matched; the distinct product names under a declared vendor that did not match are listed too, and coverage.vendor_names_seen lists the vendor spellings the documents use, so a declaration can be corrected without SBOMFlow guessing.

Versions are evaluated only where a rule exists. A product_version is compared by exact string equality (a leading v is never stripped; it is noted when it is the only difference). A vers: range is validated strictly against the pinned vers-spec text (commit 599b53de29e0271314e82347516845f18928237a, pre-standard) and evaluated for vers:semver (SemVer 2.0.0 grammar and precedence) and for vers:intdot when every version is a whole dotted number (4.2.1, never 4.2.1-HF1 or V4.2.1); states all versions and vers:none/ none. A range with a single comparator (vers:intdot/<4.2.3) is read as vers Clause 5.3.3.1 defines that comparator. Every other statement — a vls such as <=3.08.02, free text, a malformed vers: string, generic, lexicographic, datetime, a package-ecosystem type, a type the text does not list — is recorded verbatim as not_evaluated with its reason, for a person to compare with the declared firmware version.

Each observation quotes the advisory: which advisory, which product, its model list and version statement, and the product-status bucket the advisory lists it under (known_affected, fixed, …) with the vulnerability ids, including a status the advisory states only through a relationship such as installed_on. coverage counts documents, products, identity outcomes and version results, each beside its denominator, and all_versions is never added to in_range; devices_without_observation lists every declared device that found nothing, with how many documents and products were examined. START-HERE.md restates the artifact's own summary line.

The observations are context for a reviewer. None is a finding, a VEX status, an entry in the evidence pack's vulnerabilities, a release-gate input or an approval-digest input: the pack, release-gate.json and the approval digest are the same with or without identity.devices. The artifact's schema is the experimental device-advisory-context family (sbomflow schema show device-advisory-context).

Your requirement list compared with what this run recorded; SBOMFlow did not write, interpret or review these requirements and states nothing about conformity. A customer questionnaire, an internal release policy or a checklist your own staff wrote from a standard you hold is a list of questions only you can answer. SBOMFlow can say, for each question you tie to one of its selectors, what this run's own records hold. The walk-through is in Run a release against your own requirement list.

Name the lists in sbomflow.yaml, relative to that file:

requirement_catalogs:
  - catalogs/release-policy.json
  - catalogs/customer-questionnaire.json

Each analyze and audit run validates every list with the same validator as regime-profile validate, registers it for that run as a view_profile that is packaged: false and customer_authored (it can never take an id SBOMFlow ships), and writes requirement-catalog-view.json. Per list it records the path the config wrote, your profile_id, title and version, a content digest, who authored it and its legal_review exactly as you recorded it. Per requirement it records your id, title, citation (not_stated when you gave none) and note verbatim, and one of four states with its meaning:

Each selector row also carries SBOMFlow's one-line detail, the counts it read (for preserved_artifact_kind, present rows and accepted rows apart) and, under recorded, any value quoted from the run's records as it was recorded.

Four selectors answer release-process questions from records the run already holds, and quote what they read under recorded: approval_present (the approval count, and the required, satisfied_roles and missing_roles lists and every role the run recorded — a role recorded nowhere reads evidence_not_observed, never an invented one), gate_recorded (the gate's own sentence, enforcement mode and exit code verbatim, and with policy_requirement:NAME that policy's recorded outcome — an informational run keeps "No release-gate policy enforced"), artifact_digest_recorded (the SHA-256 release-record.json carries for a produced file; a file the run did not produce reads evidence_not_observed) and release_comparison_present (the comparison id and previous release of release-drift.json). They read the gate after it decided and never feed it.

A list that is missing, cannot be read, is not JSON, or is refused by the validator — an unsupported selector, an id SBOMFlow ships or another list in the run already uses, or text that states a conformity outcome — raises the requirement_catalog_unreadable warning on stderr, and the view names it not_evaluable with every problem. The run continues. The view is never a gate input: release-gate.json, evidence-pack.json, release-record.json and the approval digest are the same with or without it, under requirement_regime: cra or none.

When you pass --previous-output, issues.json gains rows marked lifecycle_status: "resolved" — one per evidence gap or advisory finding that was present in the previous release and is absent now. The row names the gap_id or vulnerability_id that closed, so you can close the matching tracker item against something specific.

Those ids are, by definition, not in the current evidence-pack.json: that is what resolved means. validate therefore checks them against the resolved set recorded in release-drift.json — the same artifact the rows were written from — rather than against the current pack. Open rows are unchanged: their ids must still resolve against the current pack, and an id that appears in neither place is still reported.

The check is not skipped for resolved rows, only pointed at the right ID space. If no drift artifact is present, the strict current-pack check applies, so a run that lost its drift record reports the contradiction instead of accepting it.

Resolving a gap is an observation about the artifacts, never a conclusion: the row says a human should confirm the evidence change before closing anything.

ai-evidence.json is written on every run and is the record. The two AI-BOMs are opt-in projections of it into third-party standards, for a consumer whose tooling reads CycloneDX or SPDX. They add no authority, resolve no conflict, and reach no verdict; both are validated against the publisher's own schema, vendored in the package.

They link, they do not duplicate. The ML-BOM carries a CycloneDX BOM-Link (urn:cdx:<serial>/<version>) to cyclonedx-sbom.json rather than folding model weights into the component list a vulnerability scanner walks. The SPDX AI-BOM declares spdx3-sbom.json's product element in SpdxDocument.import and hangs its contains relationships off that IRI — two SPDX documents naming one IRI are naming one element. Without --emit-spdx3 there is no external IRI to import, so the product is declared locally and the document's own comment says which happened.

A declared entity names where it was declared, never where that file sat on your machine. Every entity folded in from --ai-manifest carries a locator — the manifest's location plus a JSON pointer to the entry, such as #/models/detector — in ai-evidence.json and in both AI-BOMs (sbomflow:locator:N). The location follows the rule every other supplied input follows: relative to the product root when the manifest sits inside it, and outside-scan-root/<file name> when it does not. The same manifest kept in two different directories outside the product gives byte-identical artifacts.

That link can be checked — but only when SBOMFlow held the bytes. When the run also emitted spdx3-sbom.json, the reference carries verifiedUsing: a sha256 computed over the exact bytes that run wrote for that file. It is a digest of the document's content, never of its path — hashing a path would prove only that a string had not been edited.

Three states, and they are not two. The AI-BOM's comment says which one applies, because SPDX 3.0.1 allows only four properties on an ExternalMap and the reason cannot sit beside the reference:

The last two are deliberately kept apart. Empty is something SBOMFlow observed, not something it failed to get, and sha256("") is a perfectly real digest of nothing that would read as a verified reference. In a pack written before this field existed, and in any pack where the field is absent, absence means not recorded — never "verified".

What that digest claims, and what it does not. Exactly one sentence: the content digest of the exact referenced bytes was recorded. It records what those bytes were when the document was written — it says nothing about what is on disk now. It asserts nothing about the referenced document being schema-valid, correct, complete, of known provenance, authentic, signed, signature-verified, trusted, reviewed, accepted, in conformity with anything, safe, or independently corroborated. For the same reason a declared digest — a supplier's expectedHash for a file SBOMFlow never opened — never appears in a verifiedUsing anywhere in this document; it travels as sbomflow:unverified_digest.

The digest is self-attested. Read verifiedUsing with that in mind. The same run computed the sha256, over a file that same run had just written. Nothing external checked anything. A faulty or tampered run emits a document and a digest that agree with each other, and comparing the pair against itself cannot see that. What the digest does detect — provided this AI-BOM itself is unaltered — is alteration of the referenced file after the pack was written: a reviewer who resolves spdx3-sbom.json later can tell whether it is still the file this AI-BOM referenced. The proviso is not decoration. Neither document is indexed in artifact-manifest.json (which lists the inputs a run scanned, not the artifacts it emitted), so anyone who alters the target can alter the digest beside it consistently and the pack will show nothing. Read without it, this is tamper-evidence; read with it, it is drift-and-corruption evidence, which is what it actually is. The AI-BOM's own comment says all of this in those words rather than leaving a reader to infer it from a property named verifiedUsing.

The unknown is stated, never guessed. SPDX 3.0.1 gives three properties SBOMFlow cannot observe an explicit noAssertion member — ai_autonomyType, ai_useSensitivePersonalInformation and dataset_datasetType — and those are emitted as noAssertion rather than omitted, because an absent property reads to many consumers as "no". ai_safetyRiskAssessment is never emitted: its enumeration has no "no assertion" member and SBOMFlow performs no safety assessment, so any value would be an invented risk rating. A CycloneDX modelCard is omitted entirely when nothing was declared, because an empty card asserts a model card exists.

Run-level properties both AI-BOMs carry#

These describe the DOCUMENT and the run that produced it, not any one component, so they are not information loss — there is nothing in the internal graph they fail to carry. They are listed here because every sbomflow: name a reader may encounter is documented somewhere on this page, and a test asserts exactly that.

Information loss: CycloneDX 1.6 ML-BOM#

Facts SBOMFlow holds that the standard has no field for. Each one is carried through CycloneDX's own documented extension mechanism — namespaced properties — so it is visible without ever being dressed up as a standard field.

Any declared field this writer does not place in a native CycloneDX field is still emitted, as sbomflow:declared:<field>. Nothing is dropped.

Information loss: SPDX 3.0.1 AI + Dataset profiles#

Carried through SPDX's own extension_CdxPropertiesExtension, which is why the document declares the extension profile alongside ai, core, dataset and software.

As in the ML-BOM, any declared field this writer does not place in a native SPDX property is still emitted, as sbomflow:declared:<field>. Nothing is dropped — and a test asserts both directions, so an extension name with no row above fails the build just as a row with no emitted name does.

Every component, advisory finding, and evidence row — in the assessment report and in the reviewer console — carries exactly one small provenance chip. The chip's text names the source family the row's fact came from; its title carries the full provenance string.

unrecorded is highlighted deliberately. A row whose provenance was never captured must say so: a blank cell would read as "observed", which is a claim SBOMFlow has not earned. Chips are real text rather than icons, so screen readers announce them and they survive printing.

A section with no rows is a reported state, not a blank table. Every generated HTML surface — the assessment report, reviewer console, evidence bundle, drift report, and dashboard — renders the same empty-state block naming what is absent, what that absence does and does not establish, and the next command. Empty sections are never hidden: the section and its column headers stay visible, because the absence is itself part of the evidence.

The wording is deliberate where a reader is most likely to misread it:

• No advisory findings means no advisory matched the observed components. It is not proof that the release is free of vulnerabilities. It reflects the advisory sources this run used and the components it observed, so check usable_intelligence in vuln-source-health.json before reading it as an all-clear. That flag counts real sources only: a run whose findings came from the bundled synthetic sample feed reports usable_intelligence: false with synthetic_intelligence_used: true, and a run that consulted no source at all reports no_source_configured: true. Zero findings means something different in each case.
• No missing-evidence gaps means every requirement SBOMFlow can assess automatically has an observed signal. Manual-only requirements never create gaps, so this is not a statement of completeness or conformity.
• No approvals recorded means no human has signed the release off. An empty ledger blocks a release only when a policy enforces required roles or a quorum.

A count that cannot be read shows as —, never as a number#

The same rule applies one level down, to the numbers themselves. sbomflow dashboard can be pointed at a release-index.json it did not write, and the portfolio rollup reads each release's release-drift.json off disk. When a field that should hold a count holds something else — a string, a list, null, a fractional number, true, or a negative number — that value is not converted into a count:

• a dashboard cell renders —, the same mark the page uses for a timestamp it does not have, and the two headline counts add a line to the page's Index warnings block naming the field and what was found there;
• a release-drift.json whose summary counts cannot be read joins products_without_drift as unreadable, which is listed and, as that block already states, never counted as zero changes.

true is rejected explicitly rather than read as the number one, and a negative count is rejected by value with the number quoted back, because the type is right and the number is still impossible. A genuine 0 is untouched: zero is a real observation and still renders as 0.

product_id and release_id in release-record.json are derived, not assigned: they are stable hashes of what you declared — product.name, product.version, plus the product line, variant, channel and build id. Declare the same inputs and you get the same ids on every machine, which is what lets a store, a release index and a drift comparison line one release up against another.

The consequence runs the other way too. If you declare nothing, SBOMFlow derives Unnamed Product / 0.0.0 — the honest answer for a product nobody named — and hashes those. Every undeclared run therefore derives the same ids, so two unrelated code trees analysed that way are one release by identity, and nothing keyed on release_id can separate them. The same is true of a scaffolded sbomflow.yaml whose REPLACE-ME values have not been edited yet.

That situation is reported rather than left silent. A run whose identity rests on a placeholder records the product_identity_from_placeholder warning in scan-warnings.json, and a release-drift.json whose two sides carry one release_id records that fact in its own warnings array.

Read both as observations about what was declared, not as findings about the product:

• The warning does not mean a collision has happened — only that the ids carry nothing that would prevent one.
• The drift line does not mean the two outputs are the same build, and does not mean they differ. It records that release_id cannot tell them apart. The deltas in that file are unaffected and remain exactly what the two outputs contain.
• Neither is a failure. The run completes and exits as it otherwise would, which is deliberate: analysing a directory before writing any config is the first thing quickstart does.

Declaring product.name and product.version gives the release an identity of its own. Declaring them never renumbers releases you already recorded — ids already written to a store or an evidence pack are read as recorded and are never recomputed.

Re-running analyze or audit into a directory that already holds a run does not silently mix the two. Choose what should happen:

sbomflow analyze . --output ./evidence                                # overlay (default)
sbomflow analyze . --output ./evidence --on-existing-output clean     # one run, nothing stale
sbomflow analyze . --output ./evidence --on-existing-output refuse    # write nothing, exit 2

Two guarantees are worth stating plainly:

• clean only ever removes names SBOMFlow generates. A file you put in the directory — a supplier SBOM, your notes — is never touched, so pointing --output at the wrong directory cannot destroy your data.
• refuse triggers on a previous run, not on a non-empty directory. A directory holding unrelated files is not an SBOMFlow output, so refusing there would be noise.

Every artifact a run writes only conditionally is swept by a later run that does not write it, whichever policy you pick. That covers an opt-in flag that is off, a config key that is absent, and an artifact written only when there is something to state: a clean re-run with --emit-vex has no statement to make, so it writes no vex.json or csaf-vex.json, and removes the earlier run's copies rather than leaving two vulnerabilities the new release does not contain beside its pack. The same holds for advisory-reconciliation.json (written only when there are findings), decision-migration.json (only when decisions keyed by advisory were supplied), vuln-source-health.json, audit-log.jsonl and release-drift.html. The VEX family matters most: a stale vex.json left beside a fresh evidence pack would assert not_affected about findings it never saw, and — before this sweep covered it — was even sealed into the run and listed in START-HERE.md.

Only names this engine's own artifacts use are removed. A file of yours under any other name (my-vex.json, vex.json.orig, your notes) is left where it is; README.txt, the one sharing-pack name an operator may own, is never swept. The run says what it removed where it records what it wrote: the artifacts_written event in audit-log.jsonl carries stale_artifacts_removed, the sorted names of the earlier run's artifacts this run removed and did not write again. The key is absent when nothing was removed, so a first run, or a re-run with the same inputs, logs exactly what it always did. SBOMFlow's own tests derive the set of conditional artifacts from the writer itself, so a new one added without a sweep fails there by name.

evidence-bundle.zip is swept the same way. It archives the directory as it stood when it was composed, so a copy left by an earlier run describes that run's pack, not this one. Every analyze or audit removes it before writing, and audit --zip then composes a fresh one from this run's files. An overlay run without --zip therefore ends with no ZIP rather than a stale one, and START-HERE.md never names a ZIP that does not hold the pack beside it. Only that name is removed: an archive of your own under another name is left alone.

sbomflow bundle applies the same rule after it re-seals a directory. Recording a decision (review, approve) rewrites members the ZIP archived, so after audit --zip, a decision and bundle without --zip, the old evidence-bundle.zip no longer matches the re-sealed bundle. bundle removes it and prints what it removed, how many names it disagreed on, and the bundle <dir> --zip <dir>/evidence-bundle.zip command that composes a current one. A ZIP the re-seal left accurate is kept, and an archive under any other name is never touched.

compare-releases follows the same rule for the optional files it writes into its own --output: release-drift.html (--html) and engineering-release-notes.cdx.json (--release-notes-format cyclonedx or both). A re-run into the same directory that does not ask for one removes the earlier run's copy before it writes anything, so it never sits beside a release-drift.json it does not describe, and prints one line per file it removed, beside the lines naming what it wrote:

Removed release-drift.html left by an earlier run (this run does not write it): OUT/release-drift.html

Nothing is printed when nothing was removed. Only those two names are ever removed. The file you name with --release-notes FILE is yours and is never removed — not on a later run that omits the flag, and not on a run where you point it at one of those two names. Your own files under any other name stay where they are, and so does .sbomflow-output, which marks the directory as SBOMFlow output. A file you created yourself under one of those two exact names is treated as the earlier run's, as every sweep here treats a name SBOMFlow generates. If the removal is refused (a read-only directory), the run stops with E004 before writing anything. If the --release-notes path cannot be resolved, nothing is removed — it cannot be shown to differ from those names — and a note: on stderr names each earlier optional output left in place.

compare-releases never writes into an analyze or audit output directory. An --output that holds a run-completion.json is another run's sealed record: writing there would rewrite that run's release-drift.json and remove the release-drift.html its seal lists, and validate would then fail an honest pack. The command refuses with E031, names the seal, and reads, writes and removes nothing; give it a directory of its own. A seal it cannot examine (a dangling link, a permission it does not hold) refuses the same way, because only proof of absence shows the directory is unsealed. The analyze writer's own sweep is held to the same line from the other side: every name it removes is checked against what the run has already written before anything is unlinked, so a sweep can never remove a file the run's seal lists.

What the run seal says was written after it#

run-completion.json is written at the end of the write phase, and a run still writes a few files after it. The seal cannot bind their bytes (the bundle ZIP archives the seal itself), so it names them in run_completeness.written_after_seal and lists them in requested_artifacts:

• START-HERE.md on every run;
• evidence-bundle.zip on audit --zip;
• release-drift.html on analyze --drift-html when release drift is produced.

validate checks that each named file is present when it reads the directory. A run killed after the seal and before one of them is therefore reported as requested_missing with the file's name, not as complete. A seal with no written_after_seal key predates the declaration, and validate treats it as unknown rather than as "nothing owed". Two files are neither bound nor listed: the .sbomflow-output marker, written before the scan starts, and run-receipt.jsonl, which exists from the start of the run and records its own run_complete event last. On audit --zip that event is written after the ZIP.

When validate compares evidence-bundle.zip with the directory, each missing-entries or extra-entries line states how many names it covers, for example (13 missing, first 5 listed), and lists up to five of them.

When the run seal itself is missing#

Every run from SBOMFlow 0.5.0 on writes run-completion.json, so its absence from a directory holding every required artifact means one of two things: the run stopped after its required artifacts were written, or the file was removed. validate decides which reading applies from the pack's own recorded producer, evidence-pack.json's tool_version:

The remedy is to re-run analyze or audit; never recreate the token by hand. A present run-completion.json is always verified, whatever version the pack records. store add admits a token_missing_for_producer directory tagged rejected_by_validate, and supplier-package emit refuses it as unsealed.

sbomflow validate ./evidence

Validation checks structure, cross-artifact consistency (counts, references, finding keys), hashes, the audit-log hash chain, and draft watermarks. A tampered or partially copied directory fails with exit code 4. Optional extras add official JSON-Schema validation when installed; without them the structural baseline still runs and says exactly what was skipped.

Note what that means in practice: the official-schema check is the one that only runs with an extra installed, so a default install cannot tell you whether an emitted SBOM would satisfy a consumer's own SPDX or CycloneDX tooling. Install the extra's package into the same environment (python -m pip install jsonschema) before shipping an SBOM to a customer. There is no package-index entry for v0.5.5, so pip install 'sbomflow[validate]' is not a route to it.

The two SBOM exports are also round-trip stable: re-importing an exported cyclonedx-sbom.json or spdx-sbom.json yields the identical component set (name, version, and purl), so downstream tooling never sees an invented or dropped component. This is regression-tested offline, alongside the official CycloneDX 1.6 / SPDX 2.3 schema-conformance checks above.

Every generated HTML surface is light by default. Reviewers who live in dark editors can generate the dark palette instead:

sbomflow analyze . --output evidence --report-theme dark

--report-theme {light,dark} is accepted by analyze, audit, compare-releases, dashboard, and review-view, and it reaches every surface that command writes — the assessment report, reviewer console, evidence bundle, sharing pack, drift report, and dashboard.

Three deliberate properties:

• Chosen when the file is written, not when it is read. There is no prefers-color-scheme switch and no JavaScript, so a portable evidence file looks the same on every machine that opens it, and the palette is reproducible from the command that produced it.
• The default is unchanged. A light document emits no data-theme attribute, so the dark rules in the stylesheet stay inert.
• Paper is always light. Printing a dark document forces the light palette, whichever theme was generated — a dark page on white paper burns ink and reads badly.

Contrast#

Every foreground/background pair the stylesheet renders together meets WCAG 2.1 AA (4.5:1) in the dark palette. The ratios below are computed from the stylesheet itself by an automated test, so they cannot drift from what ships.

cyclonedx-sbom.json carries one CycloneDX compositions entry over the product component, so a recipient can tell whether "not listed" may mean "not affected":

• unknown when this run recorded anything that bounds what it saw — a scan warning the run seal counts as partial, an observation coverage report marked indeterminate, or an input recognised and not parsed, failed to parse, or not read (the recognised_unsupported, parse_failed, refused_resource_limit, refused_path_safety and refused_symlink dispositions). Each is listed in scan-warnings.json / observation-coverage.json.
• not_specified otherwise.

It is never complete: a file scan cannot know about statically linked or vendored code it did not recognise, so SBOMFlow does not state that its own list is complete. Nor incomplete, which asserts that more components exist. A supplier package cut with supplier-package emit states the same value (unknown for a partial run), decided by the same rule. SPDX 2.3 and SPDX 3.0.1 have no completeness construct, so those documents are unchanged.

The serialNumber is deterministic: a UUIDv5 over the product name and version and the component set, so the same inputs give the same SBOM. Every CycloneDX document SBOMFlow writes (the SBOM, VEX, VDR, ML-BOM and release notes) derives its own serial the same way, and a VEX names the SBOM beside it by a BOM-Link (urn:cdx:<serial>/<version>) that carries the SBOM's serial.

The UUID version is 5, on purpose. The CycloneDX 1.4 to 1.7 schemas accept any RFC 4122 UUID in serialNumber, and version 5 is one. Two published texts say otherwise:

• CycloneDX's description says every BOM SHOULD have a unique serial "even if the contents of the BOM have not changed".
• The IANA registration of the urn:cdx namespace says in its assignment text that BOM serial numbers are version 4 UUIDs. Its syntax admits any RFC 9562 UUID.

SBOMFlow departs from both deliberately: a random serial would make two runs over the same inputs produce different bytes, and byte-identical output is what lets a reviewer diff and reproduce an SBOM. A tool that insists on version 4 will reject these serials; nothing in SBOMFlow presents them as version 4. A corrected SBOM for a release you already shipped would therefore get a new serial and version: 1, and a recipient holding both could not tell a correction from an unrelated BOM. CycloneDX's rule for a modified BOM is to keep the serial and increment version, and SBOMFlow follows it when — and only when — you say which output it revises:

• analyze --previous-output <dir> (or previous_output_path) whose cyclonedx-sbom.json names the same product name and version as this run, with different components / dependencies / compositions: the new SBOM keeps that document's serialNumber and takes its version + 1, and release-record.json gains sbom_revision naming the superseded serial, version and SHA-256 beside the new document's SHA-256.
• The same, with identical content: the previous serial and version are kept, so with the same --as-of the SBOM is byte-identical to the one it restates, and no sbom_revision is written.
• A different product version (the ordinary release-to-release comparison), or no previous output: unchanged — a fresh deterministic serial and version: 1.
• A previous SBOM that cannot be read, is not CycloneDX, or has no usable serial or version changes nothing, and a previous_output_unavailable warning says why.

sbom_revision says which document this one supersedes; it does not say the revision is correct or approved. The --emit-mlbom BOM-Link names the revised version. SPDX documents are unchanged.

With a fixed --as-of timestamp, repeat runs over the same inputs are byte-identical — including the bundle ZIP. Without --as-of, only documented runtime timestamps (and fields derived from them, such as the audit-log hash chain) differ; components, edges, gaps, warnings, and purls do not. That is what makes the artifacts diff-able and reviewable.

--emit-metrics is the one exception under --as-of: metrics.json records wall-clock phase durations and a peak memory figure, so its bytes differ between two otherwise identical runs, and so do the row that run-completion.json keeps for it and a ZIP that archives both. The run id does not move. run-completion.json lists every produced artifact in produced_artifacts with its size and SHA-256, and run_id is a digest over those rows — except that metrics.json enters it by name only, the same way the bundle manifest leaves metrics.json out by name. Two identical runs with metrics on therefore share a run_id. The metrics.json row still carries its size and digest, and validate still checks them: leaving the file out of the identity does not leave it out of the seal. A run without --emit-metrics computes exactly the run id it always did.

For the field-level schema of every artifact — filename, schema id, and top-level keys — see the artifact schema reference.

Next: read your first bundle · warning codes · exit codes