Docker’s built-in image indexing feature is great for quickly finding and listing all the images in a Docker container. However, if you want to index your entire docker image, you’ll need to use docker sbom. docker sbom is a tool that allows you to index your docker images using a set of rules. You can create a file called “index.yaml” in your root directory and add the following contents:

  • name: “my_image” version: “1” ports: - “80” - “443” volumes: - “/var/run/docker.sock:/var/run/docker.sock:/usr/local/bin:/usr/local/sbin:/usr/local/bin:/opt/docker/” The first line sets up the environment variables for docker sbom and sets up the path to our my_image image. The second line defines our index rules. The third line defines our container’s port and volume assignments. Finally, the fourth line tells docker to start our container with the given arguments (in this case, “-v /var/run/.dockerrc:/etc/.dockerrc”:)

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:

Check the installation succeeded by running the command:

Now you can generate the SBOM for a Docker image by passing its tag to the command:

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.

Several alternative output formats are available via the –format flag. The text variant is another human-readable option using a row-based layout:

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.

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:

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:

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.