Trace and crash evidence in the release record

Firmware teams keep runtime traces and crash dumps from many tools: a streaming trace from Tracealyzer and TraceRecorder, a SystemView recording, a Zephyr core dump, a CrashCatcher or minidump file, a CTF trace from LTTng, a perf.data file, a network capture. This page shows what SBOMFlow does with those files, step by step, on a synthetic example you can run yourself. Every command on this page is offline and is executed, in order, by SBOMFlow's own test suite.

In 60 seconds#

The question it answers. Months after a release, someone asks: which trace or dump did we review for exactly which firmware of which release, who decided what about it, and is it still the same file? SBOMFlow keeps the answer as part of the release record:

• These bytes. Each file gets a small record with its name, size and SHA-256, and what a person stated about it: the release, the scenario, the tool, the firmware image it ran on. A statement is recorded as a statement, never as a measurement.
• This firmware. The image you name is hashed and, at release time, looked up among the files the release scan hashed. A build id or version you state is compared with what the image declares about itself.
• This decision. A named reviewer records a conclusion and its limits against the file's digest. The decision covers those bytes and no others.
• Still the same. Each later run re-hashes the original. One changed byte suspends the decision, and a changed record fails bundle verification.
• Across releases. The next release's comparison lists what was added, removed or decided anew, and shows an earlier decision about identical bytes as context, never as a decision for the new release.

What it deliberately does not do.

• No trace analysis. SBOMFlow never decodes events, samples, registers or memory. For a few open formats it reads the identity a file's header declares about itself (the table below says exactly which fields); for every other format it reads nothing inside the file.
• No copies of your originals. Only the small records travel into the evidence directory, the bundle and the ZIP. A trace or dump can hold memory contents and device identifiers, and keeping the original stays with you.
• No upload. Nothing on this page opens a network connection, and SBOMFlow never runs, drives or connects to the tool that wrote a file.
• No gate. A trace, a missing decision, a rejection or a mismatch changes no release gate, VEX status or approval digest. The release decision stays with the people who make it.
• No compliance claim. The record is engineering evidence of what was reviewed. It says nothing about whether a product is secure or conforms to any regulation.

The journey at a glance.

The example#

The files ship with SBOMFlow's source under examples/trace-and-crash-evidence/, and each says what it is in its own bytes or in a sidecar file. None is a recording of a device. Every file describes one target, the one the firmware image is built for: a Zephyr application on a 32-bit little-endian ARM core. The field alert's entries were written by the open-source DFM library itself, compiled and run in a host harness, so they are that library's genuine output. The TraceRecorder files are synthetic, written from the library's pinned layout as that target stores them, because the library's host harness cannot write a 32-bit Zephyr header; the other files were written from the published formats, and the .svdat files are short text files rather than that tool's format. The example's PROVENANCE.md says how each file was produced. The tool names are what an engineer states when recording each file.

The example is two releases of one sensor node, each in its own directory. Its captures, by release:

Each release also has firmware/zephyr.elf, a stand-in image that declares a GNU build id (a default Zephyr build declares none; see Build identity in practice), and an sbomflow.yaml.

1. Record each file, and the image it ran on#

Work in a copy, so the example stays as it is:

cp -R examples/trace-and-crash-evidence trace-walkthrough
cd trace-walkthrough/2.4.0
sbomflow ingest-preserved-artifact captures/boot-to-idle.psf \
  --release-id 2.4.0 --scenario "boot to idle, cold start" \
  --tool-name "Percepio Tracealyzer" --tool-version 4.11 \
  --artifact-kind runtime_trace \
  --firmware-image firmware/zephyr.elf \
  --firmware-build-id 4f1c2a9e7b3d5e6f80112233445566778899aabb \
  --firmware-version 2.4.0 \
  --output preserved/boot-to-idle.preserved-artifact.json

sbomflow preserved artifact — PRESERVED, NOT ANALYSED

  Artifact       boot-to-idle.psf (532 bytes)
  SHA-256        6fa5eca4839e5a378dc185311bc1c809648fd1cd68495bc5f465033a0b45b03f
  Format hint    psf extension trace [psf_extension_trace], from the file
                 name's extension [filename_extension]; the hint comes from
                 the name alone
  Evidence kind  runtime trace (runtime_trace), stated by the operator; not
                 read from the file

  Stated by you (user_supplied), each value exactly as given:
    Firmware build ID       4f1c2a9e7b3d5e6f80112233445566778899aabb
    Firmware image name     zephyr.elf
    Firmware image SHA-256  ff13a15e0a2d4ef3c7c97f389f3ac4889ae800cb19b7876f739a7d24f8ca4ac2
    Firmware version        2.4.0

  Declared by the file, read by the tracerecorder-psf reader:
    Byte order                      little  [byte_order]
    RTOS, named from the kernel ID  Zephyr  [kernel]  (looked up)
    64-bit target bit               0  [option_64_bit]
    Core count                      1  [core_count]
    Extension                       syscalls  [extension_name[1]]
    Extension version               3.7.0  [extension_version[1]]
    Read now for this screen only: the record does not store these values; the
    release run that declares it reads the header again and records what
    it finds.

  Gate    this record never affects a release gate.

