CycloneDx REST API - v2

NEW IN RELEASE 70

The CycloneDX REST API - v2 returns a CycloneDX SBOM document (in both XML and JSON formats) containing coordinates and licenses for components in a scan report. Currently, it fully supports maven and npm formats. Support for other formats is continuously evolving as we develop this REST API.

Methods supported:

  1.  GET 

To use CycloneDX REST API - v2, first retrieve the internal application ID and then pass it as an input parameter.

Example:

Step 1 - Get the internal application ID using the Application REST API - v2

Use the Application REST API - v2 with the application’s public ID to retrieve the internal application ID for the application you need to generate the SBOM.

GET /api/v2/applications?publicId={YourPublicId}

Step 2 - Retrieve the SBOM for the application ID from step 1, using CycloneDX REST API - v2 

GET /api/v2/cycloneDx/{version}/{applicationInternalId}/reports/{reportId}

version indicates the supported CycloneDX schema versions. Possible values for version are 1.1, 1.2, 1.3, 1.4.

reportID corresponds to the scan report.

This API can also retrieve the SBOM based on latest application evaluation stage, by specifying the stageID in the GET method. 

GET /api/v2/cycloneDx/{version}/{applicationInternalId}/stages/{stageId}

Possible values for stageID are build,stage-release,release,operate. 

To set the output formats as XML or JSON with a specific CycloneDX Version

Set the correct Accept Type header in the http request. If no accept type is specified this API returns an XML formatted output.

Accept TypeOutput FormatSupported CycloneDX Schema Versions
"application/xml"XML1.1, 1.2, 1.3, 1.4 
"application/json"JSON1.2, 1.3, 1.4 

a. Example to set accept type for output in XML format:

curl -u admin:admin123 -X GET
http://localhost:8070/api/v2/cycloneDx/1.4/b7b2b2cc9c864ea59eb7fa0fb1d7f9ff/reports/bfdb562fad2443e593357b67eb4095e7 -H 'Accept: application/xml'

b. Example to set accept type for output in JSON format:

curl -u admin:admin123 -X GET
http://localhost:8070/api/v2/cycloneDx/1.4/b7b2b2cc9c864ea59eb7fa0fb1d7f9ff/reports/bfdb562fad2443e593357b67eb4095e7 -H 'Accept: application/json'

Response

Here is an example of XML response:

<bom xmlns="http://cyclonedx.org/schema/bom/1.4" serialNumber="a6cba7fe0559450fb70251a80709021b" version="1">
    <components>
        <component type="library">
            <group>org.apache.tomcat</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <scope>required</scope>
            <hashes>
                <hash alg="SHA-1">af008de6e523b6eeb5e8</hash>
            </hashes>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl>
        </component>
        <component type="library">
            <name>Microsoft.AspNetCore.Http.Features</name>
            <version>3.1.3</version>
            <scope>required</scope>
            <hashes>
                <hash alg="SHA-1">1c82fd7494c626d1d009</hash>
            </hashes>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
                <license>
                    <id>Not-Supported</id>
                </license>
            </licenses>
            <purl>pkg:nuget/Microsoft.AspNetCore.Http.Features@3.1.3</purl>
        </component>
    </components>
    <externalReferences>
        <reference type="bom">
            <url>http://localhost:8070/ui/links/application/app/report/a6cba7fe0559450fb70251a80709021b</url>
            <comment>http://localhost:8070/ui/links/application/app/report/a6cba7fe0559450fb70251a80709021b</comment>
        </reference>
    </externalReferences>
</bom>

NEW IN RELEASE 138

To ensure valid SBOM generation, we now put the Sonatype truncated SHA1 into a property instead of a hash and use license name instead of license id for any non-SPDX licenses.

