Skip to main content

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.

Workflow

  1. Create a project and run a scan. Take note of the scanId.

  2. Use POST /export/requests, specifying the scanId, and file-format to generate a report. Take note of the exportId.

  3. Use GET /export/requests, specifying the exportId, to check the status of the report.

  4. 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 scanId and the file-format. Currently supported formats are:

  • CycloneDxJson

  • CycloneDxXml

  • SpdxJson

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

  • CycloneDxJson

  • CycloneDxXml

  • SpdxJson

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

showOnlyEffectiveLicenses

boolean

false

If you would like to exclude all licenses that aren't marked as "Effective" from the SBOM, set this flag as true.

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

  • Pending

  • Exporting

  • Completed

  • Failed

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"
}
In this section: