- Checkmarx Documentation
- Checkmarx SCA
- Checkmarx SCA (REST) API Documentation
- Checkmarx SCA (REST) API - Export Service
Checkmarx SCA (REST) API - Export Service
Overview
This API enables you to export reports of the data identified by a Checkmarx SCA scan.
Currently, this API supports generating Software Bill of Materials (SBOM) reports. SBOMs can be generated in either CycloneDX v1.4 or SPDX v2.2 format. SPDX SBOMs are output in JSON format. For CycloneDX, there is an option to output the data as JSON or XML.
Note
Each API call generates a report in a single format. If you would like to generate reports in multiple formats, then you need to send a separate API call for each report.
Software Bill of Materials (SBOM), in simple words, is a list of all ingredients (i.e., components) of a software product. Just like you would check the ingredients of a food product before eating it, so too you should know what’s in your software before using it.
Checkmarx SCA leverages our existing infrastructure for identifying vulnerabilities as well as license and supply chain risks to supplement the standard SBOM info. This creates an SBOM that provides real insight into the risks associated with your 3rd party components.
This API enables creation of SBOMs in two popular formats:
CycloneDX - CycloneDX is a lightweight SBOM standard for application security contexts and supply chain component analysis, used primarily for OWASP compliance.
SPDX - SPDX is formed with the intent of creating a common data exchange format for information related to software packages for sharing and collection among developers.
Workflow
Create a project and run a scan. Take note of the
scanId
.Use
POST /export/requests
, specifying thescanId
, andfile-format
to generate a report. Take note of theexportId
.Use
GET /export/requests
, specifying theexportId
, to check the status of the report.Once the report is complete, use the
fileUrl
to download the report.
Base URL
US Environment - https://api-sca.checkmarx.net/export
EU Environment - https://eu.api-sca.checkmarx.net/export
Authentication
Authentication for all SCA endpoints is done using an access token. To learn how to generate an access token, see Checkmarx SCA (REST) API - POST Token.
Export Endpoints Summary
API | Method | Endpoint | Description |
---|---|---|---|
Create a report | POST | /requests | Generate a report for a specific scan by specifying the
|
Get report | GET | /requests | Check the status of a specific report, and once the report is completed, retrieve the Url to download the report. |
Get report formats | GET | /file-formats | Get a list of supported formats. |
POST Create a report
This endpoint is used to generate a report for a specific scan by specifying the scanId
and the desired report format.
Notice
The success response includes an exportId which is used to get the download URL.
Request Parameters
Body Parameters
The POST method must be submitted with the following body parameters.
Parameter | Mandatory | Type | Enum | Description |
---|---|---|---|---|
ScanId | yes | string | N/A | The unique identifier of the scan for which you would like to generate a report. |
FileFormat | yes | string |
| The format of the report. |
Body Parameters Sample
{ "ScanId": "fbd46412-0227-44ef-9feb-8464273a1234", "FileFormat": "CycloneDxJson" }
Query Parameters
You can add these optional flags to limit the results included in the SBOM.
Parameter | Type | Default | Description |
---|---|---|---|
hideDevAndTestDependencies | boolean | false | If you would like to exclude all development and test dependencies from the SBOM, set this flag as |
showOnlyEffectiveLicenses | boolean | false | If you would like to exclude all licenses that aren't marked as "Effective" from the SBOM, set this flag as |
cURL Sample
curl --location --request POST 'https://api.scacheckmarx.com/export/requests' \ --header 'Authorization: Bearer {TOKEN}' \ --header 'Content-Type: application/json' \ --data-raw '{ "ScanId": "fbd46412-0227-44ef-9feb-8464273a1234", "FileFormat": "CycloneDxXml"}'
Success Response
Code: 202
The response body consists of the exportId
of the report.
Response Sample
{ "exportId": "2d46cf11-a77c-4333-922a-b3bc33581234" }
GET report
This endpoint is used to check the status of a specific report. Once the report is completed, this endpoint also returns the Url to be used for downloading the report.
Request Parameters
The GET method must be submitted with the following body parameter.
Parameter | Mandatory | Type | Enum | Description |
---|---|---|---|---|
exportId | yes | string | N/A | The unique identifier of the report for which you would like to get the status and download link. |
Body Parameters Sample
{ "exportId": "2d46cf11-a77c-4333-922a-b3bc33581234" }
cURL Sample
curl --location --request GET 'https://api.scacheckmarx.com/export/requests?exportId=e537bcb0-e539-4a6b-9881-43cb2ea21234' \ --header 'Authorization: Bearer {TOKEN}'
Success Response
Code: 200
The response body consists of the following parameters.
Parameter | Type | Enum | Description |
---|---|---|---|
exportId | string | N/A | The unique identifier of the scan for which you would like to generate a report. |
exportStatus | string |
| The current status of the report generation. |
fileUrl | string | The URL for downloading the report. This parameter is only returned for reports that are in "Completed" status. |
Response Sample
{ "exportId": "2d46cf11-a77c-4333-922a-b3bc33586060", "exportStatus": "Completed", "fileUrl": "https://mysbom.json" }