CycloneDX is a lightweight software bill-of-material (SBOM) specification designed for use in application security contexts and supply chain component analysis.

News

  • 3 March, 2019: CycloneDX BOM specification v1.1 has been released and includes numerous improvements including external references, component pedigree, license enhancements, and is more extensible.

Introduction

In software engineering, it is common to build new software by leveraging existing components. In doing so, it is often necessary to provide a bill of material that describes the components that are packaged with an application.

Project Goals

  • Define a vendor agnostic specification independent of language or ecosystem
  • Specification should be simultaneously human and machine readable
  • Specification should be simple to implement with minimal effort
  • Specification should provide lightweight schema definitions for JSON and XML
  • Specification should reuse parts of existing specs where beneficial
  • Specification should be decentralized, authoritative, and security focused
  • Specification should promote continuous component analysis
  • Specification should support hardware, libraries, frameworks, applications, and operating systems

Achievable Use Cases

  • Vulnerability analysis (software and hardware)
  • Outdated component analysis
  • License identification and compliance
  • File verification
  • Hierarchical representation of component assemblies
  • Document a components pedigree including ancestors, descendants, variants, and commits, representing a components lineage from any viewpoint and what attributes make it unique
  • Analyze modified open source libraries without any loss of fidelity
  • Human and machine readable format designed to be simple to use, extensible, and easily adoptable

Namespaces

CycloneDX defines two unique namespaces, a bill-of-material (bom) namespace and a SPDX namespace. The SPDX namespace evolves independently from the bom namespace. As new SPDX licenses are added to the SPDX specification, those changes will be reflected in the bom namespace automatically, without having to change namespaces.

CycloneDX is a versioned namespace and operates as follows:

  • http://cyclonedx.org/schema/bom will always reference the latest version of the spec.
  • Supplying a version after /bom such as http://cyclonedx.org/schema/bom/1.1 will specify a specific version of the spec.

Specification Overview

Field Description Required
type Describes if the component is a library, framework, application, operating system, or hardware device ✔
publisher The person(s) or organization(s) that published the component  
group The high-level classification that a project self-describes as. This will often be a shortened, single name of the company or project that produced the component, or the source package or domain name.  
name The name of the component as defined by the project ✔
version The version of the component as defined by the project ✔
description A description of the component  
scope Specifies the scope of the component. If scope is not specified, ‘runtime’ scope will be assumed.  
hashes File hashes supporting MD5, SHA1, SHA2, and SHA3  
license A node describing zero or more license names, SPDX license IDs or expressions  
copyright An optional copyright notice informing users of the underlying claims to copyright ownership in a published work  
purl The Package URL of the component  
cpe An optional mapping to an existing CPE identifier  
modified Indicates if the component has been modified from the official distribution  
pedigree A node which contains component ancestors, descendants, variants, and the commit which make it unique  
externalReferences A node which contains various types of references to external resources  
components Specifies optional sub-components. This is not a dependency tree. It provides a hierarchical representation of component assemblies  

Example BOM

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1">
  <components>
    <component type="library">
      <publisher>Apache</publisher>
      <group>org.apache.tomcat</group>
      <name>tomcat-catalina</name>
      <version>9.0.14</version>
      <hashes>
        <hash alg="MD5">3942447fac867ae5cdb3229b658f4d48</hash>
        <hash alg="SHA-1">e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
        <hash alg="SHA-256">f498a8ff2dd007e29c2074f5e4b01a9a01775c3ff3aeaf6906ea503bc5791b7b</hash>
        <hash alg="SHA-512">e8f33e424f3f4ed6db76a482fde1a5298970e442c531729119e37991884bdffab4f9426b7ee11fccd074eeda0634d71697d6f88a460dce0ac8d627a29f7d1282</hash>
      </hashes>
      <licenses>
        <license>
          <id>Apache-2.0</id>
        </license>
      </licenses>
      <purl>pkg:maven/org.apache.tomcat/[email protected]?packaging=jar</purl>
    </component>
      <!-- More components here -->
  </components>
