- 3 March, 2019: CycloneDX SBOM specification v1.1 has been released and includes numerous improvements including external references, component pedigree, license enhancements, and is more extensible.
Modern software is assembled using third-party and open source components, glued together in complex and unique ways, and integrated with original code to provide the desired functionality. Reusing components has many economic and technical advantages. However, documenting the use of third-party and open source components is often desirable in order to perform supply chain component analysis. CycloneDX was created for this purpose.
- 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 the 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 and consists of license identifiers. As new SPDX licenses are added to the SPDX specification over time, those changes will be reflected in the bom schema automatically.
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, hardware device, or file||✔|
|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||Describes 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 commits 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 SBOMs. The resulting SBOMs 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 SBOMs.
- 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 designed in 2017 for use with OWASP Dependency-Track, an open-source Software Composition Analysis (SCA) platform. The primary use-cases CycloneDX was designed to solve were vulnerability identification, license compliance, and outdated component analysis. Additional capabilities were added in subsequent releases of the specification.
The value of a lightweight SBOM specification, capable of achieving real-world usecases, transcends the boundaries of a single vendor or supplier. Therefore, a dedicated project, independent of OWASP, was setup to develop the specification, the implementations, and move the format into widespread adoption. Today, thousands of organizations ranging from financial services, manufacturing, software, and security firms are producing and consuming CycloneDX SBOMs.