Software supply chain security has become topical in the wake of high profile dependency-based attacks. Producing an SBOM for your software artifacts can help you identify weaknesses and trim down the number of packages you rely on.
A new Docker feature integrates support for SBOM generation into the docker CLI. This lets you produce an SBOM alongside your build, then distribute it to consumers of your image.
The “docker sbom” Command
The new docker sbom command is bundled with Docker Desktop versions 4.7.0 and later. You can add the command to a Docker Engine installation on Linux by installing the docker-sbom plugin from GitHub:
$ curl -sSfL https://raw.githubusercontent.com/docker/sbom-cli-plugin/main/install.sh | sh -s --
Check the installation succeeded by running the command:
$ docker sbom Usage: docker sbom [OPTIONS] COMMAND View the packaged-based Software Bill Of Materials (SBOM) for an image. ...
Now you can generate the SBOM for a Docker image by passing its tag to the command:
$ docker sbom nginx:latest Syft v0.43.0 ✔ Pulled image ✔ Loaded image ✔ Parsed image ✔ Cataloged packages [143 packages] NAME VERSION TYPE adduser 3.118 deb apt 2.2.4 deb base-files 11.1+deb11u3 deb base-passwd 3.5.51 deb bash 5.1-2+b3 deb bsdutils 1:2.36.1-8+deb11u1 deb ...
The CLI will pull the specified image if it doesn’t already exist on your system. The image’s content is then indexed and a package list displayed in your terminal.
Under the hood, Docker uses the popular Syft SBOM generator to scan and index the image. The active Syft version is shown each time you use the command. Its output matches what a standalone Syft installation would produce.
Syft is capable of identifying operating system packages and programming language dependencies. The type of each detected package is displayed in the command’s output, next to its name and precise version. You can use this information to accurately audit your container images and discover software they rely on. When a major vulnerability is reported, you can consult the image’s SBOM to quickly check whether you’re affected.
Customizing Output
Output is displayed as a human-readable table by default. This is ideal for distribution alongside your image or as part of your documentation.
You can strip out the lines containing the Syft version and progress report by adding the --quiet flag. Use --output to write the report into a file, instead of your terminal window. Combining these two options lets you easily save the package list data.
$ docker sbom --output sbom.txt --quiet nginx:latest
Several alternative output formats are available via the --format flag. The text variant is another human-readable option using a row-based layout:
$ docker sbom --format text --quiet nginx:latest [Image] Layer: 0 Digest: sha256:9c1b6dd6c1e6be9fdd2b1987783824670d3b0dd7ae8ad6f57dc3cea5739ac71e Size: 80400891 MediaType: application/vnd.docker.image.rootfs.diff.tar.gzip ... [adduser] Version: 3.118 Type: deb Found by: dpkgdb-cataloger [apt] Version: 2.2.4 Type: deb Found by: dpkgdb-cataloger
The [Image] section enumerates the details of all the layers within the scanned image. The following sections list the detected packages, providing their type and version as nested properties.
Several other formats are supported too, each of which can be activated using the --format flag. These are better choices when you want to consume SBOM data programmatically using third-party tools.
syft-json– Output a report in Syft’s native JSON format.cyclonedx-xml/cyclonedx-json– Produce a CycloneDX standards-compatible report as XML or JSON. This SBOM standard is led by OWASP.github-0-json– A GitHub-compatible report format.spdx-tag-value/spdx-json– Compatible with the SPDX standard for expressing SBOMs, which is defined by the Linux Foundation.
Scans usually look at everything in the image’s filesystem. Sometimes you might want to exclude specific directories to stop some packages showing in the output. Pass a glob expression to the --exclude flag to filter out particular paths. You could use this to only index the packages associated with your application, instead of those belonging to the image’s operating system layer.
$ docker sbom --exclude /var nginx:latest
On occasion you may need to scan an image built for an architecture that differs from your current platform. Use the --platform flag to select a different multi-arch variant, such as linux or arm64:
$ docker sbom --platform arm64 nginx:latest
This lets you index images you’ve built for other platforms without switching between physical hardware devices.
Use Cases
More developers are beginning to recognize the benefits of SBOMs. They highlight excessively long dependency lists, providing pruning opportunities that reduce your threat exposure. For software consumers, SBOMs are an increasingly important tool when gauging the risk presented by a new project. They’re likely to become a required deliverable for software commissioned by major organizations and government agencies.
Once you’ve got an SBOM, the data can be used with automated tools to further pinpoint security issues. As an example, you could pass the output of docker sbom directly into Grype to identify CVEs associated with the packages in your image:
$ docker sbom --format syft-json nginx:latest | grype
SBOM generation has previously relied on adoption of new tools such as Syft. This reduces discoverability and makes the SBOM a bolt-on extra, rather than something intrinsic to your artifacts. By integrating SBOMs into the Docker CLI, more developers will be able to produce reports throughout the software lifecycle.
The current implementation of docker sbom is considered experimental and limited in scope. In the future, SBOM data could be captured as part of the image build process. docker sbom would then surface this information, instead of performing an active on-demand scan.
Integrating SBOMs into docker build would make them a first-class component in the container toolchain, guaranteeing every image is accompanied by an SBOM throughout its life. Storing an image in a registry would include the corresponding SBOM, even if the registry host was air-gapped and unable to perform active scans. This functionality is still some way off though. Today’s version of docker sbom remains a powerful tool that makes container image SBOMs easier to produce.
Summary
The docker sbom command lets you generate the SBOM for a Docker image without installing a standalone tool. The Docker CLI integrates with Syft to provide on-demand scans that produce an index of packages present in the image’s filesystem.
You can start using docker sbom today by updating to Docker Desktop v4.7.0 or installing the SBOM plugin for Docker Engine on Linux. Generating an SBOM each time you build your image will help you identify and address dependency bloat before it becomes a problem. You can often reduce the number of packages in your image by switching to a minimal base image such as alpine and removing unused programming language dependencies.
