SBOM Starter Kit: Get Your Copy
CycloneDX is a full-stack bill of materials specification designed for modern software supply chains. It’s best known as a software bill of materials (SBOM) standard — and SBOMs are a top use case — but CycloneDX can also be used for vulnerability reports and other bill of materials varieties.
CycloneDX has gained significant popularity and increased adoption since it was listed as an approved SBOM data format in the U.S. federal government’s 2021 cybersecurity executive order. But the standard has been in existence for several years, dating back to 2017 when the initial prototype was released.
The current version (v1.5) of CycloneDX was published in June 2023. Today, CycloneDX is in production at an estimated 100,000 organizations.
In this guide, we’ll provide an overview of CycloneDX, including its top use cases, how it compares to other machine-readable bill of materials formats (like SPDX), and strategies for generating and importing a CycloneDX SBOM.
Although CycloneDX is often thought of exclusively as a software bill of materials format, it can also be used for other important supply chain security initiatives. These include OBOM (operations bill of materials), BOV (bill of vulnerabilities), VDR (vulnerability disclosure report), and VEX (vulnerability exploitability exchange), among others. Additionally, CycloneDX 1.5 added three new use cases to support supply chain security and transparency in even more industries: Machine Learning Bill of Materials (ML-BOM), Manufacturing Bill of Materials (MBOM), and SBOM for Low Code Application Platforms.
“CycloneDX does a lot of different things,” Steve Springett, Chair of the CycloneDX Core Working Group, told FOSSA during a recent webinar. “Certainly software is something CycloneDX can represent, but it can also represent services — there’s a concept called SaaS BOM, which is an inventory of all your services and is really important on the consumption side. CycloneDX can also be used to generate a hardware bill of materials. For IoT scenarios, this describes what that hardware stack is and what that software stack is that’s running on that hardware independent of one another.”
Other CycloneDX use cases include:
CycloneDX can also be used for OpenChain Conformance (ISO/IEC 5230:2020), security advisories, and to describe remediations made to vulnerable components, among other purposes.
The CycloneDX bill of materials model consists of eight root-level elements: metadata, components, services, dependencies, compositions, vulnerabilities, formulation, and annotations. Let’s take a look at each.
Metadata refers to the component (e.g. application, hardware, service, etc), supplier, and manufacturer that the bill of materials describes. It also includes license information for the bill of materials document as well as any tools used to generate it.
Components encompass the individual first- and third-party components that make up the larger component your bill of materials describes. These include applications, libraries, frameworks, and several others. CycloneDX 1.5 added support for four new types of components: data, device driver, ML model, and platform. With CycloneDX, you can identify components in a number of ways, including Package URL, coordinates (group, name, version), Common Platform Enumeration (CPE), SWID tag, and cryptographic hash function.
Services refer to external APIs that your software may call. CycloneDX can describe endpoint URIs, trust boundary traversals, authentication requirements, data classifications, directional flow of data, and providers.
Dependency relationships capture what components rely on other components or what services depend on other services. The CycloneDX dependency graph can show your entire dependency graph, so you can specify direct and transitive dependencies.
Compositions are used to capture the degree to which your description of BOM elements is complete (or incomplete). This makes it possible to distinguish between a bill of materials that reflects only, say, first-party software components and one that reflects all components. Each composition can be described as complete, incomplete, incomplete first-party only, incomplete third-party only, or unknown.
Vulnerabilities: CycloneDX can describe several types of data related to known and previously unknown vulnerabilities. This includes:
Formulation is a new root-level element in CycloneDX 1.5. It "describes how something was manufactured or deployed." CycloneDX can describe areas like tasks, steps, and workflows, among other processes.
Annotations is also a new root-level element in CycloneDX 1.5. Annotations allow for additional context to be added to the bill of materials. For example, an annotation may be used to add a comment or note clarifying a certain relationship. Annotations can be independently signed and verified with the use of digital signatures; annotations can be added both by tools and through manual review.
CycloneDX also includes multiple extension points. Per the standard’s website, the objective of this extensibility is to enable “fast prototyping of new capabilities and support for specialized and future use cases.”
Finally, it's important to note that the new CycloneDX 1.5 added support for snippets and has significantly expanded its support for relationship types. Relationship types can be used to provide important context about the BOM or one of its components or services. This includes not only dependency relationships and assemblies, but now also a wide range of external references. External references can refer to both items outside the SBOM (i.e. URL of a build system, website, or VCS, among others) as well as items within the SBOM. A full list of external references can be found on Page 41 of CycloneDX's "Authoritative Guide to SBOM."
CycloneDX and SPDX occupy a special place in the modern software bill of materials landscape. They’re both human- and machine-readable, and they’re the two approved full-stack SBOM formats under the U.S. government’s 2021 cybersecurity executive order. (SWID Tags are also mentioned in the executive order and do capture descriptive metadata about software components, but they aren’t comprehensive in the way SPDX and CycloneDX are.) However, there are notable differences between SPDX and CycloneDX. These include:
SPDX was originally developed primarily for open source license compliance and intellectual property use cases, while CycloneDX was created with security in mind. Both standards have evolved significantly since their initial releases, but their history is still evident today. For example, CycloneDX has more extensive support for vulnerability management, including VEX (Vulnerability Exploitability eXchange) data; VEX is used to communicate the exploitability of software components in the context where they’re used.
“As an OWASP project, we came from a security context, which is a little bit different than some of the other formats and their origin stories,” CycloneDX Core Working Group Chair Steve Springett told FOSSA in a recent webinar. “Our origin story was really about security, and we bring that expertise to the format.”
Both SPDX and CycloneDX are available in JSON and XML. SPDX also supports tag/value (which it describes as a “simple text-based format”), YAML, and Excel spreadsheets, and CycloneDX also supports Protocol Buffers.
There are multiple ways to generate a CycloneDX software bill of materials, but as a general rule, we recommend doing so during the build process. This is because running an SBOM report right after the completion of your build will produce the most accurate inventory of dependencies possible.
With FOSSA, you can easily generate a CycloneDX SBOM in either JSON or XML formats. Here’s how it works.
If you aren’t a current FOSSA user:
Step 1: Start by creating your free FOSSA account.
Step 2: Then, navigate to Projects > Add Project to import your first project. (You can integrate locally with our CLI or import code from a VCS like GitHub.)
Once you’ve imported your first project:
Step 1: Log into your account, and click on the “Projects” button in the header menu
Step 2: Click on the Project that you’d like your SBOM to describe
Step 3: Select the “Generate a Compliance Report” button from the “Actions” menu (on the right side of your screen)
Step 4: Select your SBOM export format (FOSSA supports SPDX, Plain Text, CSV, Markdown, PDF, and HTML in addition to CycloneDX)
Step 5: Decide which elements to include in your report — you can do this by checking (or unchecking) boxes in the “Customize Report Information” menu.
Step 6: Click on “Edit Dependency Info” (in the Customize Report Information” menu to decide which dependency metadata (e.g. author, package manager, file path, etc) to include in your SBOM
Step 7: Generate your report — either download a copy to distribute yourself, or create a public link for your file
FOSSA also supports the import of third-party CycloneDX SBOMs. You can use this feature to understand the composition of third-party software, including any security or license compliance risks it might pose. SBOM import is available only for users with a paid FOSSA account. For information about signing up for a paid account, please reach out to our team.