Specification Overview

 

The CycloneDX object model:

• is defined in JSON Schema, XML Schema, and Protocol Buffers
• consists of metadata, components, services, dependencies, compositions, and vulnerabilities.
• is prescriptive and simple to use
• is designed for SBOM, SaaSBOM, OBOM, MBOM, and VEX use cases
• can easily describe complex relationships
• is extensible to support specialized and future use cases

BOM Metadata

BOM metadata includes the supplier, manufacturer, and the target component for which the BOM describes. It also includes the tools used to create the BOM, and license information for the BOM document itself.

Components

Components describe the complete inventory of first-party and third-party components. Component identity can be represented as:

• Coordinates (group, name, version)
• Package URL
• Common Platform Enumeration (CPE)
• SWID (ISO/IEC 19770-2:2015)
• Cryptographic hash functions (SHA-1, SHA-2, SHA-3, BLAKE2b, BLAKE3)

CycloneDX can represent applications, frameworks, libraries, containers, operating systems, devices, firmware, files, along with the manufacturer information, license and copyright details, and complete pedigree and provenance for every component.

Services

Services describe external APIs that the software may call. Services describe endpoint URI’s, authentication requirements, and trust boundary traversals. The flow of data between software and services can also be described including the data classifications, and the flow direction of each type.

Dependencies

CycloneDX provides the ability to describe components and their dependency on other components. The dependency graph is capable of representing both direct and transitive relationships. Components that depend on services can be represented in the dependency graph and services that depend on other services can be represented as well.

Compositions

Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The aggregate of each composition can be described as complete, incomplete, incomplete first-party only, incomplete third-party only, or unknown.

Vulnerabilities

Known vulnerabilities inherited from the use of third-party and open source software and the exploitability of the vulnerabilities can be communicated with CycloneDX. Previously unknown vulnerabilities affecting both components and services may also be disclosed using CycloneDX, making it ideal for both VEX and security advisory use cases.

Extensions

Multiple extension points exist throughout the CycloneDX object model allowing fast prototyping of new capabilities and support for specialized and future use cases. The CycloneDX project maintains extensions that are beneficial to the larger community. The project encourages community participation and development of extensions that target specialized or industry-specific use cases.

High-Level Object Model

Registered Media Types

The following media types are officially registered with IANA:

Media Type	Format	Assignment
application/vnd.cyclonedx+xml	XML	IANA
application/vnd.cyclonedx+json	JSON	IANA

Specific versions of CycloneDX can be specified by using the version parameter. i.e. application/vnd.cyclonedx+xml; version=1.4.

The officially supported media type for Protocol Buffer format is application/x.vnd.cyclonedx+protobuf.

Recognized file patterns

The following file names are conventionally used for storing CycloneDX BOM files -

• bom.json for JSON encoded CycloneDX BOM files.
• bom.xml for XML encoded CycloneDX BOM files.

Alternatively, files that match the glob pattern below are also recognized -

• *.cdx.json for JSON encoded CycloneDX BOM files.
• *.cdx.xml for XML encoded CycloneDX BOM files.

Recognized predicate type

Many tools in the software supply chain capture attestations at the time of execution. A predicate contains metadata about the attestation. Tools such as in-toto use predicate types to provide context about the subject of the predicate. OWASP recognizes https://cyclonedx.org/bom as the official predicate type for all CycloneDX bill of material varieties including SBOM, SaaSBOM, and HBOM.