The record keeps the JSON field names (firmware_gnu_build_id, firmware_image_sha256, artifact_kind); the terminal prints each with a plain label, and ends with the Next: step that declares the record in sbomflow.yaml.

• Say which image the capture ran on, at capture time. The person at the bench knows it; the person assembling the release months later does not. --firmware-image hashes the image and records its SHA-256 and file name, never its path. --firmware-build-id and --firmware-version record what you state; a build id is not a checksum and a version is never a stand-in for a digest.
• What the file declares is shown at once. For a format a reader is registered for, the command reads the header exactly as the release run will, and prints it: here the kernel, the word size, the core count and the extension the TraceRecorder library registered. It reads no event, and the values are shown only: the record stores the digest and your statements, and the release run reads the header again. A closed format such as .svdat says so here, and a format no reader knows keeps "content not inspected".
• The format hint comes from the file name, and only from it. It is a label, not a check; the header block above is what the bytes say.
• --tool-name and --tool-version are the tool you state, here the host application. The TraceRecorder library built into the firmware has its own version, which its header does not declare; put it in --notes when a reviewer will need it.
• --artifact-kind is what you say the file is, from a closed vocabulary (runtime_trace, core_dump, crash_report and others). It is never guessed from the name or the bytes.
• Anything you did not state is listed as missing rather than filled in with a default.

The other two files of this release:

sbomflow ingest-preserved-artifact captures/motor-loop.svdat \
  --release-id 2.4.0 --scenario "motor-control loop, full load" \
  --tool-name "SEGGER SystemView" --artifact-kind runtime_trace \
  --firmware-image firmware/zephyr.elf \
  --output preserved/motor-loop.preserved-artifact.json
sbomflow ingest-preserved-artifact captures/unit-0042.zephyr-coredump \
  --release-id 2.4.0 --scenario "field unit 0042, watchdog reset" \
  --tool-name "Zephyr coredump" --artifact-kind core_dump \
  --firmware-version 2.4.0 \
  --output preserved/unit-0042.preserved-artifact.json

The core dump came back from a field unit that reported version 2.4.0; nobody has the image digest for it, so none is stated. That is recorded as it is, and the release run below says what it could and could not compare.

2. Declare the records for the release#

The example's sbomflow.yaml names each record, the original it describes and the release's firmware image:

release:
  id: "2.4.0"

requirement_regime: none

preserved_artifacts:
  - record: preserved/boot-to-idle.preserved-artifact.json
    original: captures/boot-to-idle.psf
    firmware_image: firmware/zephyr.elf
  - record: preserved/motor-loop.preserved-artifact.json
    original: captures/motor-loop.svdat
    firmware_image: firmware/zephyr.elf
  - record: preserved/unit-0042.preserved-artifact.json
    original: captures/unit-0042.zephyr-coredump
    firmware_image: firmware/zephyr.elf

A record is read only when it is declared: SBOMFlow never searches a directory for traces. requirement_regime: none means no regulatory requirement is assessed in this run; the evidence record works the same with or without one.

3. Run the release audit#

sbomflow audit . --output evidence
sbomflow review evidence

  Preserved artifacts (decisions about preserved files, a separate unit; not
    in awaiting_review):
    Awaiting a decision   3
    Decided               0
    - boot-to-idle.psf
      preserved-artifact:sha256:6fa5eca4839e5a378dc185311bc1c809648fd1cd68495bc5f465033a0b45b03f
      Original        verified
      Capture states  stated image is in this release
      Build ID match  not established — the file declares no GNU build ID
    - unit-0042.zephyr-coredump
      preserved-artifact:sha256:b534095e8424c4f0dcb8c25fc2d119946d79b7beeae509309b49ba6f51e8781a
      Capture states  stated without a digest
    - motor-loop.svdat
      preserved-artifact:sha256:bc436848c5f473d1340595d27e4bdfb3dede7c9560d2e104490d6dc4def80121

Each file's first lines say what was checked: the original's bytes, then what the capture record states about the image (the positive tie most firmware has, since a default build declares no build id), then the build id.

evidence/preserved-artifacts.json holds one row per file. Each row carries the checks the run made, each saying exactly what it shows:

