- 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.
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.
- 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
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/bomwill always reference the latest version of the spec.
- Supplying a version after /bom such as
http://cyclonedx.org/schema/bom/1.1will specify a specific version of the spec.
|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|
<?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>
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.
- CycloneDX .NET Core
- CycloneDX Node.js Module
- CycloneDX Maven Plugin
- CycloneDX Python Module
- CycloneDX Java API
Additional build plugins are planned and we’re actively looking for volunteers to assist.
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.
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.
npm install -g @cyclonedx/bom
Creating a BOM
cyclonedx-bom -o bom.xml
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
Creating an Aggregate BOM
NOTE: makeBom and makeAggregateBom can optionally be skipped by setting
<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>
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:
pip freeze > requirements.txt
pip install cyclonedx-bom
Creating a BOM
cyclonedx-py -i requirements.txt -o bom.xml
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: 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.
CycloneDX was originally designed for use with OWASP Dependency-Track, an open-source software composition analysis platform with a focus on continuous component analysis. Research into existing specifications such as SWID and SPDX revealed that neither specification was robust enough for application security contexts nor did these projects meet the basic requirements for wide-spread adoption within both enterprise build systems and the open source community.
After many discussions with Dependency-Track users and volunteers, a decision was made to create a new specification with the sole purpose of being lightweight, easily adoptable, and with a security-first approach. The new specification would build upon existing specifications where possible. CycloneDX incorporated SPDX license IDs as they were widely adopted and recognized within the community. Adoption for the emerging Package URL (purl) specification was also included to provide CycloneDX a reference to the native ecosystem metadata about the component.
Today, many organizations using Dependency-Track do so using CycloneDX as their preferred BOM format. Publishing CycloneDX BOMs can be handled through an API or via the Dependency-Track Jenkins plugin, currently in use by thousands of organizations.