<bom xmlns="http://cyclonedx.org/schema/bom/1.4" serialNumber="a6cba7fe0559450fb70251a80709021b" version="1">
    <components>
        <component type="library">
            <group>org.apache.tomcat</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <scope>required</scope>
            <properties>
                <property name="Sonatype truncated SHA1">af008de6e523b6eeb5e8</property>
            </properties>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl>
        </component>
        <component type="library">
            <name>Microsoft.AspNetCore.Http.Features</name>
            <version>3.1.3</version>
            <scope>required</scope>
             <properties>
                <property name="Sonatype truncated SHA1">1c82fd7494c626d1d009</property>
            </properties>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
                <license>
                    <name>Not-Supported</name>
                </license>
            </licenses>
            <purl>pkg:nuget/Microsoft.AspNetCore.Http.Features@3.1.3</purl>
        </component>
    </components>
    <externalReferences>
        <reference type="bom">
            <url>http://localhost:8070/ui/links/application/app/report/a6cba7fe0559450fb70251a80709021b</url>
            <comment>http://localhost:8070/ui/links/application/app/report/a6cba7fe0559450fb70251a80709021b</comment>
        </reference>
    </externalReferences>
</bom>

NEW IN RELEASE 143

The response now includes detailed vulnerability information in the SBOM. Note that this is only available for CycloneDX version 1.4 outputs.

<?xml version="1.0" encoding="UTF-8"?>
<bom serialNumber="urn:uuid:4b31ae4b-926f-4973-bd34-aa9efa95cd8a" version="1" xmlns="http://cyclonedx.org/schema/bom/1.4">
  <metadata>
    <timestamp>2022-08-01T19:45:40Z</timestamp>
  </metadata>
  <components>
    <component type="library" bom-ref="pkg:rpm/libzstd@1.4.4-1.el8?arch=x86_64">
      <name>libzstd</name>
      <version>1.4.4-1.el8</version>
      <purl>pkg:rpm/libzstd@1.4.4-1.el8?arch=x86_64</purl>
      <modified>false</modified>
      <properties>
        <property name="Sonatype truncated SHA1">f5f4780ecfb517cca289</property>
        <property name="Match State">exact</property>
        <property name="Identification Source">Sonatype</property>
      </properties>
    </component>
  </components>
  <externalReferences>
    <reference type="bom">
      <url>http://localhost:8070/ui/links/application/app/report/4b31ae4b926f4973bd34aa9efa95cd8a</url>
      <comment>IQ Report</comment>
    </reference>
  </externalReferences>
  <vulnerabilities>
    <vulnerability>
      <id>sonatype-2022-0219</id>
      <source>
        <name>SONATYPE</name>
        <url>http://localhost:8070/ui/links/vln/sonatype-2022-0219</url>
      </source>
      <ratings>
        <rating>
          <source>
            <name>SONATYPE</name>
          </source>
          <score>7.8</score>
          <severity>critical</severity>
          <method>other</method>
          <vector>CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H</vector>
        </rating>
      </ratings>
      <cwes>
        <cwe>119</cwe>
      </cwes>
      <affects>
        <target>
          <ref>pkg:rpm/libzstd@1.4.4-1.el8?arch=x86_64</ref>
        </target>
      </affects>
    </vulnerability>
  </vulnerabilities>
</bom>

NEW IN RELEASE 147

The response now includes dependency graph information in the SBOM. Note that this is only available for CycloneDX version 1.2 or higher.