For the boot trace, every stated value agrees with what the release shows: the image digest, the build id the image declares and the version. Each comparison is listed with its result:

{
  "state": "stated_image_in_release",
  "comparisons": [
    {"with": "declared_firmware_image_sha256", "result": "agrees"},
    {"with": "declared_firmware_image_gnu_build_id", "result": "agrees"},
    {"with": "run_release_identity", "result": "agrees"}
  ]
}

A differs in that list warns preserved_artifact_capture_firmware_differs: two statements about the same image disagree. It is not evidence of tampering, it suspends no decision and it reaches no gate; a person reconciles the two.

The core dump is in a format with a published specification, so SBOMFlow read its 12-byte file header and nothing after it — no registers, no memory:

{
  "reader": "zephyr-coredump",
  "fields": [
    {"field": "magic", "value": "ZE", "origin": "extracted"},
    {"field": "header_version", "value": "2", "origin": "extracted"},
    {"field": "target_code", "value": "3", "origin": "extracted"},
    {"field": "pointer_size_log2", "value": "5", "origin": "extracted"},
    {"field": "flags", "value": "0x00", "origin": "extracted"},
    {"field": "fatal_error_reason", "value": "0", "origin": "extracted"}
  ]
}

Its meaning says declares_no_build_identity: this format has no field naming the firmware or the build, so the link to the release comes only from what a person declared. Numbers are shown as the file carries them; no architecture or fault reason is named from a code the specification does not list.

The .svdat recording is in a closed format, and its row says so rather than staying silent:

{
  "state": "not_applicable",
  "reader": null,
  "fields": [],
  "meaning": "a closed format: its layout is neither published in a specification nor defined by open-source code, so by policy SBOMFlow reads nothing inside the file and no reader may claim it; the file's hash, its custody record and the review decision are recorded all the same"
}

The boot trace is a TraceRecorder streaming trace. No specification document defines that format; the open-source library that writes it does, so SBOMFlow read its 32-byte header under that library's source, pinned to one commit, then the timestamp block and the entry table the library writes after it (see The entry table below), and no event. The entry table holds one extension, the Zephyr port's syscalls extension, and four thread entries whose names are withheld and only counted:

{
  "reader": "tracerecorder-psf",
  "fields": [
    {"field": "byte_order", "value": "little", "origin": "extracted"},
    {"field": "format_version", "value": "0x000e", "origin": "extracted"},
    {"field": "kernel_id", "value": "0x9aa9", "origin": "extracted"},
    {"field": "kernel", "value": "Zephyr", "origin": "looked_up"},
    {"field": "option_64_bit", "value": "0", "origin": "extracted"},
    {"field": "core_count", "value": "1", "origin": "extracted"},
    {"field": "platform_config", "value": "Zephyr", "origin": "extracted"},
    {"field": "platform_config_version", "value": "4.3.0", "origin": "extracted"},
    {"field": "timestamp_frequency_hz", "value": "64000000", "origin": "extracted"},
    {"field": "os_tick_rate_hz", "value": "10000", "origin": "extracted"},
    {"field": "entry_count", "value": "5", "origin": "extracted"},
    {"field": "entries_object", "value": "4", "origin": "computed"},
    {"field": "entries_extension", "value": "1", "origin": "computed"},
    {"field": "extension_name[1]", "value": "syscalls", "origin": "extracted"},
    {"field": "extension_version[1]", "value": "3.7.0", "origin": "extracted"}
  ],
  "withheld": [
    {"field": "entry_names", "reason": "4 entry name(s) withheld: entry names are the names the application gave its tasks, interrupts, queues and other objects, user text that can carry product or customer names; they were not read, and each entry is only counted by class"}
  ]
}

The Zephyr port registers syscalls with the kernel's own version, so the 3.7.0 beside it and the v3.7.0 the release's west.yml pins can be read side by side; SBOMFlow shows both and compares neither. The clock values are this synthetic example's, not a board's.

The header declares a kernel by number; the name beside it is looked up in the kernel ports the pinned library defines, so its origin is looked_up, and the row's note says so. The entry counts are SBOMFlow's own count of the table's entries by class, so their origin is computed; entry_count is the number the table itself states. The header describes the same target as the image: Zephyr, little endian, 32-bit (option bit 3, option_64_bit, is clear), one core. It is the only link a header gives between a trace and a target, and it is a shape, not an identity. Like the dump, the header names no firmware or build (declares_no_build_identity). All three files are hashed, re-verified, linked to the image and reviewable, whichever of them a reader could open.

