# SBOM and build records

Export a package inventory and keep records of what was built and installed.

Source: https://debark.dev/docs/trust/sbom-and-evidence

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

```bash
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:

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

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

```bash
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:

```bash
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](/docs/reference/json-output) for their shapes.

## Keep an installation report

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

```bash
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.

<NextSteps
  items={[
    {
      title: 'JSON output',
      href: '/docs/reference/json-output',
      description: 'Read command reports and event streams.',
    },
    {
      title: 'Bundle format',
      href: '/docs/reference/bundle-format',
      description: 'Find the files inside a bundle.',
    },
  ]}
/>