A Practical Guide to SPDX

History of SPDX

In February 2010, a Linux Foundation working group (FOSSBazaar) began working on the first version of SPDX, though, at the time, the project was titled “Package Facts.” A few months later, in August 2010, the Linux Foundation announced that SPDX would be one of the pillars of its Open Compliance Program.

The first version of the SPDX specification (SPDX 1.0) was released in August 2011. The subsequent SPDX 1.1 (August 2012) and SPDX 1.2 (October 2013) addressed an issue with the specification’s verification algorithm and added support for additional data fields (such as author credits and project homepage).

Next came SPDX 2.0, which was released in May 2015. This was a significant update to the specification and included support for annotations, package-file relationships, and the ability to handle multiple packages. 

SPDX added significant security utility in 2016 with the release of SPDX 2.1 and support for external references, such as to security advisories and vulnerability feeds. SPDX 2.2 (published in 2020) introduced SPDX Lite (a subset of the specification with mandatory document creation and package information as well as certain other licensing data fields) and added several new supported file formats. The current 2.3 (published in August 2022) added more external reference types (to strengthen the security use case) and improved ease of use by making certain previously mandatory licensing properties optional, among other changes. 

The next version of SPDX will be 3.0. The publication date is still to be determined, but, in May 2023, SPDX announced the Release Candidate for the model. The most impactful innovation in SPDX 3.0 is that it will expand on the concept of “Profiles,” which are, essentially, condensed versions of the format intended for specific use cases. SPDX Lite is an example of an existing profile; SPDX 3.0 will separate licensing and security into separate profiles and introduce additional profiles for AI, data, and software build information.

SPDX Document Structure

SPDX can be used to describe several types of software components: packages, files, and code snippets. The specification includes a wide variety of data fields for each type of component, including name, copyright information, licensing information, and many others. SPDX documents can also be created in a broad range of file formats: .xlsx spreadsheets, YAML, JSON, RDF, XML, and tag:value. (SPDX describes tag:value as a “flat text file,” and it’s a registered MIME type.)

With that said, regulatory compliance is obviously a common SPDX use case, so let's explore the NTIA's SBOM minimum required elements and how those map to SPDX data fields. (Note that the NTIA’s minimum elements are only required for organizations selling into the U.S. federal government and/or going through the FDA premarket review process, but they do tend to be included in most SBOMs.)

NTIA Minimum Required Data Fields and SPDX Mapping

Author of SBOM Data: This maps to SPDX’s “createdBy” data field (in the "Core/CreationInfo” class).

Timestamp: This maps to SPDX’s “created” data field (in the "Core/CreationInfo” class).

Supplier Name: Which person or organization supplied the package to the producer. This should be an individual or entity rather than a host website. “Supplier Name” maps to SPDX’s “suppliedBy” data field (in the Core/Artifact class).

Component Name: This maps to SPDX’s “name” data field (in the Software/Packages class).

Version of the Component: This maps to SPDX’s “packageVersion” data field (in the Software/Packages class).

Other Unique Identifiers: This can potentially map to several SPDX fields, but "packageUrl" (in the Software/Packages class) may be the most applicable/commonly used.

Dependency Relationship: This is used to describe the relationship between different elements, such as one being a dependency of another (or one containing another). This maps to SPDX’s “Relationship” class in the "Core" namepsace.

SPDX Use Cases

Today, SPDX has multiple important use cases, including security, open source license compliance, software transparency and maintainability, and regulatory compliance. As mentioned, when selling into the federal government, software suppliers are required to produce an SBOM in a human- and machine-readable format (like SPDX) to accompany each product. 

Here, we’ll briefly explore two of the most popular SPDX use cases: security and open source license compliance.

Security

SPDX began directly supporting the security use case in 2016 with the release of v2.1. This version of the spec added “External References,” which offer the ability to link to external security information. With the release of v3.0, SPDX supports both embedding security information directly in the SBOM and linking to external references.

Specifically, SPDX 3.0 supports vulnerability data fields like EPSS score, CVSS score, SSVC, VEX status justifications, and more. It also enables you to link to external documents like SWID and CPE (using the "ExternalIdentifiers") field and other references like CWEs, security advisories, vulnerability disclosure reports, and more (using the "External References" field).

Open Source License Compliance

License compliance has been an SPDX use case since the standard was created over a decade ago, and it remains the case today. The specification has several data fields that can be used to communicate licensing information. This includes “copyright text” (to identify the component’s copyright holder and any applicable dates) and “package attribution text” to provide other required acknowledgements. 

There are also “concluded” and “declared” license fields, which differ in the following ways:

Declared license: The license(s) stated by the component author (i.e. file author or package author)

Concluded license: The license as determined by the SPDX document creator (or, in many cases, a scanning tool that document creator uses). The concluded license can differ from the declared license for any number of reasons, including the possibility that the component author mistakenly assigned a permissive license when they should have assigned a copyleft license. If the concluded and declared licenses don’t match, there’s another field (“Comments on license”) where the SBOM creator can add context or an explanation.

Other SPDX Use Cases

SPDX 3.0 introduced the concept of use case-specific profiles. These allow software producers to create SBOMs that are simpler and more tailored for their specific use case(s). As you might expect, security and open source license compliance are two of these profiles. The other three are:

• Build profile: Data fields related to the software build, like build environment and build type
• AI: Data fields related to AI model output, like how much energy the model consumes and how the model is used in software
• Dataset: Data fields related to datasets, like size and availability

Generating SPDX SBOMs

There are multiple ways to generate an SPDX SBOM, but we recommend organizations do so during the build process. Creating your SBOM during the build will generally result in a more accurate component inventory. 

With FOSSA, you can easily generate an SPDX SBOM in the JSON or tag:value file formats. Here’s how:

New FOSSA users

Step 1: Get started by creating a free FOSSA account.

Step 2: Import your project(s) by integrating with a VCS like GitHub or using our CLI 

Generating SPDX SBOMs from the FOSSA App

Step 1: Click on “Projects” in the header menu

Step 2: Select the Project for your SBOM

Step 3: Click on the “Generate a Compliance Report” button in the “Actions” menu 

Step 4: Check the box for your preferred SPDX export format 

Step 5: Decide which elements to include in your report — you can do this by checking (or unchecking) boxes in the “Customize Report Information” and “Edit Dependency Info” menus.

Step 6: Generate your report — either download a copy to distribute yourself, or create a public link for your file

Generating SPDX SBOMs from the FOSSA CLI

To generate an SPDX SBOM from the FOSSA CLI, you’ll need to run an additional report command after analyzing your project. For example:

export FOSSA_API_KEY=XXXXXXXX (needs to be a full API key)

fossa analyze && fossa report attribution --format spdx > file.json

In addition to SPDX, FOSSA supports CycloneDX and several other SBOM formats. For more information (or to access our full suite of SBOM features with a paid account), please reach out to our team.