The kernel the trace declares is also set beside the components this release's SBOM lists. The example's west.yml pins zephyr at v3.7.0, so the SBOM lists it, and the row says so, as context:

{
  "state": "sbom_lists_component",
  "declared_kernel": "Zephyr",
  "kernel_id": "0x9aa9",
  "component_names_compared": ["zephyr", "zephyr-sources"],
  "sbom_components": [
    {"name": "zephyr", "version": "v3.7.0", "purl": "pkg:generic/zephyr@v3.7.0"}
  ]
}

It is one rule: the SBOM component's name, case-folded, equals a name a pinned table gives that kernel. It shows the SBOM names the kernel the trace was built for, and nothing more: it does not show the trace was recorded on that component or version, and no version is compared, because the platform configuration version the header carries (4.3.0) is not the kernel's release.

4. Record what you concluded#

Open each file in the tool that produced it and decide what it shows. Then record the conclusion and its limits against the file's digest:

sbomflow review evidence \
  --accept preserved-artifact:sha256:6fa5eca4839e5a378dc185311bc1c809648fd1cd68495bc5f465033a0b45b03f \
  --reviewer fw-lead \
  --note "Boot to idle within budget on a cold start; covers the cold-start path only"

Recorded preserved-artifact:sha256:6fa5eca4839e5a378dc185311bc1c809648fd1cd68495bc5f465033a0b45b03f -> accepted
  decision file: evidence/reviews.json

sbomflow review evidence \
  --accept preserved-artifact:sha256:bc436848c5f473d1340595d27e4bdfb3dede7c9560d2e104490d6dc4def80121 \
  --reviewer fw-lead \
  --note "Control loop met its deadline at full load for the recorded 60 s; no other load examined"
sbomflow review evidence \
  --needs-more-evidence preserved-artifact:sha256:b534095e8424c4f0dcb8c25fc2d119946d79b7beeae509309b49ba6f51e8781a \
  --reviewer fw-lead \
  --note "Watchdog reset on unit 0042; root cause not established from this dump alone"
sbomflow audit . --output evidence --reviews evidence/reviews.json

• --accept, --reject and --needs-more-evidence take the full review key, a --reviewer and a non-empty --note; without them the decision is refused and nothing is written.
• The key is the file's digest. A different file, even under the same name, is a different key and stays unreviewed.
• The re-run applies the decisions it is given with --reviews. Every row now reads accepted or needs_more_evidence, with the reviewer and the note beside it, and evidence/release-record.json lists each record copy by its SHA-256 under preserved_artifact_refs.

5. The next release, and what changed#

Release 2.4.1 has a new image, a re-captured boot trace, the same motor-loop recording, and one field alert that produced its own entries, a trace and a core dump. Record them the same way. The alert's three files share a --capture-session, so a reviewer sees they came from one event; they are still three files with three decisions:

cd ../2.4.1
sbomflow ingest-preserved-artifact captures/boot-to-idle.psf \
  --release-id 2.4.1 --scenario "boot to idle, cold start" \
  --tool-name "Percepio Tracealyzer" --tool-version 4.11 \
  --artifact-kind runtime_trace \
  --firmware-image firmware/zephyr.elf \
  --firmware-build-id 9d2e4b6a8c0e1f3a5b7c9d0e1f2a3b4c5d6e7f80 \
  --firmware-version 2.4.1 \
  --output preserved/boot-to-idle.preserved-artifact.json
sbomflow ingest-preserved-artifact captures/motor-loop.svdat \
  --release-id 2.4.1 --scenario "motor-control loop, full load" \
  --tool-name "SEGGER SystemView" --artifact-kind runtime_trace \
  --firmware-image firmware/zephyr.elf \
  --output preserved/motor-loop.preserved-artifact.json
sbomflow ingest-preserved-artifact captures/dfm_trace.psfs \
  --release-id 2.4.1 --scenario "field alert 7f3, trace" \
  --tool-name "Percepio Detect" --artifact-kind runtime_trace \
  --capture-session alert-7f3 --firmware-version 2.4.1 \
  --output preserved/alert-7f3.trace.preserved-artifact.json
sbomflow ingest-preserved-artifact captures/cc_coredump.dmp \
  --release-id 2.4.1 --scenario "field alert 7f3, core dump" \
  --tool-name "Percepio Detect" --artifact-kind core_dump \
  --capture-session alert-7f3 --firmware-version 2.4.1 \
  --output preserved/alert-7f3.dump.preserved-artifact.json
sbomflow ingest-preserved-artifact captures/alert-7f3.dfm-alert \
  --release-id 2.4.1 --scenario "field alert 7f3, alert entries" \
  --tool-name "Percepio Detect" --artifact-kind crash_report \
  --capture-session alert-7f3 \
  --output preserved/alert-7f3.alert.preserved-artifact.json

