How to use “docker sbom” to index your Docker image packages

0
16


Software supply chain security has become a hot topic in the wake of high-profile dependency-based attacks. Producing an SBOM for your software artifacts can help you identify weaknesses and reduce the number of packages you rely on.

A new Docker feature integrates support for SBOM generation in the docker CLI. This allows you to produce an SBOM along with your build and then distribute it to consumers of your image.

The “docker sbom” command

The new docker sbom The command is included with versions 4.7.0 and later of Docker Desktop. You can add the command to a Docker Engine installation on Linux by installing the docker-sbom GitHub plugin:

$ curl -sSfL https://raw.githubusercontent.com/docker/sbom-cli-plugin/main/install.sh | sh -s --

Verify that the installation was successful by running the command:

$ docker sbom

Usage:  docker sbom [OPTIONS] COMMAND

View the packaged-based Software Bill Of Materials (SBOM) for an image.
...

You can now 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 does not already exist on your system. Then the content of the image is indexed and a list of packages is displayed in your terminal.

Under the hood, Docker uses the popular Syft SBOM generator to scan and index the image. The active version of Syft is displayed 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 output, along with its name and precise version. You can use this information to accurately audit your container images and discover the software they trust. When a major vulnerability is reported, you can check the SBOM of the image to quickly verify if you are affected.

Output customization

The output is displayed as a human-readable table by default. This is ideal for distributing alongside your image or as part of your documentation.

You can remove the lines containing the Syft version and progress report by adding the --quiet flag. Use --output to write the report to a file, instead of your terminal window. Combining these two options allows you to easily save package list data.

$ docker sbom --output sbom.txt --quiet nginx:latest

Several alternative output formats are available through the --format flag. the text variant is another human-readable option that uses 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] The section lists 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 also supported, each of which can be activated using the --format flag. These are better options when you want to programmatically consume SBOM data with third-party tools.

  • syft-json – Output to report in Syft’s native JSON format.
  • cyclonedx-xml/cyclonedx-json – Produce a report that is compliant with CycloneDX standards such 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 SBOM, defined by the Linux Foundation.

Scans generally look at everything on the image’s file system. Sometimes you may want to exclude specific directories to prevent some packages from showing up in the output. Pass a global expression to the --exclude check to filter particular routes. You can use this to index only the packages associated with your application, rather than those that belong to the OS layer of the image.

$ docker sbom --exclude /var nginx:latest

Sometimes you may need to scan an image created for an architecture that differs from your current platform. Use the --platform flag to select a different multi-arcade variant, such as linux either arm64:

$ docker sbom --platform arm64 nginx:latest

This allows you to index images that you have created 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 exposure to threats. For software consumers, SBOMs are an increasingly important tool in measuring the risk presented by a new project. They are likely to become a necessary product for software commissioned by major organizations and government agencies.

Once you have an SBOM, the data can be used with automated tools to identify further security issues. As an example, you could pass the output of docker sbom directly in Grype to identify CVEs associated with packages in your image:

$ docker sbom --format syft-json nginx:latest | grype

The SBOM generation has previously relied on the adoption of new tools like Syft. This reduces discoverability and makes SBOM an additional plugin, rather than something intrinsic to your artifacts. By integrating SBOMs into the Docker CLI, more developers will be able to generate reports throughout the software lifecycle.

The current implementation of docker sbom it is considered experimental and limited in scope. In the future, SBOM data could be captured as part of the imaging process. docker sbom it would then display this information, rather than perform an active on-demand scan.

Integration of SBOM in docker build would make them a first-class component in the container toolchain, ensuring that every image is accompanied by an SBOM for its entire lifetime. Storing an image in a registry would include the corresponding SBOM, even if the registry host had an air gap and could not perform active scans. However, this functionality is still a long way off. Today’s version of docker sbom it’s still a powerful tool that makes it easy to produce SBOM of container images.

Summary

the docker sbom The command allows you to build the SBOM for a Docker image without installing a separate tool. The Docker CLI integrates with Syft to provide on-demand scans that produce an index of packages present in the image file system.

you can start using docker sbom today by upgrading to Docker Desktop v4.7.0 or installing the SBOM plugin for Docker Engine on Linux. Generating an SBOM every time you build your image will help you identify and address dependency overload before it becomes a problem. You can often reduce the number of packages in your image by switching to a minimal base image like alpine and removing unused programming language dependencies.