Skip to main content

Reports API

Introduction

This API enables users to generate Reports with info about the applications, projects and scans in their account. The API can be used to generate the following types of reports:

  • Application List Report - gives a list of applications in your account, with detailed info about each application.

  • Project List Report - gives a list of projects in your account, with detailed info about each project.

  • Scan List Report - gives a list of scans run on a particular project, with detailed info about each scan.

  • Project Report - gives detailed info about a particular project, including aggregated statistics about the vulnerabilities detected in the project broken down by state, severity, technology etc..

  • Scan Report - gives detailed info about a particular scan of a project in your account, including info about the vulnerabilities detected by each of the scanners.

Reports can be generated in various formats (PDF, CSV, JSON), depending on the type of report being generated. Reports can be sent via email or downloaded using the download API.

Reports Endpoints

The URL for Reports Endpoints is <base_url>/api/reports

Authentication

Authentication for all Checkmarx One endpoints is done using JWT (JSON Web Token) access token. Access tokens are generated using the Authentication API.

Swagger

To view these APIs in the Swagger UI and run sample API calls, go to <base_url>/spec/v1/ and select Reports Api in the definition field. (For US environment click here.)

Endpoints Summary

API

Method

Endpoint

Desription

Create Report

POST

/api/reports

Generate a new report.

Report Status

GET

/api/reports/{reportId}

Check the status of a report.

Download Report

GET

/api/reports/{reportId}/download

Download a report that has been generated. The API redirects to the download URL and automatically initiates the download to your local machine.

Standard Workflow

To generate a report and download it:

  1. Use POST /api/reprts to generate a report, and record the Report ID that is returned.

  2. Use GET /api/{reportId}, specifying the Report ID of the desired report, to monitor the status of the report.

  3. Once the report is completed, use GET /{reportId}/download, specifying the Report ID of the desired report, to download the report.

POST Reports

Use POST /api/reports to generate a new report.

The POST method is submitted with a JSON payload that specifies the type of report being generated and the format of the report output. The parameters submitted in the payload differ depending on the type of report being generated. The following sections describe the request payload for each type of report.

A success response for this API returns a reportId which is used to download the report.

Application List Report

Request Parameters

Parameter

Mandatory

Type

Enums

Description

reportName

yes

string

  • application-list

The type of report being generated. This report gives a list of applications in your account, with detailed info about each application.

reportType

yes

string

  • cli

  • ui

  • email

Specifies how the report will be accessed. When the type is email, you will add the recipient's email in the data section and the report will be sent to that email.

fileFormat

yes

string

  • csv

The output format of the report.

Tip

For this type of report, only CSV is supported.

data

yes

JSON

There is no required data for this type of report. If reportType is email, then you need to submit the recipient's email in the data section.

Sample Payload

{
    "fileFormat": "csv",
    "reportType": "email",
    "reportName": "application-list",
     "data": {
         "email": [
         "[email protected]"
        ]
    }
}

Project List Report

Request Parameters

Parameter

Mandatory

Type

Enums

Description

reportName

yes

string

  • project-list

The type of report being generated. This type of report gives a list of projects in your account, with detailed info about each project..

reportType

yes

string

  • cli

  • ui

  • email

Specify how the report will be accessed. When the type is email, you will add the recipient's email in the data section and the report will be sent to that email.

fileFormat

yes

string

  • csv

The output format of the report.

Tip

For this type of report, only CSV is supported.

"data": {}

yes

JSON

There is no required data for this type of report. If reportType is email, then you need to submit the recipient's email in the data section.

Sample Payload

{
    "fileFormat": "csv",
    "reportType": "email",
    "reportName": "project-list",
    "data": {
         "email": [
         "[email protected]"
        ]
    }
}

Scan List Report

Request Parameters

Parameter

Mandatory

Type

Enums

Description

reportName

yes

string

  • scan-list

The type of report being generated. This type of report gives a list of scans run on a particular project, with detailed info about each scan.

reportType

yes

string

  • cli

  • ui

  • email

Specify how the report will be accessed. When the type is email, you will add the recipient's email in the data section and the report will be sent to that email.

fileFormat

yes

string

  • csv

The output format of the report.

Tip

For this type of report, only CSV is supported.

"data": {

projectId:

branchName:}

yes

JSON

For this type of report, the data section must include the projectId of the project for which you are getting the list of scans. If relevant, you can specify the branchName of the project branch. If reportType is email, then you need to submit the recipient's email in the data section.

Sample Payload

