External references in CycloneDX enhance the usability and flexibility of BOMs by linking objects, such as components or services, to external resources or contextual information. In this context, "external" means external to the object they describe, not necessarily the BOM itself. These references establish relationships within the same BOM or across BOMs, enabling traceability and modularity. By linking to URLs, documentation, or other BOMs, external references provide richer context and structure, supporting better risk management, compliance tracking, and integration with tools and workflows.
Cross-BOM references in CycloneDX leverage BOM-Link, a powerful mechanism for connecting components or metadata across separate BOMs. This capability ensures a modular approach to managing complex systems, reducing redundancy and streamlining updates when shared dependencies evolve. BOM-Link provides a standardized, traceable way to establish relationships between BOMs, enabling organizations to maintain clarity and consistency across interconnected software projects.
| Name | Description |
|---|---|
| vcs | Version Control System |
| issue-tracker | Issue or defect tracking system, or an Application Lifecycle Management (ALM) system |
| website | Website |
| advisories | Security advisories |
| bom | Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc) |
| mailing-list | Mailing list or discussion group |
| social | Social media account |
| chat | Real-time chat platform |
| documentation | Documentation, guides, or how-to instructions |
| support | Community or commercial support |
| source-distribution | The location where the source code distributable can be obtained. This is often an archive format such as zip or tgz. The source-distribution type complements use of the version control (vcs) type. |
| distribution | Direct or repository download location |
| distribution-intake | The location where a component was published to. This is often the same as "distribution" but may also include specialized publishing processes that act as an intermediary. |
| license | The reference to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness. |
| build-meta | Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc) |
| build-system | Reference to an automated build system |
| release-notes | Reference to release notes |
| security-contact | Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT. |
| model-card | A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency. |
| log | A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations. |
| configuration | Parameters or settings that may be used by other components or services. |
| evidence | Information used to substantiate a claim. |
| formulation | Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself. |
| attestation | Human or machine-readable statements containing facts, evidence, or testimony. |
| threat-model | An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format. |
| adversary-model | The defined assumptions, goals, and capabilities of an adversary. |
| risk-assessment | Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk. |
| vulnerability-assertion | A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product. |
| exploitability-statement | A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization. |
| pentest-report | Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test. |
| static-analysis-report | SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code. |
| dynamic-analysis-report | Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations. |
| runtime-analysis-report | Report generated by analyzing the call stack of a running application. |
| component-analysis-report | Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis. |
| maturity-report | Report containing a formal assessment of an organization, business unit, or team against a maturity model. |
| certification-report | Industry, regulatory, or other certification from an accredited (if applicable) certification body. |
| codified-infrastructure | Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC). |
| quality-metrics | Report or system in which quality metrics can be obtained. |
| poam | Plans of Action and Milestones (POA&M) complement an "attestation" external reference. POA&M is defined by NIST as a "document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones". |
| electronic-signature | An e-signature is commonly a scanned representation of a written signature or a stylized script of the person's name. |
| digital-signature | A signature that leverages cryptography, typically public/private key pairs, which provides strong authenticity verification. |
| rfc-9116 | Document that complies with RFC 9116 (A File Format to Aid in Security Vulnerability Disclosure) |
| patent | References information about patents which may be defined in human-readable documents or in machine-readable formats such as CycloneDX or ST.96. For detailed patent information or to reference the information provided directly by patent offices, it is recommended to leverage standards from the World Intellectual Property Organization (WIPO) such as ST.96. |
| patent-family | References information about a patent family which may be defined in human-readable documents or in machine-readable formats such as CycloneDX or ST.96. A patent family is a group of related patent applications or granted patents that cover the same or similar invention. For detailed patent family information or to reference the information provided directly by patent offices, it is recommended to leverage standards from the World Intellectual Property Organization (WIPO) such as ST.96. |
| patent-assertion | References assertions made regarding patents associated with a component or service. Assertions distinguish between ownership, licensing, and other relevant interactions with patents. |
| citation | A reference to external citations applicable to the object identified by this BOM entry or the BOM itself. When used with a BOM-Link, this allows offloading citations into a separate CycloneDX BOM. |
| other | Use this if no other types accurately describe the purpose of the external reference. |
{
"$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
"bomFormat": "CycloneDX",
"specVersion": "1.7",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"group": "com.example",
"name": "persistence",
"version": "5.2.0",
"externalReferences": [
{
"type": "bom",
"url": "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1",
"comment": "Refers to a specific BOM (via BOM-Link) with the specified serial number and version. Integrity verification should be performed to ensure the BOM has not been tampered with.",
"hashes": [
{
"alg": "SHA-256",
"content": "9048a24d72d3d4a1a0384f8f925566b44f133dd2a0194111a2daeb1cf9f7015b"
},
{
"alg": "SHA-384",
"content": "8640424aa9bf337678580c55d23e54b973703c6e586987d85700f24d5de383cd1add590ee5b98d1710a01aff212687f3"
},
{
"alg": "SHA-512",
"content": "45c6e3d03ec4207234e926063c484446d8b55f4bfce3f929f44cbc2320565290cc4b71de70c1d983792c6d63504f47f6b94513d09847dbae69c8f7cdd51ce980"
}
]
},
{
"type": "license",
"url": "urn:cdx:fcc8083d-0654-4da8-82ed-db9a3ec33cba/1#persistence-library-license",
"comment": "Refers to a specific commercial license object within a BOM."
}
]
}
]
}