CycloneDx REST API - v2

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. It supports all component formats.

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, and 1.5.

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, 1.5 
"application/json"JSON1.2, 1.3, 1.4, 1.5 

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

curl -u admin:admin123 -X GET
http://localhost:8070/api/v2/cycloneDx/1.5/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.5/b7b2b2cc9c864ea59eb7fa0fb1d7f9ff/reports/bfdb562fad2443e593357b67eb4095e7 -H 'Accept: application/json'

c. Example to set accept type for output in XML format and generate a file:

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

Response

A file with filename format [prefix]-bom.[xml|json] will be created, if you have used the curl command with options -O -J (see example c above.)

Here is an example of XML response:

<bom xmlns="http://cyclonedx.org/schema/bom/1.5" 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.5" 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 or higher. 

<bom serialNumber="urn:uuid:4b31ae4b-926f-4973-bd34-aa9efa95cd8a" version="1" xmlns="http://cyclonedx.org/schema/bom/1.5">
  <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.

<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>

NEW IN RELEASE 154

The response now includes in the metadata section information about the IQ version used to generate the SBOM. Note that this is only available for CycloneDX version 1.2 or higher.

<bom serialNumber="urn:uuid:33dfc2b6-6d6f-4174-8f4f-2b09cd3ba363" version="1" xmlns="http://cyclonedx.org/schema/bom/1.5">
  <metadata>
    <timestamp>2023-02-05T16:50:51Z</timestamp>
    <tools>
      <tool>
        <vendor>Sonatype Inc.</vendor>
        <name>Nexus IQ Server</name>
        <version>1.154.0-01</version>
      </tool>
    </tools>
    <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>

Note: The dependency information reported by Sonatype

NEW IN RELEASE 163

There are cases where Sonatype Lifecycle generates a report (and may determine a dependency graph) of a scan policy evaluation even when no information is found about the containing project. For example if you scan an archive of binary components outside a project context. In such cases, the response includes a pre-defined parent component name as placeholder in the metadata section if the report does not contain any project data.

This component will include "sonatype" as the namespace and the name of the IQ application with prefix "iq_application_" along with the policy evaluation's "scanId" being the version. For example: 

<bom serialNumber="urn:uuid:33dfc2b6-6d6f-4174-8f4f-2b09cd3ba363" version="1" xmlns="http://cyclonedx.org/schema/bom/1.5">
  <metadata>
    <timestamp>2023-06-10T16:50:51Z</timestamp>
    <tools>
      <tool>
        <vendor>Sonatype Inc.</vendor>
        <name>Nexus IQ Server</name>
        <version>1.163.0-01</version>
      </tool>
    </tools>
    <component type="application" bom-ref="b18d79de-7878-42b4-8b0e-6254e109a7a2">
      <group>sonatype</group>
      <name>iq_application_sample-app</name>
      <version>272b82ee904a45e7a1de4299540a284a</version>
      <purl>pkg:generic/sonatype/iq_application_sample-app@272b82ee904a45e7a1de4299540a284a</purl>
    </component>
  </metadata>
...

NEW IN RELEASE 168

The response may include vulnerability analysis information in the SBOM. 

...
<analysis>
  <state>resolved_with_pedigree</state>
  <justification>requires_environment</justification>
  <responses>
    <response>workaround_available</response>
    <response>update</response>
  </responses>
  <detail>Analysis Detail</detail>
</analysis>
..


Change history for CycloneDX REST API - v2 

Change

Release supported from 

Support for schema version 1.5Release 170
Vulnerability section includies analysis sub-sectionRelease 168
Metadata includes a placeholder parent componentRelease 163
SBOM includes vendor and software nameRelease 154
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