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 TypeOutput FormatSupported CycloneDX Schema Versions
"application/xml"XML1.1, 1.2, 1.3, 1.4 
"application/json"JSON1.2, 1.3, 1.4 

There are two ways to call the resource:

  1. 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}
  2. 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
  3. 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:

  1. By report id: 
    GET /api/v2/cycloneDx/{applicationInternalId}/reports/{reportId}
  2. 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>