Creating a ‘Minimum Elements’ SBOM Document in 5 Minutes

The rise in cyberattacks and the critical role that software plays in our lives has brought to light the need for increased transparency and accountability in the software supply chain. Software distributors can achieve this by providing software bills of materials (SBOMs), which provide a comprehensive list of all the components used in a software product, including open source and proprietary code, libraries, and dependencies.

In May 2021, United States Executive Order 14028 on improving the nation’s cybersecurity emphasized the importance of SBOMs in protecting the software supply chain. After comprehensive proof of concepts using the Software Package Data Exchange format (SPDX), the National Telecommunications and Information Administration (NTIA) released the “minimum elements” for an SBOM. The minimum elements require data fields that enable basic use cases:

• Supplier Name
• Component Name
• Version of the Component
• Other Unique Identifiers
• Dependency Relationship
• Author of SBOM Data
• Timestamp

The NTIA recommends that the data contained in these fields should be expressed in predictable implementations and data formats to enable automation support. One of the preferred formats for expressing this data is SPDX. While version 2.3 of the SPDX specification, released in November 2022, was the first version to explicitly describe how to express the NTIA minimum elements in an SPDX document, SPDX has supported these elements since its version 2.0 release in 2015.

The Linux Foundation is the world’s leading home for collaboration on open source software, hardware, standards, and data. Linux Foundation projects are critical to the world’s infrastructure including Linux, Kubernetes, Node.js, ONAP, Hyperledger Foundation, PyTorch, RISC-V, and more.

Learn More

The latest from Linux Foundation Training

SBOMs Using SPDX

SPDX is a standardized format for expressing SBOM data developed transparently over more than 10 years in an open source, multistakeholder community. SPDX is the only recognized international open standard (ISO/IEC 5962:2021) and defines the structure and format of an SPDX document, including the particular fields and data values to enable the interchange of software metadata in a format that is both machine-readable and human-readable.

To help software distributors create an SBOM that complies with NTIA requirements, SPDX contributor Steve Winslow has written a technical HOWTO on how SPDX 2.x supports the NTIA minimum elements for an SBOM. It provides several examples of creating an SPDX SBOM that complies with NTIA requirements using different methods.

An SPDX document can be represented as a single file in different formats, including JSON, YAML, RDF/XML, tag-value, and spreadsheet. The HOWTO focuses on SPDX’s tag-value format, a simple text file format that is both machine-parseable and human-readable. In a tag-value SPDX document, each line of data consists of a tag that defines the data field, a colon separator, and the corresponding data value.

Structure of an SPDX Document

There are three primary elements in an SPDX document: package, file, and snippet. The Package represents a unit of content associated with a software distribution, such as a collection of files, while the file represents a file on disk, and the snippet represents a portion of a file.

Although SPDX allows software to be represented down to the file or snippet level, it is unnecessary to provide those details if your goal is to meet the NTIA minimum elements requirement. As an SPDX document creator, you have the freedom to describe a software distribution to a greater degree of specificity, but NTIA only requires an SBOM to contain information at the “package” component level.

SPDX Identifiers and How They Are Used

Each SPDX element, such as a package, has a unique identifier that serves as its address. The identifier must begin with the prefix SPDXRef- followed by a unique set of letters, numbers, periods (.), and dashes (—). Each SPDX element in a document must have its own unique identifier.

It is important to note that SPDX identifiers differ from SPDX license identifiers, which refer to licenses and exceptions on the SPDX License List.

SPDX Elements are Linked through Relationships

Relationships allow us to express how elements like packages are related. The SPDX specification defines a broad vocabulary of relationship types, but for the purposes of creating an NTIA minimum elements SBOM, only two relationship types are relevant.

The first relationship type is DESCRIBES, which identifies the top-level package the document primarily describes. The second relationship type is CONTAINS, which specifies that one package contains another package as a dependency. The primary package being described in an SPDX document would have a CONTAINS relationship with each dependency package it directly contains. Those dependencies, in turn, would each have a CONTAINS relationship with their sub-dependencies. Relationships are specified using the unique SPDX identifiers assigned to each element.

An example would look like the following:

Sections of an SPDX Document

The Document Creation Information Section