No --firmware-version is stated for the alert's entries: the file declares one itself, and the release run below shows it.

Run the release audit against the previous release's output, then compare the two releases:

sbomflow audit . --output evidence --previous-output ../2.4.0/evidence
sbomflow compare-releases --previous ../2.4.0/evidence --current evidence --output drift

Wrote preserved-artifact changes: drift/preserved-artifact-changes.json
  Preserved artifacts: compared, 10 changes between the two releases
  added: cc_coredump.dmp sha256:314c8e74fca0 (not reviewed yet)
  added: dfm_trace.psfs sha256:33a411897a3c (not reviewed yet)
  added: alert-7f3.dfm-alert sha256:4b5abb25aa89 (not reviewed yet)
  added: boot-to-idle.psf sha256:b95108bd6d61 (not reviewed yet)
  removed: boot-to-idle.psf sha256:6fa5eca4839e (accepted)
  removed: unit-0042.zephyr-coredump sha256:b534095e8424 (needs more evidence)
  decision not carried: motor-loop.svdat sha256:bc436848c5f4: accepted -> not
    reviewed yet (no decision is recorded in this release)
  same stated scenario, decision not carried: boot-to-idle.psf
    sha256:b95108bd6d61 (not reviewed yet) and the previous release's
    boot-to-idle.psf sha256:6fa5eca4839e (accepted): two records state "boot
    to idle, cold start"; not the same capture, and no decision is carried
  other changes: 3 (stated associations, custody records or run checks); each
    is listed in preserved-artifact-changes.json

The comparison is by digest, so each line names the file, its review status and the start of its SHA-256. The re-captured boot trace is new bytes: the 2.4.1 trace is added and the 2.4.0 trace removed, although both are called boot-to-idle.psf. Because both records state the same scenario text, the two are also set side by side as a same stated scenario pair, so the new capture can be read beside the old one and the decision made about it:

[
  {
    "stated_scenario": "boot to idle, cold start",
    "decision_state": "decision_not_carried",
    "current": {"name": "boot-to-idle.psf", "review_status": "unreviewed"},
    "previous": {
      "name": "boot-to-idle.psf",
      "review_status": "accepted",
      "reviewer": "fw-lead",
      "in_current_release": false
    }
  }
]

A pair means two records state the same scenario text, compared as exact strings, and nothing more: the file name is never used, the bytes differ, and it does not show the same test was run the same way. The 2.4.0 decision is shown as context; it is not carried, and the 2.4.1 trace still needs its own. The pairs are listed under stated_scenario_pairs and are not counted among the changes. The Zephyr dump is removed with the decision it carried. drift/preserved-artifact-changes.json holds every change in full, including the three this output only counts.

The motor-loop recording is the same bytes in both releases, so it is compared rather than added. It reads decision not carried because 2.4.0 accepted it and 2.4.1 records no decision yet: a decision is never carried across releases, and nobody re-decided anything. Its row in 2.4.1 shows what 2.4.0 decided about those bytes, as prior_decision_context, beside the row's own review and never inside it:

{
  "state": "decision_recorded",
  "status": "accepted",
  "reviewer": "fw-lead",
  "note": "Control loop met its deadline at full load for the recorded 60 s; no other load examined",
  "previous_release": {"release_id": "2.4.0", "state": "read"},
  "meaning": "a decision recorded for the same bytes in the previous release; it is not applied here and decides nothing for this release"
}

The 2.4.1 row itself still reads unreviewed. Nothing is carried forward automatically, not even for identical bytes: the image changed, and whether a recording made on the old image still covers the new one is a person's call.

The CrashCatcher dump the alert carried has its header read, and nothing past it:

{
  "reader": "crashcatcher-dump",
  "fields": [
    {"field": "magic", "value": "cC"},
    {"field": "version_major", "value": "3"},
    {"field": "version_minor", "value": "0"},
    {"field": "flags", "value": "0x00000000"}
  ]
}

The alert's entries are the one file in this release that declares a firmware version. The DFM library writes the version the device build was configured with into every alert, and SBOMFlow read it under the library's pinned source, then set it beside the version this release states, as context:

{
  "state": "agree",
  "declared_field": "firmware_version",
  "declared_versions": ["2.4.1"],
  "release_version": "2.4.1"
}

agree means the two strings are equal, and nothing more: the version is free text the device's build configuration carries, and a copied configuration keeps old text. It is never a match, never a warning and never a gate input; differ would not be a finding either. In a file holding several alerts, every alert's version is read and all of them must equal the release version for agree, and one that cannot be read makes the context not_comparable, never an agree about part of the file.

