Skip to content

CycloneDX object model

Definition

The CycloneDX object model is the schema at the core of the OWASP CycloneDX bill-of-materials standard: a modular, extensible object model for stating what a software system is made of and what is claimed about it — BOM metadata, components, services, dependencies, compositions, vulnerabilities, formulation, annotations, definitions, declarations and citations — serialized interchangeably as XML, JSON or Protocol Buffers under IANA-registered media types.

Explanation

The model's reach comes from pairing an inventory with the claims made about it. Components cover first- and third-party software, hardware devices, machine-learning models, source code and configurations, each carrying manufacturer, license, pedigree and provenance detail; services capture external APIs with endpoint URIs, authentication requirements, trust-boundary traversals and classified, directional data flows; a dependency graph records direct and transitive relationships, including components that depend on services and services on other services. Compositions state how complete an inventory claims to be — complete, incomplete, incomplete first- or third-party-only, or unknown — which scopes what a BOM actually asserts. The vulnerabilities object communicates both known vulnerabilities with their exploitability and previously unknown ones, serving disclosure and VEX alike; formulation records declared versus observed manufacture and deployment; definitions express standards (OWASP ASVS, MASVS, SCVS, SAMM and others) machine-readably while declarations attach attestations, claims, counter-claims, evidence and signatures against them — the basis for compliance-as-code; annotations and citations make BOM content attributable and independently signable, which matters when several tools and parties contribute to one document. The integration surface is deliberately plain: IANA-registered media types with a version parameter, conventional file names and globs, and a recognized in-toto predicate type. The source is the project's own specification overview — it documents representational capability, not adoption evidence, and its promotional framing should be read as scope rather than proof.

Key Properties

  • Eleven core object families — metadata, components, services, dependencies, compositions, vulnerabilities, formulation, annotations, definitions, declarations, citations — plus extension points throughout
  • Dependency graph represents direct and transitive edges, including component-to-service and service-to-service dependencies
  • Compositions declare inventory completeness: complete, incomplete, incomplete first-party-only, incomplete third-party-only, or unknown
  • Serializes to XML, JSON and Protocol Buffers under IANA-registered media types, version-pinnable via a media-type version parameter
  • Recognized on disk as bom.json/bom.xml or .cdx.json/.cdx.xml, and https://cyclonedx.org/bom is the in-toto predicate type covering SBOM, SaaSBOM and HBOM

Relationships

  • OSV format — complementary supply-chain interchange formats: OSV describes individual open source vulnerabilities with precise affected-version ranges, while CycloneDX describes whole systems and uses its vulnerabilities object to attach known or newly disclosed vulnerabilities — including VEX exploitability statements — to that component inventory
  • Vulnerability range events — the range algorithm vulnerability range events describes is exactly the kind of fact the CycloneDX object model's vulnerabilities section is built to carry, alongside component and dependency data an advisory alone doesn't include.

Applications

Producing and exchanging SBOMs, SaaSBOMs and HBOMs for vulnerability management, license compliance and VEX workflows; expressing security standards and conformance attestations machine-readably for compliance-as-code pipelines.

Sources

  • https://cyclonedx.org/specification/overview/

See Also