SBOM and build records

A bundle includes a lock file and build record. You can also add an SBOM: a software bill of materials that lists the included packages in a format other tools can read.

File	What it tells you
lock.json	Package versions, sources, and the install plan.
evidence.json	Recorded build events.
sbom.cdx.json	A CycloneDX package inventory, added with --sbom.

These files describe the build. To record what happened on a target, save a separate installation report.

Add an SBOM

On the online builder:

debark build --snapshot target.snapshot.tar.zst \
  --out ./bundle --sign operator.key --sbom jq

The resulting bundle/sbom.cdx.json lists package names, versions, and identifiers. You can import it into a tool that accepts CycloneDX, attach it to a change record, or compare it with a previous bundle’s inventory.

Debark writes CycloneDX JSON. It does not write SPDX or run a vulnerability scan. Run your scanner on the connected side if you need that check.

The SBOM covers packages in the bundle, not every application or package already on the target.

Read the build record

evidence.json contains build events and their context, such as the selected backend, package downloads, repository generation, and warnings.

If you have jq installed, this prints the event types:

jq -r '.events[].type' ./bundle/evidence.json

For exact package versions and source information, read lock.json or use:

debark inspect ./bundle --json

Verify a bundle before relying on records received from another machine.

Save events as the command runs

--json-events writes one JSON event per line to a separate file:

debark build --snapshot target.snapshot.tar.zst \
  --out ./bundle --sign operator.key --sbom \
  --json-events build-events.ndjson jq

This stream is useful for progress displays and troubleshooting a failed build. Keep it outside the bundle directory.

The stream and evidence.json use the same event format, but serve different purposes: the stream captures the live invocation; the bundle keeps its own build record. See JSON output for their shapes.

Keep an installation report

On the target, preview first, then save the installation result:

debark install ./bundle --key operator.pub --status
sudo debark install ./bundle --key operator.pub --yes --json > install-report.json

Keep the report with the corresponding bundle identifier or manifest. If you are installing the bundled upgrade set, include --upgrade in both commands.

Share records carefully

Snapshots and reports can contain package inventories, local paths, repository URLs, and labels. Review them before attaching them to a public issue.

Do not edit records inside a signed bundle: changing a covered file causes verification to fail. Make a separate copy for notes or redaction.