A Practical Guide to CycloneDX

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 many 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 CycloneDX v1.6 was published in April, 2024. This followed the release of CycloneDX 1.5 in June, 2023.

Today, CycloneDX is in production at an estimated 100,000 organizations.

Although CycloneDX is often thought of exclusively as a software bill of materials format, it can 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.

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, while CycloneDX 1.6 added support for Cryptographic Bill of Materials (CBOM).

Primary CycloneDX Use Cases

• Component inventory: This serves as the foundation for all component analysis. CycloneDX can describe multiple types of components: applications, containers, devices, libraries, files, firmware, frameworks, operating systems, and services.
• Vulnerability analysis: CycloneDX can be used for several different types of vulnerability analysis: known vulnerabilities, unknown vulnerabilities, vulnerability exploitability, and whether a vulnerability has been remediated.
• Software package evaluation: CycloneDX enables several dimensions of package analysis, including age and overall health of open source packages.
• License identification and compliance: CycloneDX offers multiple ways to document open source licenses: SPDX license IDs, SPDX expressions, and license names. Additionally, CycloneDX v1.5 added support for commercial licenses.
• Assemblies: With CycloneDX, you can represent complex component assemblies and digitally sign each one, similar to how physical subcomponents are tracked in manufacturing.
• Component pedigree: CycloneDX captures software component pedigree: the relationships in terms of descendants, variants, ancestors, and specific modifications made to open source components.

The CycloneDX bill of materials model consists of 10 root-level elements that provide a comprehensive framework for describing software components and their relationships.

The 10 root-level elements of a CycloneDX bill of materials

Root-Level Elements Explained

• Metadata: Information about the component, supplier, and manufacturer that the bill of materials describes, including license information and tools used to generate it.
• Components: Individual first- and third-party components that make up the larger component your BOM describes, including applications, libraries, frameworks, and more.
• Services: External APIs that your software may call, including endpoint URIs, trust boundary traversals, and authentication requirements.
• Dependencies: Relationships capturing what components rely on other components or what services depend on other services, including both direct and transitive dependencies.
• Compositions: Used to capture the degree to which your description of BOM elements is complete or incomplete, distinguishing between various levels of completeness.
• Vulnerabilities: Details about known and previously unknown vulnerabilities, including severity scores, VEX data, and remediation status.
• Formulation: Added in CycloneDX 1.5, describes how something was manufactured or deployed, including tasks, steps, and workflows.
• Annotations: Added in CycloneDX 1.5, allows for additional context such as comments or notes to be added to the bill of materials.
• Declarations: Added in CycloneDX 1.6, used to describe compliance with regulatory requirements and state claims about security processes.
• Definitions: Added in CycloneDX 1.6, provides a mechanism to define standards, best practices, and maturity models.

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.

Key Differences

Origin Stories

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 origins are still evident in their designs and capabilities.

"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."

File Formats

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, while 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:

For New FOSSA Users

1. Start by creating your free FOSSA account.
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.)

Generate Your CycloneDX SBOM

1. Log into your account, and click on the "Projects" button in the header menu
2. Click on the Project that you'd like your SBOM to describe
3. Select the "Generate a Compliance Report" button from the "Actions" menu (on the right side of your screen)
4. Select your SBOM export format (FOSSA supports SPDX, Plain Text, CSV, Markdown, PDF, and HTML in addition to CycloneDX)
5. Decide which elements to include in your report — you can do this by checking (or unchecking) boxes in the "Customize Report Information" menu
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
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.