CycloneDx REST API - v2
NEW IN RELEASE 70
CycloneDX is a vendor agnostic, language/ecosystem independent specification for defining software components.
IQ Server CycloneDX API returns a CycloneDX SBOM document containing the components with its coordinates and licenses related to a scan report. This API method is available via a GET resource.
You may see limited information for formats other than Maven and NPM. Support for other formats will be increased as we develop this feature.
Step 1 - Get the Application ID
First, you will use the application’s public ID to retrieve the internal application ID. This is done using the following GET REST resource from our application API.
GET /api/v2/applications?publicId={YourPublicId}
Step 2 - Get SBOM
NEW IN RELEASE 114
Support for CycloneDX schema version 1.2 was added in release 114.
NEW IN RELEASE 117
Support for CycloneDX schema version 1.3 was added in release 117.
NEW IN RELEASE 134
Support for CycloneDX schema version 1.4 was added in release 134.
Support for output with a specific CycloneDX Version
Prior to IQ version 134 this API only include support for XML formatted outputs. As of version 134, this API supports CycloneDX XML and JSON formatted outputs. To get the correctly formated output you need to 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 |
"application/json" | JSON | 1.2, 1.3, 1.4 |
There are two ways to call the resource:
- By report id specifying the schema version
The possible values for the version are:
- 1.1
- 1.2
- 1.3
- 1.4
GET /api/v2/cycloneDx/{version}/{applicationInternalId}/reports/{reportId}
- By stage id specifying the schema version
The possible values for the version are:
- 1.1
- 1.2
- 1.3
- 1.4
The possible values for the stage id are:
-
build
-
stage-release
-
release
-
operate
When requesting by stage id, the result is from the latest application evaluation in that stage.
GET /api/v2/cycloneDx/{version}/{applicationInternalId}/stages/{stageId}
Response
You will receive a response containing a XML bom, you will see something like the following.
The response output will be in the version specified in the request : 1.1, 1.2, 1.3 or 1.4
<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>
Support for XML output with CycloneDX version 1.1
Starting from version 114, the paths bellow are deprecated and paths using CycloneDX versions should be used instead
There are two ways to call the resource:
- By report id:
GET /api/v2/cycloneDx/{applicationInternalId}/reports/{reportId}
- By stage id:
The possible values for the stage id are:
-
build
-
stage-release
-
release
-
operate
When requesting by stage id, the result is from the latest application evaluation in that stage.
GET /api/v2/cycloneDx/{applicationInternalId}/stages/{stageId}
-
Response
You will receive a response containing a XML bom, you will see something like the following.
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" 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>