Skip to main content

CycloneDX REST API

This API 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. Retrieve the internal application identifier and then pass it as an input parameter to get the SBOM report.

Step 1 - Get the internal application ID

Use the Application REST API with the application’s public ID (user-created) to retrieve the application's internal ID.

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

Step 2 - Retrieve the SBOM with the application ID

The returned version of the supported CycloneDX schema is required when requesting an SBOM. Possible values for the version are:

1.1, 1.2, 1.3, 1.4, 1.5, 1.6

The API can retrieve the SBOM based on the latest evaluation by instead passing the stage ID in the GET method.

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

Possible values for the stage ID are:

build, stage-release, release, operate

Optionally retrieve a specific report using the report ID

To retrieve a report that is not the latest scan, you may use the identifier for the specific report. Use the Report REST APIs to find the required report ID.

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

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 Type

Output Format

Supported CycloneDX Schema Versions

"application/xml"

XML

1.1, 1.2, 1.3, 1.4, 1.5, 1.6

"application/json"

JSON

1.2, 1.3, 1.4, 1.5, 1.6

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>

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>

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>

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>

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

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

The response may include vulnerability analysis information in the SBOM.

Note

Information under the vulnerability analysis section will appear if it originally existed in the SBOM that was scanned for the same stage. If it did not exist, you can add the vulnerability analysis section in the original SBOM using the Vulnerability Analysis Details REST API.

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

The response may include Common Platform Enumeration (CPE) and Software Identification (SWID) details, but only if they were present in the original SBOM scanned for that stage.

"cpe": "cpe:/a:acme:application:9.1.1",
"swid": {
    "tagId": "swidgen-242eb18a-503e-ca37-393b-cf156ef09691_9.1.1",
    "name": "Acme Application",
    "version": "9.1.1",
    "tagVersion": 0,
    "patch": false,
    "text": {
        "encoding": "base64",
        "contentType": "text/xml",
        "content": "PD94bWwgdmVyc"
    }
}

The response includes the field occurrences for every component. This is available for CycloneDX version 1.5 or higher.

...
<components>
...
  <component type="library" bom-ref="7e161007-1f0f-467a-8dad-fc4701e90302">
    <group>org.springframework.boot</group>
    <name>spring-boot-autoconfigure</name>
    <version>2.0.3.RELEASE</version>
    <licenses>
      <license>
          <id>Apache-2.0</id>
      </license>
    </licenses>
    <purl>pkg:maven/org.springframework.boot/spring-boot-autoconfigure@2.0.3.RELEASE?type=jar</purl>
    <modified>false</modified>
    <properties>
      <property name="Sonatype truncated SHA1">011bc4cc96b08fabad2b</property>
      <property name="Match State">exact</property>
      <property name="Identification Source">Sonatype</property>
    </properties>
    <evidence>
      <occurrences>
        <occurrence>
          <location>MySampleApp-1.war/WEB-INF/lib/spring-boot-autoconfigure-2.0.3.RELEASE.jar</location>
        </occurrence>
      </occurrences>
    </evidence>
  </component>
  ...
</components>
...

Change history for CycloneDX REST API

Change

Release supported from

Added support for CycloneDX version 1.6

The components section includes the field occurrences

Support for Common Platform Enumeration (CPE) and Software Identification (SWID) fields

Support for schema version 1.5

Vulnerability section includes analysis sub-section

Metadata includes a placeholder parent component

SBOM includes vendor and software name

Support for dependency graph in SBOM

Support for JSON output format

Support for schema version 1.4

Support for schema version 1.3

Release 117

Support for schema version 1.2

Release 114

Discontinue use of API without specifying versions

Release 114