How to generate an SBOM with Microsoft’s open source tool

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

One of the main proponents of SBOMs is Microsoft, which published its approach to its generation in October 2021. Earlier this year, the company opened up its tool to produce SBOMs on Windows, macOS, and Linux.

In this article, you’ll learn how to get started with the project to index your code’s dependencies. Produces SPDX-compliant documents that list the files, packages, and relationships within your project. SPDX (Software Package Data Exchange) is the ISO-accepted standard for SBOM, so you can pass generated reports directly to other tools in the ecosystem.

Microsoft originally announced the project under the name Salus. This term has since been dropped because it conflicts with the existing Salus code security project that originated from Coinbase. The SBOM generator is now known simply as sbom-tool.

Starting

You can download the SBOM tool from Microsoft’s GitHub repository. Precompiled binaries are available on the release page. Select the correct download for your system, then make the binary executable and move it to a location on your path.

Here is 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 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

Generation of an SBOM

New SBOMs are created by running the tool generate subcommand. You need to provide some arguments:

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

SBOM Tool also needs to know the name and version of your project. You can often infer this from files that are already in your repository, like the package.json name Y version fields, but you may need to provide the information manually or override the default values ​​in some cases. Add the pn Y pv flags to do this:

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

Here is an example of how to generate an SBOM for files in your working directory. The SBOM will be placed in the sbom-output subdirectory. This must exist before running 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 displayed on 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 package.json proceedings.

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 you specified. The SBOM is a fairly verbose JSON file that is meant 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 that contain the source code that you have written in your project. SBOM Tool will only complete this section when scanning certain types of projects, 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 – Here all the relationships between the components listed in the SBOM are detailed. The most common relationship you will see is DEPENDS_ONwhich declares an item in the packages section as one of your project’s dependencies. There are also other types of relationships, such as CREATED_BY, DEPENDENCY_OFY PATCH_FOR.
• Report metadata details – fields like name, documentNamespace, spdxVersionY creationInfo identify the SBOM, the tool used to create it, and the revision of the SPDX manifest that is applied.

Now that you have an SBOM, you can start using it with other tools to perform vulnerability scans and manage license compliance. You might consider distributing the SBOM with your software versions so that consumers can inspect the content of each new version. SBOMs are best generated as part of your build process so they are kept up to date.

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

Docker Image Scan

The SBOM tool is capable of scanning existing Docker images as part of generating a report. To use this capability, you must add the -di check and specify the image tag or abstract you want to scan. The rest of the arguments remain 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 parsed to identify the packages it includes. They will be added to the SBOM report along with any dependencies found in your source folder. You can scan multiple Docker images in a single operation by separating their digest tags or hashes with commas.

Summary

SBOM Tool is a young open source SBOM generation utility developed at Microsoft. It supports several leading packet formats and produces SPDX-compliant output. This means you can feed generated SBOMs directly 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 hidden problems. Producing and distributing an SBOM helps users understand what is quietly included in their project. SBOM Tool is a way to generate industry standard reports with a single command, making it easy to deliver an SBOM with each of your releases.