<?xml version="1.0" encoding="UTF-8"?>
<bom serialNumber="urn:uuid:33dfc2b6-6d6f-4174-8f4f-2b09cd3ba363" version="1" xmlns="http://cyclonedx.org/schema/bom/1.2">
  <metadata>
    <timestamp>2022-10-10T16:50:51Z</timestamp>
    <component type="application" bom-ref="pkg:maven/com.samplecompany.app/sample-app@2.36.19-SNAPSHOT?type=pom">
      <group>com.samplecompany.app</group>
      <name>sample-app</name>
      <version>2.36.19-SNAPSHOT</version>
      <purl>pkg:maven/com.samplecompany.app/sample-app@2.36.19-SNAPSHOT?type=pom</purl>
    </component>
  </metadata>
  <components>
    <component type="library" bom-ref="pkg:maven/org.apache.httpcomponents/httpcore@4.4.13?type=jar">
      <group>org.apache.httpcomponents</group>
      <name>httpcore</name>
      <version>4.4.13</version>
      <licenses/>
      <purl>pkg:maven/org.apache.httpcomponents/httpcore@4.4.13?type=jar</purl>
      <modified>false</modified>
    </component>
    <component type="library" bom-ref="pkg:maven/commons-codec/commons-codec@1.15?type=jar">
      <group>commons-codec</group>
      <name>commons-codec</name>
      <version>1.15</version>
      <licenses/>
      <purl>pkg:maven/commons-codec/commons-codec@1.15?type=jar</purl>
      <modified>false</modified>
    </component>
    <component type="library" bom-ref="pkg:maven/org.slf4j/jcl-over-slf4j@1.7.36?type=jar">
      <group>org.slf4j</group>
      <name>jcl-over-slf4j</name>
      <version>1.7.36</version>
      <licenses/>
      <purl>pkg:maven/org.slf4j/jcl-over-slf4j@1.7.36?type=jar</purl>
      <modified>false</modified>
    </component>
    <component type="library" bom-ref="pkg:maven/org.apache.httpcomponents/httpclient@4.5.13?type=jar">
      <group>org.apache.httpcomponents</group>
      <name>httpclient</name>
      <version>4.5.13</version>
      <licenses/>
      <purl>pkg:maven/org.apache.httpcomponents/httpclient@4.5.13?type=jar</purl>
      <modified>false</modified>
    </component>
    <component type="library" bom-ref="pkg:maven/com.samplecompany.app/app-test@2.36.19-SNAPSHOT?type=jar">
      <group>com.samplecompany.app</group>
      <name>app-test</name>
      <version>2.36.19-SNAPSHOT</version>
      <licenses/>
      <purl>pkg:maven/com.samplecompany.app/app-test@2.36.19-SNAPSHOT?type=jar</purl>
      <modified>false</modified>
    </component>
    <component type="library" bom-ref="pkg:maven/com.samplecompany.app/app-test-proxy@2.36.19-SNAPSHOT?type=jar">
      <group>com.samplecompany.app</group>
      <name>app-test-proxy</name>
      <version>2.36.19-SNAPSHOT</version>
      <licenses/>
      <purl>pkg:maven/com.samplecompany.app/app-test-proxy@2.36.19-SNAPSHOT?type=jar</purl>
      <modified>false</modified>
    </component>
  </components>
  <externalReferences>
    <reference type="bom">
      <url>http://localhost:8070/ui/links/application/maven/report/33dfc2b66d6f41748f4f2b09cd3ba363</url>
      <comment>IQ Report</comment>
    </reference>
  </externalReferences>
  <dependencies>
    <dependency ref="pkg:maven/com.samplecompany.app/sample-app@2.36.19-SNAPSHOT?type=pom">
      <dependency ref="pkg:maven/com.samplecompany.app/app-test@2.36.19-SNAPSHOT?type=jar"/>
      <dependency ref="pkg:maven/com.samplecompany.app/app-test-proxy@2.36.19-SNAPSHOT?type=jar"/>
    </dependency>
    <dependency ref="pkg:maven/com.samplecompany.app/app-test@2.36.19-SNAPSHOT?type=jar"/>
    <dependency ref="pkg:maven/com.samplecompany.app/app-test-proxy@2.36.19-SNAPSHOT?type=jar">
      <dependency ref="pkg:maven/org.slf4j/jcl-over-slf4j@1.7.36?type=jar"/>
      <dependency ref="pkg:maven/org.apache.httpcomponents/httpclient@4.5.13?type=jar"/>
    </dependency>
    <dependency ref="pkg:maven/org.slf4j/jcl-over-slf4j@1.7.36?type=jar"/>
    <dependency ref="pkg:maven/org.apache.httpcomponents/httpclient@4.5.13?type=jar">
      <dependency ref="pkg:maven/org.apache.httpcomponents/httpcore@4.4.13?type=jar"/>
      <dependency ref="pkg:maven/commons-codec/commons-codec@1.15?type=jar"/>
    </dependency>
    <dependency ref="pkg:maven/org.apache.httpcomponents/httpcore@4.4.13?type=jar"/>
  </dependencies>
</bom>

Change history for CycloneDX REST API - v2 

Change

Release supported from 

Support for dependency graph in SBOMRelease 147
Support for JSON output format Release 134
Support for schema version 1.4Release 134
Support for schema version 1.3Release 117
Support for schema version 1.2Release 114
Discontinue use of API without specifying versionsRelease 114

Other Related Links:

CycloneDX Application Analysis