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 as they’ve updated their National Cybersecurity Strategy.
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.
CycloneDX, on the other hand, 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.
Both support the generation of SBOMs. 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.
In this blog post, we describe how to convert between SBOM formats using tooling from the official repositories of SPDX and CycloneDX. 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.
Now go and do likewise
Hopefully this guide streamlines your efforts in converting between SBOM formats! Reach out to me on Twitter if you have any thoughts on this topic.
