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):

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 file's shape (it parses as JSON/TOML/XML/YAML) never counts — every config file in existence has a shape. Neither does high entropy, nor living under a vendor/ directory. A rule that promotes on a single keyword 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.

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.

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.

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.

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

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 2025 draft SBOM minimum elements (a validate presence check)#

sbomflow validate runs a presence check for the four data fields CISA's 2025 Minimum Elements for a Software Bill of Materials adds to the NTIA 2021 baseline — component hash, license, generation tool name, and generation context — 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 guidance is a draft, and this is a presence check — never a conformance certification.** CISA published the 2025 Minimum Elements as a Request for Comment in the Federal Register on 2025-08-22 (docket CISA-2025-0007); the comment period closed 2025-10-03 and, as of this writing, it is not a final 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.

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

Because the guidance is a draft, 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.

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.

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. with_supplier is always 0 for SPDX 3.x documents: that profile expresses supplier via a graph relationship rather than a flat field, and SBOMFlow does not guess at that shape.

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 and deliberate. TR-03183-2 states SHA-512 for the deployable component's hash; SBOMFlow records a SHA-256 content digest, so a recorded digest is reported invalid rather than quietly accepted. And the guideline states an email address or URL for the SBOM creator; SBOMFlow records the producing tool and version, which is neither — supply a creator contact in your own publishing step if a reviewer expects that form.

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:

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.

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.

Opt-in artifacts are swept when their flag is off, whichever policy you pick. That matters most for the VEX family: a stale vex.json left beside a fresh evidence pack would assert not_affected about findings it never saw.

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 it (pip install 'sbomflow[validate]') before shipping an SBOM to a customer.

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.

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.

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