Image analysis uses image SBOMs to understand what packages and versions an image contains. Docker Scout uses SBOM attestations if available on the image (recommended). If no SBOM attestation is available, Docker Scout creates one by indexing the image contents.
View from CLI#
To view the contents of the SBOM that Docker Scout generates, you can use the
docker scout sbom
command.
$ docker scout sbom [IMAGE]
By default, this prints the SBOM in a JSON format to stdout.
The default JSON format produced by docker scout sbom
isn't SPDX-JSON.
To output SPDX, use the --format spdx
flag:
$ docker scout sbom --format spdx [IMAGE]
To generate a human-readable list, use the --format list
flag:
$ docker scout sbom --format list alpine
Name Version Type
───────────────────────────────────────────────
alpine-baselayout 3.4.3-r1 apk
alpine-baselayout-data 3.4.3-r1 apk
alpine-keys 2.4-r1 apk
apk-tools 2.14.0-r2 apk
busybox 1.36.1-r2 apk
busybox-binsh 1.36.1-r2 apk
ca-certificates 20230506-r0 apk
ca-certificates-bundle 20230506-r0 apk
libc-dev 0.7.2-r5 apk
libc-utils 0.7.2-r5 apk
libcrypto3 3.1.2-r0 apk
libssl3 3.1.2-r0 apk
musl 1.2.4-r1 apk
musl-utils 1.2.4-r1 apk
openssl 3.1.2-r0 apk
pax-utils 1.3.7-r1 apk
scanelf 1.3.7-r1 apk
ssl_client 1.36.1-r2 apk
zlib 1.2.13-r1 apk
For more information about the docker scout sbom
command, refer to the CLI
reference.
Attach as build attestation#
You can generate the SBOM and attach it to the image at build-time as an
attestation. BuildKit provides a default
SBOM generator which is different from what Docker Scout uses.
You can configure BuildKit to use the Docker Scout SBOM generator
using the --attest
flag for the docker build
command.
The Docker Scout SBOM indexer provides richer results
and ensures better compatibility with the Docker Scout image analysis.
$ docker build --tag <org>/<image> \
--attest type=sbom,generator=docker/scout-sbom-indexer:latest \
--push .
To build images with SBOM attestations, you must use either the containerd
image store feature, or use a docker-container
builder together with the --push
flag to push the image (with attestations)
directly to a registry. The classic image store doesn't support manifest lists
or image indices, which is required for adding attestations to an image.
Extract to file#
The command for extracting the SBOM of an image to an SPDX JSON file is different depending on whether the image has been pushed to a registry or if it's a local image.
Remote image#
To extract the SBOM of an image and save it to a file, you can use the docker
buildx imagetools inspect
command. This command only works for images in a
registry.
$ docker buildx imagetools inspect <image> --format "\{\{ json .SBOM }}" > sbom.spdx.json
Local image#
To extract the SPDX file for a local image, build the image with the local
exporter and use the scout-sbom-indexer
SBOM generator plugin.
The following command saves the SBOM to a file at build/sbom.spdx.json
.
$ docker build --attest type=sbom,generator=docker/scout-sbom-indexer:latest \
--output build .