SBOM — software bill of materials for images · Docker & Containers

An SBOM is a structured list of every component in a piece of software. For an image that means every package, library and — where the format is present — every binary the cataloguer could identify.

The promise is that “what versions of openssl are running in production?” becomes a query rather than an archaeology project. The promise is real. It is also conditional on something almost nobody does at the same time as turning the flag on.

We generate SBOMs. We still spent three days answering the question.

A serious vulnerability in a widely used library is disclosed on a Friday afternoon. Leadership asks the only question that matters: are we affected, and where?

The team has been generating SBOMs for eighteen months. Every build produces one. Every one is uploaded as a CI artefact.

And the answer still takes three days, because:

The artefacts are keyed by pipeline run, not by image digest, so matching an SBOM to a running container means correlating build numbers with deploy records.
The retention policy on the artefact store is 90 days, and several production services have not been rebuilt in six months.
Nothing indexes them. Answering the question means downloading a few thousand JSON files and grepping them.
Nobody has ever run that query, so the first day is spent discovering that a third of the SBOMs are empty because a base-image change broke the cataloguer and no check ever looked.

Generating an SBOM and acting on an SBOM are different projects. The first is a build flag. The second is storage keyed by digest, an index, a scheduled re-scan and somebody who has run the query before the day they need it.

The tell that you are in this state: nobody can answer “which running images contain package X” in under five minutes, on a normal Tuesday, without touching production.

Generating

BuildKit, at build time

Configuration changebuild with an SBOM attestation— --sbom=true is shorthand for --attest type=sbom. The result is attached to the image, not written to a file.

docker buildx build \
--sbom=true \
--provenance=mode=max \
--tag registry.example.com/myorg/myapp:1.0.0 \
--push .

BuildKit’s SBOM is generated from what the builder observed while building, and is attached “to the final image as a JSON-encoded SPDX document, using the format defined by the in-toto SPDX predicate”.

--load into a classic image store silently drops the attestation

Attestations attach to an image as an extra manifest in the image index. A classic Docker image store has no representation for that, so the attestation has nowhere to go.

The documentation is explicit: “To build attestations with the docker driver, turn on the containerd image store.” And on export: “Pushing the result to a registry with --push keeps the attestations. If you load the result into the daemon with --load instead, the same image store requirement applies.”

So a local --load build on a daemon using the classic store produces an image with no SBOM and no error. The build says it succeeded. The attestation is gone.

This is one of the behaviours that changed with Engine 29, where the containerd image store became the default. On 28.x it is opt-in, and on any 28.x host that has not opted in, --load builds lose attestations. Check before you rely on it:

docker info --format '{{.DriverStatus}}'

The reliable path on any version is to push to a registry, and to verify the attestation is there afterwards rather than assuming.

Syft, for images you did not build

Read-only / Safegenerate SBOMs in both formats— Syft can emit several formats in one pass. Scan by digest so the SBOM names a specific artefact.

IMG=registry.example.com/myorg/myapp@sha256:REPLACE_ME

syft "$IMG" \
-o spdx-json=./sbom.spdx.json \
-o cyclonedx-json=./sbom.cdx.json

Syft catalogues a filesystem after the fact. That is the right tool for a third-party image, a base image you are evaluating, or an artefact whose build you do not control.

The formats

Format	Steward	Heritage	Where it fits
SPDX	Linux Foundation	License and compliance	Regulatory reporting, licence obligations, the format BuildKit emits
CycloneDX	OWASP	Security	Vulnerability management, and it carries VEX natively

Those are the two SBOM formats. Both express the same core idea — components, versions, identifiers, relationships — and good tooling converts between them with acceptable fidelity.

Choose SPDX when licence and compliance reporting is the driver, or when you want the format BuildKit produces natively. Choose CycloneDX when vulnerability management is the driver and you want VEX statements in the same document. If you have no strong reason, produce both — the marginal cost is one extra output flag.

Verifying an image actually has one

This is the check that would have caught the “a third of our SBOMs are empty” problem in the story above, and it takes one command.

Read-only / Safedoes this image carry an SBOM?— Reads the SBOM attestation from the registry. An error here means the attestation is absent, whatever the build log said.

IMG=registry.example.com/myorg/myapp:1.0.0

docker buildx imagetools inspect "$IMG" \
--format '{{ json .SBOM.SPDX }}' > /dev/null \
&& echo 'OK: SBOM attestation present' \
|| echo 'FAIL: no SBOM attestation on this image' >&2

OK: SBOM attestation present

Illustrative output

Presence is not enough. An SBOM listing four packages for a Debian-based image is a cataloguer failure, not a minimal image, and it will pass every “does an SBOM exist” check ever written.

Read-only / Safeis the SBOM plausible?— Lists every package with its version, then counts them. Compare the count against what you expect for this base image.

IMG=registry.example.com/myorg/myapp:1.0.0

docker buildx imagetools inspect "$IMG" \
--format '{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}' \
| tee /tmp/sbom-packages.txt \
| wc -l

Illustrative output

Assert a floor in CI. A debian:bookworm-slim base yields a few hundred packages; if the count drops to single digits between one build and the next, something in the build changed in a way nobody intended. That assertion is cheap and it is the difference between an SBOM programme that works and one that is discovered to be hollow during an incident.

Where the SBOM physically lives

An SBOM attestation is not a file next to the image and not a field inside the image config. It is another manifest.

An image index lists manifests. Normally each entry is a platform variant — linux/amd64, linux/arm64. When you build with attestations, BuildKit adds further entries whose content is the attestation blobs, associated with the platform manifest they describe. As the documentation puts it: “Attestations attach to images as a manifest in the image index. The data records of the attestations are stored as JSON blobs.”

Three consequences follow, and each explains a common confusion:

An SBOM is content-addressed and immutable, like everything else in a registry. It describes the image digest it is attached to. It cannot drift from the image, because changing either changes a digest.

Copying an image without copying the index loses it. A docker pull followed by docker tag and docker push transfers the platform manifest the local daemon selected — not the index, and not the attestation manifests. docker buildx imagetools create copies the whole index and keeps them. This is the same mechanism that drops non-native platforms during a naive mirror, and it bites for the same reason.

Registry retention affects attestations. They are manifests, so they are subject to retention rules and garbage collection. A rule that keeps the ten most recent artefacts per repository may or may not count attestation manifests as artefacts, and a --delete-untagged collection can remove an attestation whose image is still deployed. Check what your registry does before you find out.

Acting on it

The workflow that turns SBOMs from paperwork into an answer:

Generate at build time, attached to the image, so the SBOM and the artefact cannot become separated.
Store keyed by image digest. Not by build number, not by tag. The digest is the only identifier that is stable and that a running container can be resolved to.
Index the component list into something queryable. A database table of (image digest, package name, version) is enough; this does not need a product.
Re-scan on a schedule against a current vulnerability database — the SBOM is fixed, the database is not, and the whole value is in re-matching an unchanged component list against new knowledge.
Join against what is deployed. An SBOM index that cannot be joined to running containers by digest tells you what you have built, not what you are running.
Rehearse the query on a normal day, so the first time you run it is not during an incident.

Step four is the one that makes the whole thing worthwhile and the one people skip. The vulnerability that matters is almost never known when the image is built — it is disclosed months later, against a component list that has not changed. Scanning at build time catches what was known then; re-scanning the stored SBOM catches what is known now, without pulling or rebuilding anything.

Read-only / Safere-scan a stored SBOM against today's database— No image pull, no registry round trip for layers. This is what makes fleet-wide daily re-scanning practical.

trivy sbom ./sbom.spdx.json --severity HIGH,CRITICAL --ignore-unfixed

sbom.spdx.json (debian 12.5)
Total: 2 (HIGH: 2, CRITICAL: 0)

Illustrative output

Read-only / Safethe query the whole programme exists for— Which deployed images contain a given package. Against a flat directory of digest-named SBOMs; a real index makes this a SQL query.

PKG=libssl3
SBOM_DIR=/srv/sbom-index

grep -l "\"name\": \"${PKG}\"" "$SBOM_DIR"/*.spdx.json \
| while IFS= read -r f; do
    basename "$f" .spdx.json
  done

sha256:4f2ac19d00000000000000000000000000000000000000000000000000000000
sha256:81e077b300000000000000000000000000000000000000000000000000000000

Illustrative output

Those digests join directly to docker inspect --format '{{.Image}}' across the fleet, which is the entire chain from “a CVE was announced” to “these seventeen containers on these five hosts”. If that chain has a broken link anywhere, the SBOM programme is not finished.

What if the SBOM is incomplete?

It will be. The honest position is that an SBOM is a catalogue of what the cataloguer could identify, and it inherits exactly the blind spots described in the CVE scanning lesson — because it is generated by the same class of tool, often the same library.

Specifically, an SBOM will typically not list:

A C library statically linked into a compiled binary.
A dependency vendored into a source tree and compiled during the build, with no manifest file surviving into the image.
A binary downloaded with curl in a RUN step and dropped into /usr/local/bin.
Anything installed by a package manager the cataloguer does not support.

None of these appear as “unknown component”. They are absent, and absence is indistinguishable from “not present”.

What to do about it, in order of practicality:

Prefer package-manager installs over ad-hoc downloads in your Dockerfiles. This is a build-hygiene change that directly improves SBOM coverage, and it is the highest-leverage item here.
Keep the language-level lock files in the image or attach them alongside, so vendored dependencies remain enumerable.
Record what you know the tooling misses. A short written list of “components in this image that our SBOM does not cover” is worth more than the pretence of completeness, and it is the thing an auditor should actually ask for.
Diff SBOMs between releases. A component that appears or disappears without a corresponding change in your dependency files is a signal worth chasing.

An incomplete SBOM is still far better than no SBOM. It stops being better the moment somebody treats it as exhaustive.

Why this matters

The case for SBOMs is usually made as compliance, and that undersells it. The real case is time: when a component you depend on is compromised or disclosed, the difference between an organisation that answers “where are we affected” in ten minutes and one that answers in three days is entirely a question of whether the component lists were indexed before the day they were needed.

The build flag is trivial and it is where most SBOM programmes stop. Storage keyed by digest, an index, a scheduled re-scan against a current database, and a query somebody has actually run — that is the part that turns a JSON file into an answer.

And when you build it, verify the SBOMs are not empty. The failure mode that costs the most is not a missing SBOM; it is a present one that nobody checked and that lists four packages for a full Debian userland.

Generating

BuildKit, at build time

Syft, for images you did not build

The formats

Verifying an image actually has one

Acting on it

Knowledge check