</bom>

Implementations

Build plugins for a number of ecosystems have been created which support the automatic identification of all project dependencies and automatically generate CycloneDX BOMs. The resulting BOMs may contain many of the elements above including group, name, version, description, file hashes, license, and PackageURL. Additionally, a standalone Java API was created for the programmatic creation and validation of CycloneDX BOMs.

Additional build plugins are planned and we’re actively looking for volunteers to assist.

.NET

The .NET Core module creates CycloneDX BOMs from existing Visual Studio solutions and projects. The module will automatically resolve all metadata (via NuGet) for all direct and transitive dependencies.

Installing
dotnet tool install --global CycloneDX
Creating a BOM
cyclonedx YourSolution.sln -o /output/path

Node Package Manager

The NPM module creates CycloneDX BOMs from existing Node.js projects that use NPM. The module will automatically resolve all metadata for all direct and transitive dependencies.

Installing
npm install -g @cyclonedx/bom
Creating a BOM
cyclonedx-bom -o bom.xml

Java (Maven)

The Maven plugin creates CycloneDX BOMs from existing Java projects. The plugin will automatically resolve all metadata for all direct and transitive dependencies.

Creating a BOM
mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom
Creating an Aggregate BOM
mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom
Maven Defaults
<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>LATEST</version>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>makeAggregateBom</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <includeCompileScope>true</includeCompileScope>
        <includeProvidedScope>true</includeProvidedScope>
        <includeRuntimeScope>true</includeRuntimeScope>
        <includeSystemScope>true</includeSystemScope>
        <includeTestScope>false</includeTestScope>
    </configuration>
</plugin>
NOTE: makeBom and makeAggregateBom can optionally be skipped by setting cyclonedx.skip to true.

Python

The Python module creates CycloneDX BOMs from existing Python projects that have dependencies managed through pypi. The module will automatically resolve all metadata (via pypi) for all dependencies identified in requirements.txt. A bill-of-material such as CycloneDX expects exact version numbers. Therefore requirements.txt must be frozen. This can be accomplished via:

Freezing
pip freeze > requirements.txt
Installing
pip install cyclonedx-bom
Creating a BOM
cyclonedx-py -i requirements.txt -o bom.xml

Component Ecosystems

Components often belong to one or more ecosystems. These ecosystems typically have one or more sources of truth that provide additional data about the components. For example, Maven Central and the NPM repository provide information about Java and Node components respectively. Likewise, Linux distributions typically utilize one or more repositories for packages within their ecosystem including RPM, Debian, and Solus.

Package URL (purl)

Package URL was created to standardize how software package metadata is represented so that packages could universally be located regardless of what vendor, project, or ecosystem the packages belong. Package URL conforms to RFC-3986.

The syntax of Package URL is:

scheme:type/namespace/[email protected]?qualifiers#subpath
  • Scheme: Will always be ‘pkg’ to indicate a Package URL (required)
  • Type: The package “type” or package “protocol” such as maven, npm, nuget, gem, pypi, etc. Required.
  • Namespace: Some name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization. Optional and type-specific.
  • Name: The name of the package. Required.
  • Version: The version of the package. Optional.
  • Qualifiers: Extra qualifying data for a package such as an OS, architecture, a distro, etc. Optional and type-specific.
  • Subpath: Extra subpath within a package, relative to the package root. Optional.

History

CycloneDX was originally designed for use with OWASP Dependency-Track, an open-source software composition analysis (SCA) platform with a focus on continuous component analysis. A dedicated project, separate from OWASP, was setup to develop the specification and the implementations. Research into existing formats at the time revealed that they either lacked supply chain or security focus, or were governed by slow-moving projects or standards bodies.

The CycloneDX project removes these blocking activities and strives to innovate whenever possible.