6. Decide, and hand over a bundle you can verify#

sbomflow review evidence \
  --accept preserved-artifact:sha256:b95108bd6d61035fd94be39a4ae129cc7326b1268e50421192f8ef67db8a0769 \
  --reviewer fw-lead \
  --note "Boot to idle within budget on a cold start; covers the cold-start path only"
sbomflow review evidence \
  --accept preserved-artifact:sha256:bc436848c5f473d1340595d27e4bdfb3dede7c9560d2e104490d6dc4def80121 \
  --reviewer fw-lead \
  --note "Re-examined for 2.4.1; the control loop is unchanged in this release"
sbomflow review evidence \
  --reject preserved-artifact:sha256:314c8e74fca056de8936fd7165296462b271a16c6378cdc87bc6a523644a2275 \
  --reviewer fw-lead \
  --note "Hard fault in the sensor driver; a fix is required before release"
sbomflow review evidence \
  --needs-more-evidence preserved-artifact:sha256:33a411897a3cd1bd74870a022b5829e6239f04cdf766887b5d09d6c4b4ba6e7d \
  --reviewer fw-lead \
  --note "Trace window ends before the fault; a longer capture is needed"
sbomflow review evidence \
  --accept preserved-artifact:sha256:4b5abb25aa89029fd7c18889c4f755c6935ea70162b26d2c325df24142f9454f \
  --reviewer fw-lead \
  --note "Alert from a 2.4.1 field unit; the fault is decided on its core dump"
sbomflow audit . --output evidence --reviews evidence/reviews.json --previous-output ../2.4.0/evidence --zip
sbomflow validate evidence
sbomflow verify-bundle evidence/evidence-bundle.zip --layered --require-layers content

verify-bundle (layered): NOT TRUSTED
  content   verified
  envelope  not present [not_present] — no signature in the
            bundle [no_signature_artifact]
  required  content — all met

• A --reject records a person's conclusion. It does not block the release: no decision about a preserved file reaches the release gate. Acting on it is the release owner's call.
• --zip writes evidence/evidence-bundle.zip, a deterministic handoff. It carries the five records under preserved-artifacts/ and preserved-artifacts.json, and none of the captures.
• content verified means every member re-hashed to the digest the bundle's manifest records. The verdict reads NOT TRUSTED because the bundle is not signed: an unsigned bundle is checked only against itself. Sign it with sbomflow sign-bundle when the recipient needs to know who packaged it, and verify with --key.
• Each layer's status and reason are printed in words with the code in brackets, such as not present [not_present]; --json carries the codes alone.

7. What tampering looks like#

Someone edits one of the record copies in the evidence directory:

echo "edited" >> evidence/preserved-artifacts/b95108bd6d61035fd94be39a4ae129cc7326b1268e50421192f8ef67db8a0769.json
sbomflow verify-bundle evidence --layered --require-layers content  # exits 3

  content   failed — a member does not match the
            manifest [member_integrity_failed]
      · member changed [member_hash_mismatch]:
        preserved-artifacts/b95108bd6d61035fd94be39a4ae129cc7326b1268e50421192f8ef67db8a0769.json

validate names the same copy, against its own record, and exits 4:

sbomflow validate evidence  # exits 4

    - preserved-artifacts.json: rows[3].records[0]: copy preserved-artifacts/b95108bd6d61035fd94be39a4ae129cc7326b1268e50421192f8ef67db8a0769.json does not hash to its record_sha256 [rows[3] is the row for boot-to-idle.psf; records[0] is its record 1]

Both commands only read: re-running them gives the same verdict until the file changes back.

Someone changes the original trace after it was reviewed. One appended line is enough:

echo "edited" >> captures/boot-to-idle.psf
sbomflow audit . --output evidence-after-edit --reviews evidence/reviews.json
sbomflow review evidence-after-edit

    - boot-to-idle.psf
      preserved-artifact:sha256:b95108bd6d61035fd94be39a4ae129cc7326b1268e50421192f8ef67db8a0769
      Original        CHANGED (hash differs)
      Recorded        accepted, NOT applied: the supplied original does not
                      match the bytes the record describes
                      (original_verification is mismatch), so this decision is
                      about other bytes; it is shown and suspended, never kept
      Capture states  stated image is in this release

The reviewer's decision is still shown, with the reason it is not applied. A conclusion about other bytes never carries over silently.

What SBOMFlow reads from your file#

For most trace and crash formats, SBOMFlow reads nothing inside the file: it records the digest, what you stated, and the review. A few formats declare something about themselves in their header — a version, a trace UUID, the tool or host that wrote them, occasionally a build id. For those, and only those, SBOMFlow reads the declared header fields under a cited basis:

