Announcing Support for CycloneDX and SBOM Import - Learn More

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 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.4) of CycloneDX was published in January 2022, and v1.5 is expected to be released in Q2 of 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.
Learn More
Try FOSSA's SBOM Tool

Table of Contents

CycloneDX Use Cases
CycloneDX vs. SPDX
Generating a CycloneDX SBOM

CycloneDX Use Cases

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.

“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:
  • 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: The majority of software in modern applications is open source. And, a lot of that software is in the form of packages — which are often managed by package managers. CycloneDX enables several dimensions of package analysis, including age and overall health.
  • License identification and compliance: CycloneDX offers multiple ways to document open source licenses: SPDX license IDs, SPDX expressions, and license names.
  • Assemblies: Software is complex, and sometimes components include other components. With CycloneDX, you can represent complex component assemblies and digitally sign each one. You can think of assemblies like the dashboard of an automobile. You might have an instrument cluster within the dashboard, a speedometer within the instrument cluster, and plexiglass within the speedometer. CycloneDX can be used to represent these relationships. And, if you have parts of these assemblies from different suppliers, each supplier can independently sign their specific portion.
  • Component pedigree: Software components are renamed, modified, reused, and distributed on a frequent basis. CycloneDX captures this pedigree: the relationships in terms of descendants, variants, and ancestors, and what specific modifications you’ve made to open source components.
  • Component provenance: Provenance refers to where and/or who you retrieved a component from. A common example might be an open source repository. Package URL (PURL) and SWID metadata/documents can be used to describe provenance.
  • Reliance on services: Services are an important part of your inventory since software relies on them to function. You can use CycloneDX to describe a number of different elements related to services, such as endpoint URIs and data flows.
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.

Elements of a CycloneDX Bill of Materials

The CycloneDX bill of materials model consists of six elements: metadata, components, services, dependencies, compositions, and vulnerabilities. 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. With CycloneDX, you can represent components in a number of ways: 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:
  • Vulnerability details, source, and severity score
  • VEX data (used to communicate vulnerability exploitability)
  • Security advisories (which can be used to communicate information about previously unknown vulnerabilities)
  • Whether the vulnerability has been remediated
Finally, CycloneDX 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.”

CycloneDX vs. SPDX

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:
  • 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 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. On the other hand, although both specifications can be used to represent dependency relationships (and to describe component pedigree), SPDX does support a more comprehensive list of relationship types; these may be useful in certain audit scenarios.

    “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, and CycloneDX also supports Protocol Buffers.
  • Elements
    SPDX supports the following elements that CycloneDX does not:
    • Snippets (to define licenses within a particular part of a file)
    • Annotations (essentially comments on specific parts of an SPDX document), though, CycloneDX will be adding support for annotations in the next version of its specification, v1.5.
    CycloneDX supports the following elements that SPDX does not:
    • Compositions (though you can add this type of completeness information as a comment to an SPDX BOM)
    • Vulnerabilities (though SDPX’s “External Reference for a Package” does allow linking to external vulnerability data)
    • Services

Generating a CycloneDX SBOM

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.

Try FOSSA's SBOM Tool

Request Demo