Skip to main content

Checkmarx SCA (REST) API - Export Service

Warning

This API replaces the /risk-report API that had been used previously for generating scan reports and SBOMs. The /risk-report API will be deprecated soon.

Notice

This API is supported both for Checkmarx One and SCA standalone accounts.

Overview

This API enables you to export reports of the data identified by a Checkmarx SCA scan. This includes detailed info about the open source packages in your project and the risks associated with them. This API can be used to generate the following types of reports:

  • Scan Report - shows an overview of the security of your project as well as specific vulnerabilities, legal risks, and outdated versions identified by the scan. Scan Reports can be generated in JSON, XML, PDF or CSV format.

  • Software Bill of Materials (SBOM) - SBOMs can be generated in either CycloneDX v1.5 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.

  • Remediated Manifest File - A replacement manifest file that contains the recommended versions for each of your packages. You can download the remediated manifest file and use it to update your project. This feature is currently supported only for npm manifest files and this remediation method is relevant only for direct dependencies.

    Warning

    If you update the dependency versions, your code may require some refactoring because of some possible functionality changes.

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.

Export Service URLs

Checkmarx One

The following base URLs are used for these APIs, depending on your environment:

  • US Environment - https://ast.checkmarx.net/api/sca/export

  • US2 Environment - https://us.ast.checkmarx.net/api/sca/export

  • EU Environment - https://eu.ast.checkmarx.net/api/sca/export

  • EU2 Environment - https://eu-2.ast.checkmarx.net/api/sca/export

  • DEU Environment - https://deu.ast.checkmarx.net/api/sca/export

  • Australia & New Zealand – https://anz.ast.checkmarx.net/api/sca/export

  • India - https://ind.ast.checkmarx.net/api/sca/export

  • Singapore - https://sng.ast.checkmarx.net/api/sca/export

  • UAE - https://mea.ast.checkmarx.net/api/sca/export

Checkmarx SCA Standalone

  • US Environment - https://api-sca.checkmarx.net/export

  • EU Environment - https://eu.api-sca.checkmarx.net/export

Workflow

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

  2. Use POST /requests, specifying the scanId, and fileFormat to generate a report. Take note of the exportId.

  3. Use GET /requests, specifying the exportId as a query parameter, to check the status of the report and to get the fileUrl for downloading the file.

  4. Once the report is complete, use the fileUrl to download the report.

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 fileFormat. Currently supported formats are:

  • CycloneDxJson

  • CycloneDxXml

  • SpdxJson

  • RemediatedPackagesJson

  • ScanReportJson

  • ScanReportXml

  • ScanReportCsv

  • ScanReportPdf

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 check the status and get the download URL.

Request Parameters

Body Parameters

The POST method must be submitted with the following body parameters.

Parameter

Mandatory

Type

Default

Enum/Comments

Description

ScanId

yes

string

N/A

N/A

The unique identifier of the scan for which you would like to generate a report.

FileFormat

yes

string

N/A

  • CycloneDxJson

  • CycloneDxXml

  • SpdxJson

  • RemediatedPackagesJson

  • ScanReportJson

  • ScanReportXml

  • ScanReportCsv

  • ScanReportPdf

The format of the report.

ExportParameters/

hideDevAndTestDependencies

no

boolean

false

If you would like to exclude all development and test dependencies from the SBOM, set this flag as true.. Default: false

ExportParameters/

showOnlyEffectiveLicenses

no

boolean

false

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

ExportParameters/excludePackages

no

boolean

false

Relevant only for scan reports

ExportParameters/excludeLicenses

no

boolean

false

Relevant only for scan reports

ExportParameters/excludeVulnerabilities

no

boolean

false

Relevant only for scan reports

ExportParameters/excludePolicies

no

boolean

false

Relevant only for scan reports

ExportParameters/filePaths[]

Required for report type RemediatedPackagesJson

string

Relevant only for RemediatedPackagesJson reports.

Comma separated list of paths to manifest files that will be remediated. Paths are relative to the repo folder.

ExportParameters/compressedOutput

no

boolean

false

If set as true, the output will always be returned in a zip archive.

If false (default), then if there is a single filepath the output will be returned as a json.

Notice

If there are multiple filepaths, then the output is always returned as a zip archive, even if this parameter is set as false.

SBOM Body Parameters Sample
{
    "ScanId": "2b43b0f5-5080-4224-af24-8325d33d4676",
    "FileFormat": "cycloneDxJson",
    "ExportParameters": {
        "hideDevAndTestDependencies": true,
        "showOnlyEffectiveLicenses": false
    }
}
Scan Report Body Parameters Sample
{
  "ScanId": "e8576978-88f1-4c64-af8a-2b37f94d9e4b",
  "FileFormat": "ScanReportPdf",
  "ExportParameters": {
    "hideDevAndTestDependencies": false,
    "showOnlyEffectiveLicenses": false,
    "excludePackages": false,
    "excludeLicenses": true,
    "excludeVulnerabilities": false,
    "excludePolicies": true
  }
}
Remediated Packages Body Parameters Sample
{
  "ScanId": "e8576978-88f1-4c64-af8a-2b37f94d9e4b",
  "FileFormat": "remediatePackagesJson",
  "ExportParameters": {
    "filePaths": [juice-shop-master/frontend/package.json, juice-shop-master/package.json]
  }
}

cURL Sample

curl --location 'https://api-sca.checkmarx.net/export/requests' \
--header 'Cx-Authentication-Type: service' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer  someToken' \
--data '{
  "ScanId":
  "2b43b0f5-5080-4224-af24-8325d33d4676",
  "FileFormat": "cycloneDxJson",
      "ExportParameters": {               
           "hideDevAndTestDependencies": true,
            "showOnlyEffectiveLicenses": false
    }
}'

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 Query Parameters

The GET method must be submitted with the following query 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.

cURL Sample

curl --location --request GET 'https://api-sca.checkmarx.net/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: