CycloneDX BOM-Link

 

I'm a circle
Software Bill of Materials
Software-as-a-Service BOM
Vulnerability Exploitability Exchange
Manufacturing Bill of Materials
Operations Bill of Materials
Bill of Vulnerabilities
Javascript Object Notation
Extensible Markup Language
Protocol Buffers

With CycloneDX, it is possible to reference a component, service, or vulnerability inside a BOM from other systems or other BOMs. This deep-linking capability is referred to as BOM-Link and is a formally registered URN, governed by IANA, and compliant with RFC-8141.

Syntax:

urn:cdx:serialNumber/version#bom-ref

Examples:

urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1
urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#componentA
Field Description
serialNumber The unique serial number of the BOM. The serial number MUST conform to RFC-4122.
version The version of the BOM. The default version is 1.
bom-ref The unique identifier of the component, service, or vulnerability within the BOM.

There are many use cases that BOM-Link supports. Two common scenarios are to:

  • Reference one BOM from another BOM
  • Reference a specific component or service in one BOM from another BOM

Linking to External BOMs

External references provide a way to document systems, sites, and information that may be relevant but which are not included with the BOM. External references can be applied to individual components, services, or to the BOM itself. One external reference type is bom which can point to a URL of where the BOM is located, or BOM-Link URI that references the precise serial number and version of the BOM.

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.4"
     serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
     version="1">
    <components>
        <component type="library">
            <group>org.example</group>
            <name>persistence</name>
            <version>5.2.0</version>
            <externalReferences>
                <reference type="bom">
                    <url>urn:cdx:bdd819e6-ee8f-42d7-a4d0-166ff44d51e8/5</url>
                    <comment>Refers to version 5 of a specific BOM. Integrity verification should be performed to ensure the BOM has not been tampered with.</comment>
                    <hashes>
                        <hash alg="SHA-512">45c6e3d03ec4207234e926063c484446d8b55f4bfce3f929f44cbc2320565290cc4b71de70c1d983792c6d63504f47f6b94513d09847dbae69c8f7cdd51ce980</hash>
                    </hashes>
                </reference>
            </externalReferences>
        </component>
    </components>
</bom>
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
  "components": [
    {
      "type": "library",
      "group": "org.example",
      "name": "persistence",
      "version": "5.2.0",
      "externalReferences": [
        {
          "type": "bom",
          "url": "urn:cdx:bdd819e6-ee8f-42d7-a4d0-166ff44d51e8/5",
          "comment": "Refers to version 5 of a specific BOM. Integrity verification should be performed to ensure the BOM has not been tampered with.",
          "hashes": [
            {
              "alg": "SHA-512",
              "content": "45c6e3d03ec4207234e926063c484446d8b55f4bfce3f929f44cbc2320565290cc4b71de70c1d983792c6d63504f47f6b94513d09847dbae69c8f7cdd51ce980"
            }
          ]
        }
      ]
    }
  ]
}

Refer to the External References Use Case for additional information.

Linking External VEX to BOM Inventory

Inventory described in a BOM (SBOM, SaaSBOM, etc) will typically remain static until such time the inventory changes. However, vulnerability information is much more dynamic and subject to change. Therefore, it is recommended to decouple the VEX from the BOM. This allows VEX information to be updated without having to create and track additional BOMs.

VEX is an integral part of the CycloneDX specification providing the convenience of leveraging a single format and tool chain.

In the following example, a vulnerability is identified in a component called Jackson Databind, and the VEX provides a direct link to the precise component within a BOM.

Example

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.4" version="1">
    <vulnerabilities>
        <vulnerability>
            <id>CVE-2018-7489</id>
            <source>
                <name>NVD</name>
                <url>https://nvd.nist.gov/vuln/detail/CVE-2019-9997</url>
            </source>
            <ratings>
                <rating>
                    <source>
                        <name>NVD</name>
                        <url>https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&amp;version=3.0</url>
                    </source>
                    <score>9.8</score>
                    <severity>critical</severity>
                    <method>CVSSv3</method>
                    <vector>AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H</vector>
                </rating>
            </ratings>
            <cwes>
                <cwe>184</cwe>
                <cwe>502</cwe>
            </cwes>
            <description>FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.</description>
            <recommendation>Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.</recommendation>
            <advisories>
                <advisory>
                    <title>GitHub Commit</title>
                    <url>https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2</url>
                </advisory>
                <advisory>
                    <title>GitHub Issue</title>
                    <url>https://github.com/FasterXML/jackson-databind/issues/1931</url>
                </advisory>
            </advisories>
            <created>2021-01-01T00:00:00.000Z</created>
            <published>2021-01-01T00:00:00.000Z</published>
            <updated>2021-01-01T00:00:00.000Z</updated>
            <analysis>
                <state>not_affected</state>
                <justification>code_not_reachable</justification>
                <responses>
                    <response>will_not_fix</response>
                    <response>update</response>
                </responses>
                <detail>An optional explanation of why the application is not affected by the vulnerable component.</detail>
            </analysis>
            <affects>
                <target>
                    <ref>urn:cdx:3e671687-395b-41f5-a30f-a58921a69b79/1#jackson-databind-2.8.0</ref>
                </target>
            </affects>
        </vulnerability>
    </vulnerabilities>
</bom>
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "version": 1,
  "vulnerabilities": [
    {
      "id": "CVE-2018-7489",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2019-9997"
      },
      "ratings": [
        {
          "source": {
            "name": "NVD",
            "url": "https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&version=3.0"
          },
          "score": 9.8,
          "severity": "critical",
          "method": "CVSSv3",
          "vector": "AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
        }
      ],
      "cwes": [
        184,
        502
      ],
      "description": "FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.",
      "recommendation": "Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.",
      "advisories": [
        {
          "title": "GitHub Commit",
          "url": "https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2"
        },
        {
          "title": "GitHub Issue",
          "url": "https://github.com/FasterXML/jackson-databind/issues/1931"
        }
      ],
      "created": "2021-01-01T00:00:00.000Z",
      "published": "2021-01-01T00:00:00.000Z",
      "updated": "2021-01-01T00:00:00.000Z",
      "analysis": {
        "state": "not_affected",
        "justification": "code_not_reachable",
        "response": ["will_not_fix", "update"],
        "detail": "An optional explanation of why the application is not affected by the vulnerable component."
      },
      "affects": [
        {
          "ref": "urn:cdx:3e671687-395b-41f5-a30f-a58921a69b79/1#jackson-databind-2.8.0"
        }
      ]
    }
  ]
}

CycloneDX Supporters