The document creation information section is a required “file header” providing information about the SPDX document itself. It includes details such as the version of the SPDX specification being used, the license applicable to the SPDX document, and a user-defined name for the document. The section also includes other required information, such as a unique uniform resource identifier (URI) for the SPDX document, which may or may not be a URL from which the document can be downloaded; the creator(s) of the document; and the date and time the document was created. These details are important for ensuring that the SPDX document is clear, complete, and can be used to accurately describe the software it is referencing.

For example:

The SPDX Package Information Section

An SPDX package information section contains information about a software package being described in an SPDX document. It includes details like the package name, unique identifier, version, supplier name and download location. If the document contains information about more than one package, then SPDX requires at least one DESCRIBES relationship to the primary package(s).

For a simple NTIA minimum elements SBOM where we won’t be describing every file contained within a package, the SPDX spec also requires a FilesAnalyzed: false statement in the package section.

For example:

After providing the package section for the primary package, an SBOM would also include subsequent package sections for each dependency, with CONTAINS relationships in the form described above.

Part 3 of the HOWTO contains a complete example SBOM and walks through the specific details for each field.

Required Fields

The minimum elements specified by the NTIA each have corresponding SPDX 2.3 fields. Some of the NTIA’s fields appear in the SPDX document creation information section, while the rest are in the package information sections.

A few other mandatory SPDX 2.3 fields are not part of the NTIA minimum elements but are required by the SPDX specification.

How to Create an NTIA Minimum Elements SPDX SBOM

Manually

The best way to become familiar with creating an NTIA minimum Elements SPDX SBOM is by manually creating it as a text file. Part 4.1.1 of the HOWTO provides a template that creators can use as a starting point. The template is a text file that follows a specific format and includes required fields and comments to guide the user. The user can copy the template and fill in the fields with information specific to their software. This method is straightforward but can be time-consuming and prone to human error, and challenging to perform at scale. However, it is an effective way to learn what’s involved in creating an SPDX SBOM that satisfies the NTIA minimum elements.

The NTIA also acknowledges that some creators may not have complete information about their software’s dependencies, so they may include “known unknowns” in their SBOM. In these cases, creators can add a line to the SBOM indicating that there are “known unknowns” and that they have not listed all indirect dependencies in their software.

Using Tooling

Another way to create an NTIA minimum elements SPDX SBOM is through a tool such as SwiftBOM. SwiftBOM was developed by the CERT Coordination Center at Carnegie Mellon University’s Software Engineering Institute, which allows users to fill in fields via a simple form, generating an SPDX SBOM. This method is quicker and less prone to human error than manual creation, but the resulting SBOM may be less readable than one created manually.

Creators can use automated tools to create an NTIA minimum elements SPDX SBOM. The specifics of how to do this will depend on the nature of the software programming ecosystem being used, but in general, the process involves gathering information about the primary software package, its supplier, its version number and its dependencies. This information can then be used to assign SPDX identifiers and output the required fields for the SBOM.

This method is the most efficient but requires more technical knowledge and may not be suitable for all creators. The official SPDX tools for Java, Golang and Python may be helpful to organizations looking to incorporate SBOM automation into their workflows, as well as a variety of other open source and proprietary tools and services in the broader community.

Conclusion

As software continues to play a critical role in our lives, the need for transparency and accountability in software supply chains have become more important than ever. The NTIA SBOM guidelines provide a framework for creating, managing, and sharing SBOMs, which can help organizations manage their software supply chains effectively.

Following these guidelines can provide several benefits, including improved security, better compliance, greater transparency, and reduced legal risk. Organizations that adopt SBOMs can better manage their software supply chains, reduce risks and ensure compliance with regulatory requirements.

Steve Winslow’s HOWTO provides a practical guide to implementing the NTIA SBOM guidelines. Organizations can create, manage and share SBOMs that effectively provide the necessary information to manage their software supply chains. We thank Winslow and the SPDX team for their contribution to the software industry and the transparency and accountability of software supply chains.

Additional Resources

In addition to Winslow’s NTIA SPDX HOWTO, if you are interested in learning more about SPDX, here are some useful resources:

• The SPDX specification: https://spdx.org/specifications
• SPDX tools and utilities: https://github.com/spdx
• SPDX License List: https://spdx.org/licenses
• SPDX community: https://spdx.dev/

In addition, the NTIA has published guidelines and recommendations for creating SBOMs on its website: https://www.ntia.gov/page/software-bill-materials