Quick Links

An SBOM (Software Bill of Materials) helps you understand your software supply chain by listing the packages and vendors that your code relies upon. SBOMs are rapidly gaining momentum as a way to help improve security in the wake of prominent real-world supply chain attacks.

One major proponent of SBOMs is Microsoft which published its approach to their generation back in October 2021. Earlier this year the company open-sourced its tool for producing SBOMs on Windows, macOS, and Linux.

In this article, you'll learn how to start using the project to index your code's dependencies. It produces SPDX-compatible documents that list the files, packages, and relationships within your project. SPDX (Software Package Data Exchange) is the ISO-accepted standard for SBOMs so you can pass generated reports directly into other ecosystem tools.

Microsoft originally announced the project under the name Salus. It's since retreated from this term because it conflicts with the existing Salus code security project which originated at Coinbase. The SBOM generator is now referred to simply as sbom-tool.

Getting Started

You can download SBOM Tool from Microsoft's GitHub repository. Precompiled binaries are available on the releases page. Select the right download for your system, then make the binary executable and move it to a location in your path.

Here's an example for Linux: 

$ wget https://github.com/microsoft/sbom-tool/releases/download/v<VERSION>/sbom-tool-linux-x64
    
    

            $ chmod +x sbom-tool-linux-x64
    
    

            $ mv sbom-tool-linux-x64 /usr/local/bin/sbom-tool

You should be able to run sbom-tool to display the help information in your terminal window: 

$ sbom-tool
    
    

            No action was specified
    
    

            The Sbom tool generates a SBOM for any build artifact.
    
    

            Usage - Microsoft.Sbom.Tool <action> -options

Generating an SBOM

New SBOMs are created by running the tool's generate sub-command. A few arguments need to be supplied:

  • -b (BuildDropPath) - The folder to save the generated SPDX SBOM manifests to.
  • -bc (BuildComponentPath) - The folder that will be scanned to find the dependencies in your project.
  • -nsb (NamespaceUriBase) - The base path that will be used as the SBOM manifest's namespace. This should be a URL that's owned by your organization, such as https://example.com/sbom.

SBOM Tool also needs to know your project's name and version. It can often infer this from files already in your repository, such as the package.json name and version fields, but you might need to provide the information manually or override the defaults in some cases. Add the pn and pv flags to do this:

  • -pn (PackageName) - The name of your project or package.
  • -pv (PackageVersion) - The project version that you're scanning. This should match the release version that your SBOM accompanies so users can correlate dependency lists with specific builds.

Here's an example of generating an SBOM for the files in your working directory. The SBOM will be placed into the sbom-output subdirectory. This needs to exist before you run the tool. 

$ mkdir sbom-output
    
    

            $ sbom-tool generate -b sbom-output -bc . -pn example -pv 1.0 -nsb https://example.com/sbom

An overview of the scan results will be shown in your terminal: 

[INFO] Enumerated 3728 files and 607 directories in 00:00:00.5938034 
    
    

            [INFO] |Component Detector Id |Detection Time |# Components Found |# Explicitly Referenced | 
    
    

            ...
    
    

            [INFO] |Npm |0.63 seconds |241 |0 | 
    
    

            ...
    
    

            [INFO] |Total |0.64 seconds |241 |0 | 
    
    

            [INFO] Detection time: 0.6374678 seconds.

This project uses npm to manage its dependencies. The tool detected 241 packages inside the working directory's package.json file.

SBOM Tool currently supports 19 different programming languages and package formats. The list includes npm, NuGet, PyPi, Maven, Rust Crates, and Ruby gems, as well as Linux packages present in Docker images. References to remote GitHub repositories are also supported.

SBOM Contents

The generated SBOM will be written to _manifest/spdx_2.2/manifest.spdx.json inside the build output directory that you specified. The SBOM is a fairly verbose JSON file that's intended to be consumed by other software. 

{
    
    

             "files": [],
    
    

             "packages": [
    
    

             {
    
    

             "name": "color-convert",
    
    

             "SPDXID": "SPDXRef-Package-A72B0922E46D9828746F346D7FD11B7F81EDEB15B92BEEDAE087F5F7407FECDC",
    
    

             ...
    
    

             }

There are four main types of information within the report:

  • The files section - This lists all the files containing source code you've written in your project. SBOM Tool will only populate this section when certain project types are scanned, such as C# solutions.
  • The packages section - A complete catalog of all the third-party dependencies present in your project, with references to their source package manager, the version used, and the type of license that applies.
  • The relationships section - This details all the relationships between the components listed in the SBOM. The most common relationship you'll see is DEPENDS_ON, which declares an item in the packages section as one of your project's dependencies. Several other kinds of relationship also exist, such as CREATED_BY, DEPENDENCY_OF, and PATCH_FOR.
  • Report metadata details - Fields such as name, documentNamespace, spdxVersion, and creationInfo identify the SBOM, the tool used to create it, and the SPDX manifest revision that applies.

Now you've got an SBOM you can start using it with other tools to conduct vulnerability scans and manage license compliance. You can consider distributing the SBOM with your software releases so consumers are able to inspect the contents of each new version. SBOMs are best generated as part of your build pipeline so they stay up to date.

Having access to an SBOM is invaluable when major new supply chain problems appear. Organizations using SBOMs were better placed to respond to Log4j, for example. They could inspect their reports to quickly find projects depending on the vulnerable library, instead of auditing package lists by hand.

Scanning Docker Images

SBOM Tool is capable of scanning existing Docker images as part of a report generation. To use this capability, you need to add the -di flag and specify the image tag or digest that you want to scan. The rest of the arguments stay the same. 

$ sbom-tool generate -di ubuntu:latest -b sbom-output -bc . -pn demo -pv 1.0 -nsb https://demo.com/demo

The Docker image will be analyzed to identify the packages it includes. They'll be added to the SBOM report alongside the dependencies found in your source folder. You can scan multiple Docker images in a single operation by separating their tags or digest hashes with commas.

Summary

SBOM Tool is a young open-source SBOM generation utility developed at Microsoft. It supports several leading package formats and produces SPDX-compatible output. This means you can feed generated SBOMs straight into other tools like Grype to automatically find security vulnerabilities and outdated dependencies.

SBOMs are an effective way to increase awareness of software supply chains and uncover lurking issues. Producing and distributing an SBOM helps users understand what's being silently included in their project. SBOM Tool is one way to generate industry-standard reports with a single command, making it easier to offer an SBOM with each of your releases.