• a published specification, cited by title, version and address; or
• open-source code that defines the format, when no specification document exists: an OSI-approved licence, pinned to an exact commit with the defining file's SHA-256, header and identity fields only, an unrecognised version refused by name, byte order taken from a marker in the file, and a row that says basis: source code.

The file's name selects which reader may run, and the leading bytes must confirm it. A file whose bytes do not match is reported as unreadable (or, under a name several formats share, as not applicable) and is never handed to another reader. Every value carries the citation and an origin. extracted is a value the file stores, and is what the file says — not something SBOMFlow verified. computed is a value SBOMFlow produced from the bytes (a count, a derived number, a position it searched for, the outcome of a check), and looked_up is a name SBOMFlow took from a pinned table for a number the file stores under another field, such as the kernel named from a TraceRecorder kernel id. Neither is ever recorded as extracted, and the build-id comparison never lists either as a string the file declares; explain and custody show print "computed by SBOMFlow" or "looked up by SBOMFlow" beside them.

Only a field in the last column is ever compared with the GNU build ids of the release's firmware images; a declared version or any other string is listed, never matched or verified (a declared firmware version is shown beside the release's stated version in declared_version_context, as context only). A match means the two files name the same build. It does not show the capture was taken on a device running that image. The full list of fields each reader reads, and the fields it never reads as a value, is in Keeping runtime and test evidence with a release, and every cited address and digest is in Supported inputs.

Recognised, and declaring nothing. A file named *.zephyr-ctf is recognised: the CTF metadata Zephyr ships declares only the CTF version and byte order, with no trace UUID and no environment block, so the row says so rather than staying silent.

Opaque formats. A format that is neither published nor defined by open-source code is never read, whatever its name, and no reader may claim it. In this build that is:

• .svdat — SEGGER SystemView recordings.

An opaque file's row reads not_applicable with that meaning, in a release run's preserved-artifacts.json and in custody show --json alike, so "closed, never read" is never confused with "no reader yet".

For an opaque file, and for every format not in the table above, SBOMFlow still records everything the journey needs: the file's SHA-256 and size, the extension hint, what you stated (release, scenario, tool, firmware image, capture session), the re-hash on every run, the firmware link, the review decision, the drift between releases and the bundle entry. Only the header read is missing.

Tracealyzer and TraceRecorder files#

Percepio's TraceRecorder library is built into firmware on FreeRTOS, Zephyr, ThreadX, ESP-IDF and bare-metal targets. Tracealyzer reads the traces it writes, and a Percepio Detect alert can carry one beside a core dump. Nothing in SBOMFlow connects to those tools; this section says what happens to their files in this build.

Beside the trace: the firmware image and a CoreSight snapshot. On an ESP-IDF target the application image you flash (<project>.bin) carries its own descriptor, including the SHA-256 of the application ELF it was built from. SBOMFlow reads it only from a file that opens with the image header's byte 0xE9 and has the descriptor's magic word at offset 32 (esp-app-image), and sets that digest beside the release ELF's. Any other .bin is read exactly as before. An Arm CoreSight trace kept as a snapshot directory is read from its snapshot.ini, trace.ini and device .ini files: the devices, cores, trace sources and buffers they declare (coresight-snapshot, coresight-snapshot-trace-metadata, coresight-snapshot-device). Trace bytes, memory images and registers are never read. Neither names a build by itself; both are context for a reviewer.

Kernel ids. A TraceRecorder header records which kernel port produced the trace as a number (kernel_id). SBOMFlow shows the number as the file carries it and, beside it, the kernel that number means in the pinned library's kernel ports (FreeRTOS, Zephyr, ThreadX, BareMetal); a number no pinned port defines is shown alone, with a note saying it is outside the table. The name is a lookup, and the row's note says so: the file declares the number, not the name.

The entry table, and the names it keeps back. After the header a streaming trace carries the recorder's timestamp block and its entry table: one entry for each extension an instrumenting library registered, and one for each task, interrupt, queue or other object the application named. SBOMFlow reads them only where their place in the file is certain — one core, not ThreadX, and the start event the library writes next found right after the entries — and otherwise says why not and keeps the header. From the table it shows how many entries of each class there are and each extension's name and version; the names your application gave its tasks and objects can carry product or customer text, so they are never read, only counted, and the row says how many were withheld. A trace the pinned library wrote in a host harness with one extension and eight named entries reads:

The example's boot traces carry these blocks, written from the pinned layout: their rows show five entries, one of them the syscalls extension, and withhold four entry names.

