Sometimes, SBOMs (software bill of materials) can feel more theoretical than tangible. There’s a lot of talk about the potential benefits of using SBOMs, like software supply chain security and regulatory compliance, as well as popular SBOM formats like CycloneDX and SPDX. But some of our customers (especially those early in their SBOM journeys) have mentioned that they’ve faced challenges making decisions in the real-world SBOM context.
With that in mind, I figured it would be helpful to put together a sample application and pair of SBOM examples that describe it. In this blog, you’ll find links to those two samples, along with a description of their sections and data fields.
Please note that in the interest of keeping this blog to a manageable length, I didn’t analyze every data field in our sample SBOMs. Rather, in addition to providing a high-level explanation for each section, I did my best to cover some of the less intuitive and/or potentially confusing fields you might encounter, such as declared vs. concluded licenses in SPDX.
All analysis in this blog will be based on the following two SBOM examples:
Please feel free to reach out to firstname.lastname@example.org if you have any questions about specific data fields in our sample SBOM that I don’t cover in this blog.
SBOM Example 1: SPDX
SPDX (Software Packet Data Exchange) supports the tag/value (which it calls a “simple text-based format”), YAML, JSON, and Excel spreadsheet formats. Our example SPDX SBOM is in JSON.
Valid SPDX SBOMs will always include a section with document creation information. Depending on the composition of the bill of materials, it may also include sections to describe packages, files, snippets, licensing information, relationships, and annotations.
Document Creation Information
Document creation information covers the “who,” “when,” and “how” of an SPDX document.
The document creation information in our sample SPDX SBOM starts in Row 2 and concludes in Row 118. Some of the data fields are:
- Row 2: SPDX ID - This provides a standardized way to refer to the SPDX bill of materials throughout the document.
- Row 3: SPDX Version - This makes clear which version of the SPDX specification the bill of materials uses. Our example uses SPDX 2.3, which is the current version (though the upcoming SPDX v3.0 is under development).
- Row 10: License List Version - The SPDX License List is a collection of commonly used open source licenses, including short-form License Identifiers. The License List is periodically updated (albeit generally with very minor changes), which is why the License List version is part of document creation information.
- Row 119: Data License - An SPDX bill of materials must include the Data License, which essentially communicates that you’re using the SPDX specification under the terms of the Creative Commons CC0 1.0 Universal license.
The package information section of our SBOM example starts on Row 120. Since our application relies on numerous packages, our sample SBOM includes multiple package entries. However, we’ll discuss only one of them here.
Some of the data fields in the package information section are:
- Row 122: SPDX ID - This is the package SPDX identifier field. It’s used to uniquely reference the given package in the SPDX document.
- Row 128: Supplier - This is the “actual distribution source” for a given package. This should be an author (or organization), not a host website. Supplier differs from Originator (Row 127) in that the latter refers to the point of origin, while Supplier refers to the point of distribution.
- Row 131: License Declared - This is the package license as stated by the component author. This differs from the Concluded License (Row 134) in that the Concluded License is stated by the SPDX document creator (often an SBOM tool), which is why these fields sometimes have different values.
- Row 135: Checksums - The intent of the package checksum field is to help SPDX document consumers determine whether any file in the original package has been changed.
- Row 181: External References - This data field is often used to link to security documents, such as VEX (Vulnerability Exploitability eXchange), or package identifiers, like PURL.
This part of our SPDX SBOM is used to describe the nature of relationships between SPDX elements. These elements may be packages, files, and/or snippets, or even the bill of materials itself. (Rows 4633 - 4635 explain that our SPDX SBOM is describing our Recipe Book application.) Relationships are commonly used to describe the nature of dependencies, such as one element depending on another (or containing another). SPDX offers numerous ways to describe relationships, such as “DependsOn,” "DependencyOf,” "Contains," and many more.
As mentioned, SPDX can describe not only packages, but files (and snippets), too. Our example SBOM doesn’t include any snippets, but, starting on row 6661, it describes several files. The data fields in the File Information section are similar to the Package Information section, although there are a handful of differences. (For example, although they’re not included in our sample, the Package Information section has fields that can be used to communicate release date, build date, and valid-until date. And, the File Information section has fields that can be used to communicate file notices and file contributors.)
These aren’t included in our example, but SPDX also supports the following sections:
- Snippet Information: Used to describe part of a file, with data fields including byte and line range.
- Annotation Information: Used to provide additional context and comments related to a part of or the full bill of materials.
- Other Licensing Information Detected: Used to provide additional context about uncommon licenses — those not on the SPDX License List — that may appear in a bill of materials.
SBOM Example 2: CycloneDX
Like SPDX, CycloneDX supports multiple types of file formats. These include JSON, XML, and Protocol Buffers. Our example CycloneDX SBOM is in the JSON format.
A valid CycloneDX bill of materials will always include document creation information (BOM Identity and Metadata sections). Depending on the composition of the bill of materials, it may also describe components, services, dependencies, compositions, vulnerabilities, formulation, annotations, and extensions.
A CycloneDX bill of materials includes several data fields that identify the document version and file format (i.e. the document “Identity”). These include:
- Row 4: Spec Version - Our example uses CycloneDX v1.4. (A new version of the specification, CycloneDX v1.5, was recently released.)
- Row 5: Version - This is the first version of our bill of materials for this application. Each time we make changes to our BOM, we’ll add 1 to that number. The second version would be “2,” the third version “3,” and so on.
- Row 6: Serial Number - Each bill of materials should have a unique serial number.
In CycloneDX, the Metadata section communicates the component (e.g. application, hardware, etc.), supplier, and manufacturer that the bill of materials describes.
- Row 9: Component - CycloneDX is a versatile standard that can be used to describe applications, libraries, hardware, files, and much more. Row 10 (Type) is used to specify which type of component the bill of materials describes. In our sample, this is an application.
- Row 28: Manufacture - This data field communicates the organization that manufactured the component.
- Row 40: Supplier - The supplier is often the same as the manufacturer, but it can sometimes be different, such as in cases where a distributor or repackager is involved. In our sample, the manufacturer and supplier are the same.
This section describes the individual first- and third-party components that make up the application (or hardware, file, etc.) the CycloneDX document describes.
As you might expect, our application relies on many different components; for the purposes of this blog post, we’ll just review one of them, the CodeMirror library.
- Row 55: Type - As was the case in the Metadata section, “Type” is used to describe the nature of the component being analyzed. In our case, this is a library.
- Row 58: BOM-Ref - This is a unique identifier that’s used to identify the component elsewhere in our CycloneDX bill of materials.
- Row 74: PURL - PURL is a helpful way to accurately identify packages, including the ecosystem (package manager) and unique version.
I’d also note that although we don’t have any in our example SBOM, CycloneDX has an External Reference data field that can be used to provide additional information on a Component. CycloneDX supports an extensive list of External References, including multiple security analysis reports, VEX, release notes, and more.
The Dependencies section can be used to depict direct and transitive dependencies. It uses the BOM-Ref element discussed in the previous section to describe the nature of dependency relationships.
For example, in Row 2391, we see that our application depends on multiple packages, including
This section (which starts on Row 2933 in our example) is used to communicate vulnerabilities in components or services. Fields include ID, which is used to uniquely identify the vulnerability (such as a CVE number, like in Row 2936). The “Ratings” section (such as Row 2941) includes metrics like severity, score, and method (i.e. the methodology used to grade severity and score).
These aren’t included in our example, but CycloneDX also supports the following sections
- Services: External APIs your software may call
- Compositions: Communicates the completeness of a component, service, or dependency relationship
- Formulation (new to CycloneDX v1.5): Describes how something was deployed or manufactured
- Annotations (new to CycloneDX 1.5): Allows for comments or explanations that provide additional context on part (or all) of the bill of materials
Additional SBOM Resources
I hope this blog post helped bring to life the data fields and sections you might find in a software bill of materials. For more information about building and managing an effective SBOM program, I’d recommend you consider checking out the following resources:
The Minimum Required Elements of a Software Bill of Materials (Blog): The data fields in an SBOM can vary significantly depending on a number of factors, including your intended use cases. Organizations that sell into the federal government (and, as such, prioritize regulatory compliance) should make sure to generate SBOMs that include these minimum elements.
Generating, Managing, and Importing SBOMs with FOSSA (On-demand webinar): Learn how to automate SBOM document creation — as well as management and import — in this workshop-style on-demand webinar.
How SBOMs Can Strengthen Security (Blog): Security is a well-known SBOM use case. But, dig a little deeper, and you’ll find some potentially surprising ways you can leverage SBOMs (and SBOM tools) to strengthen your security program.