Third-Party Analysis REST API
Third-Party Analysis REST API
Use the Third-Party Analysis REST API to perform an analysis of a software bill of materials (SBOM) for your application.
- The analysis is performed as an asynchronous request that can be monitored or as a fire-and-forget action.
- The analysis results include the Policy Actions as determined by the analysis stage.
- Users require the Evaluate Applications permission to call this API.
- When the same component is found more than once in the SBOM, only the data of the first component is processed.
Submit SBOM for evaluation
Use a POST request to submit the SBOM for evaluation.
POST /api/v2/scan/applications/{applicationId}/sources/{source}?stageId={stageId}
applicationInternalId: The internal ID for the application.
See the Application REST API to get the application's internal identifier.
stageId: the Lifecycle or SBOM Manager stage to run the analysis.
build, develop, stage-release, release, operate, compliance
source: specify the source of the SBOM file or the tool used to create it.
cyclonedx, spdx
- Adjust the request header's 'Content-Type' depending on when the file is in XML or JSON formats
-H "Content-Type: application/xml"
-H "Content-Type: application/json"
- The contents of SBOM may be embedded directly in the call or linked as an included file
--data "@/path/to/filename"
Example request with the XML file embedded:
curl -u admin:admin123 -X POST -H "Content-Type: application/xml" -d '<bom xmlns="http://cyclonedx.org/schema/bom/1.4" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"> <components> <component type="library"> <publisher>Apache</publisher> <group>org.apache.tomcat</group> <name>tomcat-catalina</name> <version>9.0.14</version> <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl> </component> </components> </bom>' 'http://localhost:8070/api/v2/scan/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/sources/cyclonedx'
Example request with the JSON file linked:
curl -u admin:admin123 -X POST -H "Content-Type: application/json" --data "@cyclonedx-bom.json" 'http://localhost:8070/api/v2/scan/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/sources/cyclonedx'
A successful POST will result in JSON formatted data confirming that the evaluation was submitted.
{ "statusUrl": "api/v2/scan/applications/a20bc16e83944595a94c2e36c1cd228e/status/9cee2b6366fc4d328edc318eae46b2cb" }
Checking the status URL to get the scan result
While the analysis is running, the status URL returned from the response may be used to check the status of the scan. This URL includes the application ID and the scan status ID.
GET /api/v2/scan/applications/{applicationInternalId}/status/{statusId}
Until the analysis is complete this endpoint will return a 404 status and the following message with your application ID and scan status ID.
Report with status id {statusId} for application with id {applicationInternalId} is not ready.
When the report is ready the response results in JSON response object containing an analysis summary.
{
"policyAction": "Failure",
"reportHtmlUrl": "ui/links/application/my-app/report/95c4c14e",
"reportPdfUrl": "ui/links/application/my-app/report/95c4c14e/pdf",
"reportDataUrl": "api/v2/applications/my-app/reports/95c4c14e/raw",
"embeddableReportHtmlUrl": "ui/links/application/my-app/report/95c4c14e/embeddable",
"isError": false,
"componentsAffected": {
"critical": 1,
"severe": 0,
"moderate": 0
},
"openPolicyViolations": {
"critical": 2,
"severe": 1,
"moderate": 0
},
"legacyViolations": 0
}
Error handling from the scan result endpoint
When the scan does not exist in the IQ server, the following message is returned with HTTP Status 404:
Policy evaluation status with id a20bc16e83944595a94c2e36c1cd228e for public application id cyclone was not found.
When there is an error while doing the scan:
{
"isError": true,
"errorMessage": "Unable to evaluate policy, the scan 123456783944595a94c2e36c1cd228e could not be processed."
}
When the Package URL is Not Available
The package URL is the most effective way to specify the exact component referenced in an application. When not available, the component coordinated and hash may be used to approximate the intended component.
Using the coordinates tags
A component can be specified using the coordinates tags. The name and version tags are required. The component may also include license data as shown in the following example:
<bom xmlns="http://cyclonedx.org/schema/bom/1.4" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1">
<components>
<component type="library">
<publisher>Apache</publisher>
<group>org.apache.tomcat</group>
<name>tomcat-catalina</name>
<version>9.0.14</version>
<licenses>
<license>
<id>Apache-2.0</id>
</license>
</licenses>
<purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl>
</component>
</components>
</bom>
Using the Content Hash (SHA-1)
A component can be specified using its content hash (SHA-1) along with its name and version:
<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
xmlns="http://cyclonedx.org/schema/bom/1.4">
<components>
<component type="library">
<name>tomcat-catalina</name>
<version>9.0.16</version>
<hashes>
<hash alg="SHA-1">e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
</hashes>
</component>
</components>
</bom>
Including CPE and SWID Tags
Components may include CPE and SWID tags to identify the component when a Package URL is not provided. These tags are preserved when included in the SBOM.
<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.4">
<components>
<component type="library">
<name>tomcat-catalina</name>
<version>9.0.14</version>
<hashes>
<hash alg="SHA-1">e7b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
</hashes>
<swid tagId="swidgen-242eb18a-503e-ca37-393b-cf156ef09691_9.0.14" name="Apache Tomcat" version="9.0.14">
<text content-type="text/xml" encoding="base64">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiID8+CjxTb2Z0d2FyZUlkZW50aXR5IHhtbDpsYW5nPSJFTiIgbmFtZT0iQWNtZSBBcHBsaWNhdGlvbiIgdmVyc2lvbj0iOS4xLjEiIAogdmVyc2lvblNjaGVtZT0ibXVsdGlwYXJ0bnVtZXJpYyIgCiB0YWdJZD0ic3dpZGdlbi1iNTk1MWFjOS00MmMwLWYzODItM2YxZS1iYzdhMmE0NDk3Y2JfOS4xLjEiIAogeG1sbnM9Imh0dHA6Ly9zdGFuZGFyZHMuaXNvLm9yZy9pc28vMTk3NzAvLTIvMjAxNS9zY2hlbWEueHNkIj4gCiB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIiAKIHhzaTpzY2hlbWFMb2NhdGlvbj0iaHR0cDovL3N0YW5kYXJkcy5pc28ub3JnL2lzby8xOTc3MC8tMi8yMDE1LWN1cnJlbnQvc2NoZW1hLnhzZCBzY2hlbWEueHNkIiA+CiAgPE1ldGEgZ2VuZXJhdG9yPSJTV0lEIFRhZyBPbmxpbmUgR2VuZXJhdG9yIHYwLjEiIC8+IAogIDxFbnRpdHkgbmFtZT0iQWNtZSwgSW5jLiIgcmVnaWQ9ImV4YW1wbGUuY29tIiByb2xlPSJ0YWdDcmVhdG9yIiAvPiAKPC9Tb2Z0d2FyZUlkZW50aXR5Pg==</text>
</swid>
</component>
<component type="library">
<name>log4j</name>
<version>2.12.2</version>
<hashes>
<hash alg="SHA-1">e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
</hashes>
<cpe>cpe:2.3:a:apache:log4j:2.12.2:rc1:*:en:*:*:*:*</cpe>
</component>
</components>
</bom>
Supported SBOM and Data Formats
| IQ Release | BOM Specification | Supported Formats |
|---|---|---|
| 77 | CycloneDX 1.1 | XML |
| 78 | XML | |
| 81 | license element support | XML |
| 114 | CycloneDX 1.2 | XML |
| 117 | CycloneDX 1.3 | XML |
| 134 | CycloneDX 1.4 | XML + JSON |
| 166 | SPDX 2.3 | XML + JSON |
| 170 | CycloneDX 1.5 | XML + JSON |
| 180 | CycloneDX 1.6 | XML + JSON |
| 192 | SPDX 2.2 | XML + JSON |
Warning
Support for CycloneDX vulnerability schema 1.0 XML extension is deprecated with BOM specification 1.4
Use the vulnerabilities type included with version 1.4
Examples of Valid SBOM Payload
Dependency graph and Innersource examples
Response when CycloneDX SBOM includes a dependency graph along with the parent component data in the metadata element, including dependency information and InnerSource insight data:
<bom xmlns="http://cyclonedx.org/schema/bom/1.4" version="1">
<metadata>
<component type="application" bom-ref="acme-app">
<name>Acme Application</name>
<version>9.1.1</version>
<purl>pkg:maven/org.acme/acme-app@9.1.1?type=jar</purl>
</component>
</metadata>
<components>
<component type="framework" bom-ref="pkg:maven/org.acme/web-framework@1.0.0?type=jar">
<group>org.acme</group>
<name>web-framework</name>
<version>1.0.0</version>
<purl>pkg:maven/org.acme/web-framework@1.0.0?type=jar</purl>
</component>
<component type="library" bom-ref="pkg:maven/org.acme/persistence@3.1.0?type=jar">
<group>org.acme</group>
<name>persistence</name>
<version>3.1.0</version>
<purl>pkg:maven/org.acme/persistence@3.1.0?type=jar</purl>
</component>
<component type="library" bom-ref="pkg:maven/org.acme/common-util@3.0.0?type=jar">
<group>org.acme</group>
<name>common-util</name>
<version>3.0.0</version>
<purl>pkg:maven/org.acme/common-util@3.0.0?type=jar</purl>
</component>
</components>
<dependencies>
<dependency ref="acme-app">
<dependency ref="pkg:maven/org.acme/web-framework@1.0.0?type=jar"/>
<dependency ref="pkg:maven/org.acme/persistence@3.1.0?type=jar"/>
</dependency>
<dependency ref="pkg:maven/org.acme/web-framework@1.0.0?type=jar">
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar"/>
</dependency>
<dependency ref="pkg:maven/org.acme/persistence@3.1.0?type=jar">
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar"/>
</dependency>
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar"/>
</dependencies>
</bom>
CycloneDX version 1.5 in XML format
<bom xmlns="http://cyclonedx.org/schema/bom/1.5" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1">
<metadata>
<component type="application" bom-ref="acme-app">
<name>Acme Application</name>
<version>9.1.1</version>
</component>
</metadata>
<components>
<component type="library">
<name>acme-library</name>
<version>1.0.0</version>
<hashes>
<hash alg="SHA-1">9188560f22e0b73070d2efce670c74af2bdf30af</hash>
<hash alg="SHA-256">d88bc4e70bfb34d18b5542136639acbb26a8ae2429aa1e47489332fb389cc964</hash>
</hashes>
<cpe>cpe:/a:acme:application:9.1.1</cpe>
</component>
<component type="library">
<group>com.fasterxml.jackson.core</group>
<name>jackson-databind</name>
<version>2.8.0</version>
<licenses>
<license>
<id>Apache-2.0</id>
</license>
</licenses>
<purl>pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar</purl>
</component>
</components>
<vulnerabilities>
<vulnerability>
<id>CVE-2018-7489</id>
<source>
<name>NVD</name>
<url>https://nvd.nist.gov/vuln/detail/CVE-2019-9997</url>
</source>
<ratings>
<rating>
<source>
<name>NVD</name>
<url>https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&version=3.0</url>
</source>
<score>9.8</score>
<severity>critical</severity>
<method>CVSSv3</method>
<vector>AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H</vector>
</rating>
</ratings>
<cwes>
<cwe>184</cwe>
<cwe>502</cwe>
</cwes>
<description>FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.</description>
<recommendation>Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.</recommendation>
<advisories>
<advisory>
<title>GitHub Commit</title>
<url>https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2</url>
</advisory>
</advisories>
<created>2021-01-01T00:00:00.000Z</created>
<published>2021-01-01T00:00:00.000Z</published>
<updated>2021-01-01T00:00:00.000Z</updated>
<analysis>
<state>not_affected</state>
<justification>code_not_reachable</justification>
<responses>
<response>will_not_fix</response>
<response>update</response>
</responses>
<detail>An optional explanation of why the application is not affected by the vulnerable component.</detail>
</analysis>
<affects>
<target>
<ref>pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar</ref>
</target>
</affects>
</vulnerability>
</vulnerabilities>
<dependencies>
<dependency ref="acme-app">
<dependency ref="pkg:maven/org.acme/web-framework@1.0.0?type=jar" />
<dependency ref="pkg:maven/org.acme/persistence@3.1.0?type=jar" />
</dependency>
<dependency ref="pkg:maven/org.acme/web-framework@1.0.0?type=jar">
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar" />
</dependency>
<dependency ref="pkg:maven/org.acme/persistence@3.1.0?type=jar">
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar" />
</dependency>
<dependency ref="pkg:maven/org.acme/common-util@3.0.0?type=jar" />
</dependencies>
</bom>
CycloneDX version 1.5 in JSON format
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"metadata": {
"timestamp": "2022-02-21T17:20:41Z",
"component": {
"name": "Acme Application",
"version": "9.1.1",
"type": "application",
"bom-ref": "acme-app"
}
},
"components": [\
{\
"name": "acme-library",\
"version": "1.0.0",\
"hashes": [\
{\
"alg": "SHA-1",\
"content": "9188560f22e0b73070d2efce670c74af2bdf30af"\
},\
{\
"alg": "SHA-256",\
"content": "d88bc4e70bfb34d18b5542136639acbb26a8ae2429aa1e47489332fb389cc964"\
}\
],\
"cpe": "cpe:/a:acme:application:9.1.1",\
"type": "library"\
},\
{\
"group": "com.fasterxml.jackson.core",\
"name": "jackson-databind",\
"version": "2.8.0",\
"licenses": [\
{\
"license": {\
"id": "Apache-2.0"\
}\
}\
],\
"purl": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar",\
"type": "library"\
}\
],
"dependencies": [\
{\
"ref": "acme-app",\
"dependsOn": [\
"pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"pkg:maven/org.acme/persistence@3.1.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/persistence@3.1.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/common-util@3.0.0?type=jar",\
"dependsOn": []\
}\
],
"vulnerabilities": [\
{\
"id": "CVE-2018-7489",\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln/detail/CVE-2019-9997"\
},\
"ratings": [\
{\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&version=3.0"\
},\
"score": 9.8,\
"severity": "critical",\
"method": "CVSSv3",\
"vector": "AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"\
}\
],\
"cwes": [\
184,\
502\
],\
"description": "FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.",\
"recommendation": "Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.",\
"advisories": [\
{\
"title": "GitHub Commit",\
"url": "https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2"\
}\
],\
"created": "2021-01-01T00:00:00Z",\
"published": "2021-01-01T00:00:00Z",\
"updated": "2021-01-01T00:00:00Z",\
"analysis": {\
"state": "not_affected",\
"justification": "code_not_reachable",\
"response": [\
"will_not_fix",\
"update"\
],\
"detail": "An optional explanation of why the application is not affected by the vulnerable component."\
},\
"affects": [\
{\
"ref": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar"\
}\
]\
}\
],\
"dependencies": [\
{\
"ref": "acme-app",\
"dependsOn": [\
"pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"pkg:maven/org.acme/persistence@3.1.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/persistence@3.1.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/common-util@3.0.0?type=jar",\
"dependsOn": []\
}\
],\
"vulnerabilities": [\
{\
"id": "CVE-2018-7489",\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln/detail/CVE-2019-9997"\
},\
"ratings": [\
{\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&version=3.0"\
},\
"score": 9.8,\
"severity": "critical",\
"method": "CVSSv3",\
"vector": "AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"\
}\
],\
"cwes": [\
184,\
502\
],\
"description": "FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.",\
"recommendation": "Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.",\
"advisories": [\
{\
"title": "GitHub Commit",\
"url": "https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2"\
}\
],\
"created": "2021-01-01T00:00:00Z",\
"published": "2021-01-01T00:00:00Z",\
"updated": "2021-01-01T00:00:00Z",\
"analysis": {\
"state": "not_affected",\
"justification": "code_not_reachable",\
"response": [\
"will_not_fix",\
"update"\
],\
"detail": "An optional explanation of why the application is not affected by the vulnerable component."\
},\
"affects": [\
{\
"ref": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar"\
}\
]\
}\
],\
"dependencies": [\
{\
"ref": "acme-app",\
"dependsOn": [\
"pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"pkg:maven/org.acme/persistence@3.1.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/web-framework@1.0.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/persistence@3.1.0?type=jar",\
"dependsOn": [\
"pkg:maven/org.acme/common-util@3.0.0?type=jar"\
]\
},\
{\
"ref": "pkg:maven/org.acme/common-util@3.0.0?type=jar",\
"dependsOn": []\
}\
],\
"vulnerabilities": [\
{\
"id": "CVE-2018-7489",\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln/detail/CVE-2019-9997"\
},\
"ratings": [\
{\
"source": {\
"name": "NVD",\
"url": "https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?vector=AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H&version=3.0"\
},\
"score": 9.8,\
"severity": "critical",\
"method": "CVSSv3",\
"vector": "AN/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"\
}\
],\
"cwes": [\
184,\
502\
],\
"description": "FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.",\
"recommendation": "Upgrade com.fasterxml.jackson.core:jackson-databind to version 2.6.7.5, 2.8.11.1, 2.9.5 or higher.",\
"advisories": [\
{\
"title": "GitHub Commit",\
"url": "https://github.com/FasterXML/jackson-databind/commit/6799f8f10cc78e9af6d443ed6982d00a13f2e7d2"\
}\
],\
"created": "2021-01-01T00:00:00Z",\
"published": "2021-01-01T00:00:00Z",\
"updated": "2021-01-01T00:00:00Z",\
"analysis": {\
"state": "not_affected",\
"justification": "code_not_reachable",\
"response": [\
"will_not_fix",\
"update"\
],\
"detail": "An optional explanation of why the application is not affected by the vulnerable component."\
},\
"affects": [\
{\
"ref": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.0?type=jar"\
}\
]\
}\
]
}