Keep an alert's files together. A Detect alert, like most crash-reporting alerts, arrives as more than one file. Record each file with its own record and give them the same --capture-session, as step 5 does: three digests, three review keys, three decisions, one session a reviewer can see. Keep the alert's own entries (*.dfm-alert) beside its payloads: they are the one file of the alert that declares a firmware version.

Build identity in practice#

A GNU build id is the strongest link a file can carry to a build, and most microcontroller firmware does not have one. Zephyr links with --build-id=none by default: line 7 of cmake/linker/ld/linker_flags.cmake at zephyrproject-rtos/zephyr commit 1ee3b93134be23c16ab16b9eb4183bfef63447a6 (Apache-2.0, sha256 d8fb87566fa172f7bec84b3b0fa80a062779df22615c78aca8674fa247bd1abc) sets it for every application, and the proposal to change that default, issue 54522, was closed as not planned. Many bare-metal projects do not pass the flag at all. The captures do not fill the gap: the TraceRecorder, DFM alert, CrashCatcher and Zephyr core dump formats in the table above declare no build id.

So for most firmware the link between a capture and a build is the image digest, and SBOMFlow treats it that way:

• --firmware-image hashes the image at capture time, and the release run compares that SHA-256 with the image the release declares and the files it scanned. When they are the same bytes, firmware_image reads in_release and capture_firmware reads stated_image_in_release, whether or not the image carries a build id.
• Where no build id exists, build_id_match reads not_established with the reason (the file declares none, or the release's images carry none). That describes the formats, not a failed check, and it reaches no gate.
• A version a file declares, such as a DFM alert's firmware version, is set beside the release's version as declared_version_context, never matched.

This example's stand-in images carry a build id only so the comparison can be shown. If you want one in your own images, make the link pass --build-id=sha1 instead of --build-id=none. The id is written into a .note.gnu.build-id section of the ELF; if you also ship a .bin or .hex, check that your linker script places that section in a loaded region, or the load image will not carry it.

Which field answers which question. Context only: the questions a reviewer, a customer or an internal audit commonly asks of a test or incident record, and where this record keeps what was stated or observed. It does not say any record satisfies a standard, a regulation or a customer requirement, and SBOMFlow does not decide whether the evidence is sufficient.

Other tools#

The journey is the same for any tool. What changes is only whether a header is read:

A file you rename to a name a reader claims is still checked by its leading bytes: renaming never makes SBOMFlow read something it cannot confirm.

FAQ#

Does SBOMFlow parse my trace? No. It never decodes events, samples, packets, registers or memory, and derives no finding from a trace. For the formats in the tables above it reads only the identity fields a file's header declares about itself — for a CrashCatcher dump that is eight bytes — and for a microcontroller load image the framing of each record, never a data byte. For an ESP-IDF core-dump image it also checks the image's own checksum, which hashes the bytes and decodes none of them. Everything else is recorded by digest.

Is my data uploaded? No. Every command on this page is offline, and the test suite that executes this page fails if any step opens a network connection. The originals are never copied into the evidence directory, the bundle or the ZIP; only the records are. Records contain what you typed, so do not put a customer's or a person's name into a free-text field you intend to share.

What if my tool's format is unknown? It gets the same journey without the header read: digest, statements, firmware link, review, drift, bundle, verification and tamper detection. The extension hint then reads unrecognised, which describes the file name, not the file. A reader is added only for a format with a published specification or with open-source code that defines it, under the rules above.

Can a trace block a release? No. A trace, a core dump, a missing decision, a rejection, a mismatch or a firmware disagreement changes no release gate, VEX status or approval digest, and no --fail-on-* option reads them. What it changes is what a reviewer sees: counts in START-HERE.md, the review queue, next-actions and the reviewer console. The release decision stays with the people who make it.

How does this help with the CRA or other regimes? As context. Whoever asks later — a customer questionnaire, an integrator, an internal handover, or a requirement regime your product falls under — reads the same record: which evidence was examined for which release, and what the reviewer concluded. SBOMFlow does not say whether that evidence is sufficient for any regime, maps no preserved file to a requirement, and makes no conformity claim. Reports are engineering gap assessments, not legal advice.

Can I keep files before a release run exists? Yes. A custody set keeps records, decisions and an audit log in a directory you own, with no scan and no release, and joins a release run later. See Keeping runtime evidence in custody.

Commands used on this page#

Every option of every command is in the CLI reference.

See also#

• Keeping runtime and test evidence with a release — every option, state and refusal, including test reports, laboratory reports and fuzzing campaigns.
• Keeping runtime evidence in custody — custody sets, handover exports and intake manifests.
• Supported inputs — the reader table with every citation.
• Observed vs reviewed — why SBOMFlow observes and people decide.