A software bill of materials (SBOM) outlines all components, libraries, and dependencies that comprise a software project.
Various SBOM formats standardize this document. Two emerged as popular options in the wake of the White House's cybersecurity Executive Order in 2021 and updated National Cybersecurity Strategy.
This blog post delves into these formats, emphasizing the need for a standardized structure to facilitate SBOM generation and interoperability across various tools, despite lacking a federally recommended SBOM format. We'll guide you through understanding these formats and the tools available for efficient conversion between them.
Understanding SBOM standards
CycloneDX format
CycloneDX is a full-stack bill of materials (BOM) standard for software supply chains. SBOM support is just one of the capabilities of the CycloneDX project, which also contains a sizable library of official and community-supported tools.
As a comprehensive SBOM standard, CycloneDX contains the following features:
- Design that emphasizes precise component identification
- Lightweight protocol facilitates easy construction, maintenance, and management
- Support for multiple formats (JSON, XML), enhancing integration with development tools
- Open source, with an Apache 2.0 license, encouraging wide adoption and contribution
- Prioritization of security, offering digital signatures for enhanced integrity
SPDX format
SPDX (Software Package Data Exchange) is an open standard for exchanging software package metadata. GitHub even contains an Export SBOM function that generates an SPDX SBOM from your repository's dependency graph.
Key attributes of the SPDX SBOM format include the following:
- Focus on compliance and intellectual property management
- Comprehensive analysis for in-depth license information and software package analysis
- Open source and maintained under a Creative Commons Public License, encouraging broad participation
- Enhanced documentation with detailed annotations, including comments and code snippets, facilitating transparent decision-making processes
Additional formats
Although CycloneDX and SPDX stand out as leading SBOM formats, two other standards warrant consideration:
- Software identification (SWID) tagging offers a structured metadata approach that details a piece of software, encapsulating details like product version and involved organizations, which aids in software management and compliance.
- Package URL (purl) standardizes the identification and location of software packages across diverse environments, promoting uniformity and reliability.
Both SWID and purl complement the broader SBOM ecosystem, supporting the integration and management of software components.
Choosing the right SBOM format
Deciding on the right SBOM format involves weighing the complexity and specific needs of your industry.
Engaging with industry partners to understand their preferences can offer valuable insights. Organizations frequently align their choice of SBOM standard with their operational ecosystem and key partnerships.
For instance, collaborations with tech giants like Microsoft might lean towards SPDX due to its comprehensive nature and widespread recognition. Conversely, entities favoring agility and simplicity, and those engaged with open-source communities or companies like IBM, might find CycloneDX's lightweight approach more fitting.
Ultimately, the decision hinges on the balance between detailed compliance requirements and the desire for streamlined, flexible SBOM management.
Tooling for converting SBOM formats
Converting between SPDX and CycloneDX can be useful when collaborating with people who use different formats or when switching between tools that support or leverage different formats.
Our instructions presuppose that you already possess an SBOM. If you do not, we've previously written about how to create them and how to use them.
Please note that converting between SPDX and CycloneDX formats might result in the loss of some data. For a general idea of what information might be lost from conversion, check out this repository for CycloneDX .NET libraries.
SPDX tooling
SPDX provides a prototype utility in GitHub specifically designed to convert from CycloneDX to SPDX. Generally, CycloneDX components map to SPDX packages. Read the design and implementation notes in the repository for more information on mapping.
This utility uses the SPDX v2.3 annotations to track the conversion differences between CycloneDX and SPDX SBOMs, as shown here:
Converting your SBOM
The utility is able to convert a CycloneDX SBOM into SPDX format. You’ll be good to jump right in so long as you have Docker Desktop or an environment set up to use Java 11+ with Maven.
Simply follow the usage instructions in the README. The tool can be installed in your local Java development environment or run in the provided Docker container.
Option 1: JAR
The utility itself is a standalone executable Java archive (JAR) file that can be downloaded from the releases section of the GitHub repository.
Download the JAR file and run it using the appropriate command in your terminal or command prompt with your desired input and output files. In this example, cyclonedx.json is the input file and spdx.json is the output.
java -jar cdx2spdx-[version]-jar-with-dependencies.jar cyclonedx.json spdx.json
Option 2: Dockerfile
Run this utility with its accompanying Dockerfile via the following build commands after you change the input file (cyclonedx.json or spdx.json) according to your specific use case:
docker build -t cdx2spdx .
docker run -v <directory where cyclonedx.json is located>:/cdx2spdx/sboms -it --rm cdx2spdx
Shout out to Sonatype’s Developer Advocates Theresa Mammarella and Eddie Knight for working to contribute the Docker Container to the SPDX repository using the lessons we learned during the creation of this article.
CycloneDX tooling
The CycloneDX project provides a command line interface (CLI) tool and a web tool that assist a variety of CycloneDX use cases, including SBOM conversion to and from CycloneDX.
After installation, this tool provides a wide array of features… but we’ll just be using the "convert" functionality.
Installation
Step 1
Download the latest version of the CycloneDX CLI tool from its GitHub repository's releases page.
If you need more information to decide which binary to download, run the appropriate command below to learn more about your operating system.
On a Windows machine:
systeminfo | findstr /C:"System Type"
On a Mac or Linux machine:
arch
For example, on Windows if you receive a response "x64-based PC," you have a 64-bit processor. If it reads “ARM-based PC” then you have an ARM64-based processor. Select the corresponding binary based on your system’s information.
Step 2
Open a command prompt or terminal window and navigate to the directory where you extracted the CycloneDX CLI tool.
There is a chance you will experience "known publisher" issues on Mac, but we didn’t have any of the same issues on Windows. If you have any problems, try running it once as an administrator, or using Ctrl+Click to designate the file as a trusted application.
Decide whether or not to add the tool to your path, or call it locally using the ./ syntax as you move forward to the conversion process.
Converting your SBOM
Once you have everything installed, you can use this tool to convert either direction between SPDX and CycloneDX… with a caveat.
While the SPDX tooling is capable of converting our SBOM to SPDX v2.3 with annotations for any dropped items, the CycloneDX tooling will instead convert to SPDX v2.2 and will not include annotations. The upside is that you can use the same tool for all of your other CycloneDX needs, but you may be missing a few SPDX features after conversion.
The tool will typically be able to infer your SBOM format and the desired output, allowing you to run your conversion by simply specifying the existing file with the flag --input-file, and the file you want it to create using the flag --output-file:
cyclonedx-win-x86.exe convert --input-file sbom.spdx --output-file sbom.json
Customize the above command based on your situation, and make sure to use the correct executable name.
If the tool does not successfully infer your input and output types, use the –-help flag to find out about additional options that may resolve the issue:
cyclonedx-win-x86.exe convert –-help
Once the command completes successfully, you should see the output CycloneDX-formatted SBOM file in the location that you specified.
Comparing your SBOMs
The last thing you may want to do is confirm the result of your conversion. Use the diff command to compare two files of different formats.
For example, target components specifically by running the following diff command:
cyclonedx-win-x86.exe diff sbom.spdx sbom.json --component-versions
Note that the --component-versions option is required if you run the diff command for Windows, but omit for Mac to get the diff.
Sonatype's position and the future of SBOMs
Sonatype's commitment to advancing SBOM standards reflects a broader vision for a secure and transparent software supply chain.
While CycloneDX has been a focal point of Sonatype's contributions, the company's involvement with the SPDX Working Group underscores a balanced approach to embracing diverse SBOM standards. This dual engagement mirrors the evolving landscape of software development and security, where collaboration and standardization are key.
As the industry moves towards greater automation and standardization, Sonatype's role exemplifies a forward-thinking strategy of leveraging SBOMs to enhance the integrity and reliability of software components across all sectors.