{
    "fileFormat": "csv",
    "reportType": "email",
    "reportName": "scan-list",
    "data": {
        "projectId": "5f45d9b3-cd3e-4bd8-9c5d-241831e1234",
        "branchName": "master",
         "email": [
         "[email protected]"
        ]
    }
}

Scan Report

Request Parameters

Parameter

Mandatory

Type

Enums

Description

reportName

yes

string

  • scan-report

The type of report being generated. This type of report gives gives detailed info about a particular scan of a project in your account, including info about the vulnerabilities detected by each of the scanners.

reportType

yes

string

  • cli

  • ui

  • email

Specify how the report will be accessed. When the type is email, you will add the recipient's email in the data section and the report will be sent to that email.

fileFormat

yes

string

  • pdf

  • json

The output format of the report.

Tip

For this type of report, only PDF and JSON are supported.

"data": {

}

A JSON object that contains the following parameters:

scanId

yes

string

The scan ID of the scan for which you would like to generate the report.

projectId

yes

stirng

The project ID of the project on which the scan was run.

branchName

no

string

The name of the branch on which the scan was run.

sections[]

no

string

  • ScanSummary

  • ExecutiveSummary

  • ScanResults

The sections to include in the report.

Default: All sections

scanners[]

no

string

  • SAST

  • SCA

  • KICS

If you included the ScanResults section, then you need to specify for which scanners scan results are included.

Default: All scanners

host

no

string

For internal Checkmarx use.

email[]

no

string

The emails of the report recipients.

Sample Payload

{
    "fileFormat": "pdf",
    "reportType": "email",
    "reportName": "scan-report",
    "data": {
        "scanId": "73ed25a6-3aa7-49c8-bcfd-967ec18a1234",
        "projectId": "74cdc5f1-2a35-4ca4-8894-112e62521234",
        "branchName": "dev2",
        "sections": [
            "ScanSummary",
            "ExecutiveSummary",
            "ScanResults"
        ],
        "scanners": [
            "SAST",
            "SCA",
            "KICS"
        ],
        "host": "",
        "email": [
            "[email protected]"
        ]
    }
}

Project Report

Request Parameters

Parameter

Mandatory

Type

Enums

Description

reportName

yes

string

  • project-report

The type of report being generated. This type of report gives gives detailed info about a particular project in your account, including aggregated statistics about the vulnerabilities identified in the project broken down by state, severity, technology etc.

reportType

yes

string

  • cli

  • ui

  • email

Specify how the report will be accessed. When the type is email, you will add the recipient's email in the data section and the report will be sent to that email.

fileFormat

yes

string

  • pdf

  • json

The output format of the report.

Tip

For this type of report, only PDF and JSON are supported.

resultsLimit

no

string

The max. number of results to return per scanner.

For PDF, Default: 100, Max.: 10,000

For other formats: Default: no limit

fromDate

yes

string

Specify the date from which data is be included in the report.

Format: YYYY-MM-DD

toDate

yes

string

Specify the date until which data is included in the report.

Format: YYYY-MM-DD

granularity

yes

string

  • all

  • daily

The degree of granularity of the results. This is relevant for metrics that are shown over time.

  • All - datapoints are shown for all scans.

  • Daily - datapoints are shown for one scan per day (last scan).

"data": {

}

A JSON object that contains the following parameters:

projectId

yes

string

The project ID of the project for which you are generating the report.

sections[]

no

string

  • ProjectInformation

  • TotalResultsOverview

  • ScanResultsOverview

  • TopTenVulnerableFiles

  • ResolvedVulnerabilitiesSeverity

  • ResolvedVulnerabilitiesScanner

  • ResultsTotalCombined

  • ResultsTotalByScanner

The sections to include in the report.

Default: All secions

email[]

no

string

The emails of the report recipients.

The emails of the report recipients.

Sample Payload

{
    "fileFormat": "pdf",
    "reportType": "email",
    "resultsLimit": 5000,
    "reportName": "project-report",
    "fromDate": "2022-09-05",
    "toDate": "2022-12-04",
    "granularity": "all",
    "data": {
        "projectId": "c3471c94-1beb-421b-869e-e8f3cf55ede1",
        "sections": [
            "ProjectInformation",
            "TotalResultsOverview",
            "ScanResultsOverview",
            "TopTenVulnerableFiles",
            "ResolvedVulnerabilitiesSeverity",
            "ResolvedVulnerabilitiesScanner",
            "ResultsTotalCombined",
            "ResultsTotalByScanner"
        ],
        "email": [
            "[email protected], [email protected]"
        ]
    }
}
In this section: