SBOMs for container images
An image contains your application plus a base image of OS packages and runtimes. Generate the application SBOM from source and the image SBOM from the built image with sbombox generate --image, then upload both to the same project.
At a glance
| SBOM | Generate with | What it covers |
|---|---|---|
| Application | sbombox generate in the source tree | Your dependencies, from the lockfile, with dev dependencies left out |
| Image | sbombox generate --image <ref> | OS packages, language runtimes and anything copied into the image |
The source SBOM is the more accurate record of your dependencies: it reads the lockfile and the package manager's own resolution. The image SBOM finds what the source cannot see, such as base image packages.
Generate the image SBOM
curl -fsSL https://sbombox.com/install.sh | sh
sbombox generate --image registry.example.com/acme/api:1.4.0 -o image-sbom.json
sbombox score image-sbom.json
sbombox push image-sbom.json --version v1.4.0SBOMBox picks the source for you:
- The image's own SBOM first. If the image was built with
docker buildx build --sbom=true, BuildKit attached an SPDX SBOM to it. SBOMBox reads it withdocker buildx imagetools inspect. It describes exactly what the build put in the image. This needs Docker with buildx on the machine. - Otherwise, syft. syft (added by the installer) pulls the image from its registry, or reads it from the local Docker daemon, and lists the OS and language packages in its layers. Docker is not required.
Either way, the SBOM's root component is marked as a container, named after the image and versioned by its tag. When the digest is known (from an @sha256: reference, or from the registry when Docker is available) it is recorded as the root component's hash and in the sbombox:image:digest property, with sbombox:image:ref and sbombox:image:source.
| Option | Effect |
|---|---|
--image REF | Scan this image instead of a directory. Cannot be combined with --dir. |
--platform OS/ARCH | For a multi-platform image, e.g. linux/arm64. Default linux/amd64. If the image's BuildKit SBOM has no entry for that platform, syft scans the platform you asked for; SBOMBox never substitutes another platform's SBOM. |
--format spdx | SPDX 2.3 instead of CycloneDX 1.6, as for source scans. |
SBOMBOX_GENERATOR=syft | Skip the BuildKit SBOM and always scan. buildx-attestation uses only the attached SBOM. Names that cannot read images are ignored for image scans. |
Private registries. Sign in the usual way (docker login registry.example.com); SBOMBox and syft use Docker's stored credentials, or the config in DOCKER_CONFIG. In GitHub Actions, run docker/login-action before the SBOMBox Action and set its image input; see the GitHub Action.
Measured on 16 November 2026 with syft 1.57.1: alpine:3.20 gave 15 components and scored 6.5/10, python:3.12-slim gave 96 components and scored 6.6/10. Licenses and package URLs were present for almost every package; hashes and suppliers were not, because OS package databases do not record them.
Do it by hand
The same results without the --image option, for pipelines that already run these tools:
# syft: leave out per-file entries, which have no version or purl
SYFT_FILE_METADATA_SELECTION=none syft registry.example.com/acme/api:1.4.0 \
-o cyclonedx-json=image-sbom.json
# BuildKit: attach an SBOM at build time, then read it back
docker buildx build --sbom=true -t registry.example.com/acme/api:1.4.0 --push .
docker buildx imagetools inspect registry.example.com/acme/api:1.4.0 \
--format '{{ json .SBOM.SPDX }}' > image-sbom.spdx.jsonFor a multi-platform image, select one platform: --format '{{ json (index .SBOM "linux/amd64").SPDX }}'. To include the build context in the BuildKit scan, declare ARG BUILDKIT_SBOM_SCAN_CONTEXT=true after the syntax line in the Dockerfile. Upload either file with sbombox push.
Combine the application and image SBOMs
Upload both to the same SBOMBox project, with the same release label, so the release has a complete record:
# From the source tree
sbombox generate -o app-sbom.json
sbombox push app-sbom.json --version v1.4.0
# From the built image
sbombox generate --image registry.example.com/acme/api:1.4.0 -o image-sbom.json
sbombox push image-sbom.json --version v1.4.0SBOMBox has no merge command. If a customer needs a single file, merge with the CycloneDX CLI, then upload the result:
cyclonedx merge --input-files app-sbom.json image-sbom.json --output-file release-sbom.json
sbombox push release-sbom.json --version v1.4.0A hierarchical merge (--hierarchical --name api --version 1.4.0) keeps each input as a nested component. See Unify SBOMs for when to merge and when to keep SBOMs separate.
Known gaps
- Image scanners find language packages from installed metadata, not lockfiles. Dev dependencies installed in the image show up as shipped.
- Multi-stage builds discard build-stage packages, so an image SBOM does not show what was used to build the binary. Keep the source SBOM.
- OS packages carry no hashes or supplier names in their package databases, so image SBOMs score lower on integrity and provenance than source SBOMs.
- BuildKit SBOMs are SPDX. SBOMBox converts them when you ask for CycloneDX, and
sbombox pushaccepts either.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
the registry refused access. Run docker login <registry> | The image is private and this machine is not signed in to the registry | docker login <registry>, or in CI run docker/login-action first |
| the image was not found locally or in its registry | Wrong name or tag, or the image was not pushed (or pulled, for a local image) | Check the reference; docker pull it to confirm |
| the registry could not be reached | Typo in the registry host, or no network access to it | Check the host part of the reference and the network |
| syft is not installed | Generators were skipped at install time | curl -fsSL https://sbombox.com/install.sh | sh |
| The image has no SBOM attestation for linux/arm64 | The BuildKit SBOM covers other platforms only | Nothing to do: syft scans the platform you asked for |
Could not detect project ecosystem in <dir>: no supported manifest or lockfile. | sbombox generate was pointed at a directory with no manifest, such as a Dockerfile only | Add --image <ref> to scan the built image; run sbombox generate in the source tree for the application |
| Two SBOMs disagree on a version | The image was built from a different commit, or the base image changed | Build the image and the source SBOM from the same commit in one pipeline |
For a full pipeline, see the end-to-end guide.
In CI, run the same commands. See GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, Bitbucket Pipelines or CircleCI, or use the GitHub Action.