Scans API

Overview

Checkmarx One scans identify vulnerabilities in your source code. You can specify which scanners to run for each scan (SAST, SCA, KICS). Each scan is run on a Project (a logical entity representing a source code repository).

The scans endpoints enable you to run scans, get info about scan that have run in your account and check their status. You can also cancel delete scans.

Scans URL

The URL for Scans Endpoints is <base_url>/api/scans

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 Scans in the definition field. (For US environment click here.)

Workflow

The following are examples of standard workflows for using the scans APIs together with other Checkmarx One APIs to run scans and retrieve scan results.

Notice

When scanning from a zip archive, you must first create a Project in your account using the the Checkmarx One web portal or the POST /api/projects API before you can run the scan.
When scanning from a Git repository, there is an option of running a scan without a preconfigured Project. In this case, a Project is automatically generated and it is given the name of the repo.

To scan source code from a zip archive:

Use POST /api/projects to generate a Project ID.
Use POST /api/uploads to generate an upload link.
Use PUT /{uploadLink} , specifying the path to your zip archive, to upload your file.
Use POST /api/scans , specifying the Project ID and upload link, to scan the zip file.
Use GET /api/scans/{scanId} to check the status of the scan.
View the results using GET /api/results, specifying the Scan ID. Alternatively, you can view the results in the Checkmarx One web application (UI), see Scan Results.

To scan from a Git repo:

Use POST /api/scans, specifying the Git repo URL and Project ID (optional) to scan the Project.
Use GET /api/scans/{scanId} to check the status of the scan.
View the results using GET /api/results, specifying the Scan ID. Alternatively, you can view the results in the Checkmarx One web application (UI), see Scan Results.

Scans Endpoints Summary

API	Method	Endpoint	Description
Run scan	POST	/scans	Run a scan from a zip archive or Git repo.
Get scans	GET	/scans	Get a list of scans, with detailed information about each scan. You can limit the results by using pagination and/or setting filters.
Get tags	GET	/scans/tags	Get a list of all scan tags used in your account. Tags can be simple strings or key:value pairs.
Get scan status summary	GET	/scans/summary	Get a summary of the status of the scans in your account.
Get templates	GET	/scans/templates	Get the list of the available config-as-code template files that are under the dedicated directory.
Get template file	GET	/scans/templates/{file-name}	Get a config-as-code template file. Example: '/templates/config.yml'
Get scan details	GET	/scans/{id}	Get details about a specific scan, including the current status of the scan.
Cancel a scan	PATCH	/scans/{id}
Delete a scan	DELETE	/scans/{id}	Delete a scan.
Get scan workflow	GET	/scans/{id}	Get a detailed workflow, listing the tasks performed for a specific scan.

POST Scans (Running a scan)

Use POST /api/scans to initiate a new scan. You can scan source code either from a zip archive or from a Git repo.

A success response for this API returns information about the scan, including a unique Scan ID which you will use to identify the scan for all API calls relating to the scan.

Scan Process

When a scan is run using multiple scanners, all scanners run in parallel.

When multiple scans are run in your account, the number of concurrent scans is specified in your account's license. This info is available under Account Settings > License > License Plan Summary. When the limit is exceeded, the scans are added to a queue which runs on a "first in first out" basis.

Prerequisites

In order to run a scan from a zip archive, you need to have:

Project ID
Upload link to the location where you uploaded the zip archive

In order to run a scan from a Git repo, you need to have:

The URL of the repo
Credentials for accessing the repo (if it isn’t public)

Request Parameters

The POST method is submitted with the following body parameters:

Notice

This table gives a high level explanation of the request. For a description of the request parameters, see the descriptions in the Swagger visualization above.

Parameter	Mandatory	Type	Enums	Description	Default
type	yes	string	`upload` `git`	The type of the scan. Options are: “upload” if the source code is stored locally in a zip archive. “git” if the source code is located in a Git repository.	n/a
handler	yes	JSON object	n/a	The handler gives info about how the source code is being accessed. The attributes differ depending on the type of scan (upload or git).	n/a
project (not required for git type scans)	yes	JSON object	n/a	Information about the Project on which the scan is being run.	n/a
config	no	JSON object	n/a	The configuration settings for running the scan. This includes which scanners will run as well as specific info about how the scan will run.	If no config is submitted, an incremental sast scan will run using the Checkmarx Default preset.
tags	no	JSON object	n/a	A list of tags associated with the project in key-value format.

Upload (zip) Scan Sample

Request body

{
    "project": {
        "id": "ee79f633-1ce1-4f0f-80e8-39cca31f8243"
    },
    "type": "upload",
    "handler": {
        "uploadurl": "https://master.cxast.com/storage/uploads.master.cxast.com-eu-west-1-94135634443184/2021_05_11_06_23_19.385?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ast%2F2064343554311%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20210513454319Z&X-Amz-Expires=86400&X-Amz-Signature=b0e305be6b4cst645trw84&X-Amz-SignedHeaders=host"
    },
    "tags": {
        "ScanTag01": "",
        "ScanSeverity": "high"
    },
    "config": [ { "type": "sast",

                   "value": { "incremental": "false", "presetName": "Checkmarx Default", "engineVerbose": "false" }

                },

                {"type": "sca",

                   "value": { "lastSastScanTime": "", "exploitablePath": "false" }

                },

                {"type": "kics",

                   "value": { "filter": "", "platforms": "" }

                },
                {"type": "apisec","value": {}
                }     
  ]
}

cURL

curl -X POST "https://ast.checkmarx.net/api/scans/" -H  "accept: application/json; version=1.0" -H  "Content-Type: application/json; version=1.0" -d "{"type":"upload","handler":{"uploadurl":"https://<your_unique_upload_url>"},"project":{"id":"773c4f28-c048-4633-afb9-c4308ab21234","tags":{"projectTag":"","projectPriority":"high"}},"config":[{"type": "sast","value": {"incremental": "false","presetName": "Checkmarx Default","engineVerbose": "false"}},{"type": "sca","value": {"lastSastScanTime": "","exploitablePath": "false"}},{"type": "kics","value": {"filter": "","platforms": ""}},{"type": "apisec","value": {}}]"

Git Scan Sample

Request body

{
    "project": {
        "id": "e6c83787-1e5c-4348-aaed-560797b60bad"
    },
    "type": "git",
    "handler": {
        "repoUrl": "https://github.com/CheckmarxDev/ast-github-action",
        "branch": "master",
        "credentials": {
            "username": "",
            "type": "apiKey",
            "value": "1234567890qwrtyuiopasdfghjkl;zxcvbnm,./"
        }
    },
    "tags": {
        "ScanTag01": "",
        "ScanSeverity": "high"
    },
    "config": [ { "type": "sast",

                   "value": { "incremental": "false", "presetName": "Checkmarx Default", "engineVerbose": "false" }

                },

                {"type": "sca",

                   "value": { "lastSastScanTime": "", "exploitablePath": "false" }

                },

                {"type": "kics",

                   "value": { "filter": "", "platforms": "" }

                },
                {"type": "apisec","value": {}
                }     
  ]
}

cURL

curl -X POST "https://ast.checkmarx.net/api/scans/" -H  "accept: application/json; version=1.0" -H  "Content-Type: application/json; version=1.0" -d "{"project":{"id":"ee79f633-1ce1-4f0f-80e8-39cca31f8243"},"type":"upload","handler":{"uploadurl":"https://<your_unique_upload_url>"},"tags":{"ScanTag01":"","ScanSeverity":"high"},"config":[{"type": "sast","value": {"incremental": "false","presetName": "Checkmarx Default","engineVerbose": "false"}},{"type": "sca","value": {"lastSastScanTime": "","exploitablePath": "false"}},{"type": "kics","value": {"filter": "","platforms": ""}},{"type": "apisec","value": {}}]}"

GET Scans

Gets general info for scans in your account, including status.

Notice

To get complete scan results (i.e., vulnerabilities that were identified) use GET /api/results

You can limit results by using pagination and or by filtering by various scan attributes such as scan ID, status, fromdate etc. You can also specify how the results are sorted (e.g., created at, name, user agent etc.). See query parameters in the Swagger visualization above.

Curl Samples

Get all scans

curl -X GET "https://eu.ast.checkmarx.net/api/scans/?statuses=&sort=" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>phdGlvbiIsImF1ZCI6WyJyZWFsbS1tYW5hZ2VtZW50IiwiYWNjb3VudCJdLCJzdWIiOiIxODgzMTUxZS03MjliLTQxNDgtOGNiZS1jNzE5NTAxYTM0NGQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhc3QtYXBwIiwic2Vzc2lvbl9zdGF0ZSI6IjY3ZDBkOTYyLTNkYTYtNDliYS1hMTA5LTU2N2UwYTYxMTU1ZiIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiKiIsIi8qIl0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbInZpZXctcmVhbG0iLCJ2aWV3LWlkZW50aXR5LXByb3ZpZGVycyIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwicmVhbG0tYWRtaW4iLCJjcmVhdGUtY2xpZW50IiwibWFuYWdlLXVzZXJzIiwicXVlcnktcmVhbG1zIiwidW1hX3Byb3RlY3Rpb24iLCJ2aWV3LWF1dGhvcml6YXRpb24iLCJxdWVyeS1jbGllbnRzIiwicXVlcnktdXNlcnMiLCJtYW5hZ2UtZXZlbnRzIiwibWFuYWdlLXJlYWxtIiwidmlldy1ldmVudHMiLCJ2aWV3LXVzZXJzIiwidmlldy1jbGllbnRzIiwibWFuYWdlLWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtY2xpZW50cyIsInF1ZXJ5LWdyb3VwcyJdfX0sInNjb3BlIjoiaWFtLWFwaSBwcm9maWxlIGVtYWlsIGFzdC1hcGkgZ3JvdXBzIHJvbGVzIiwic2lkIjoiNjdkMGQ5NjItM2RhNi00OWJhLWExMDktNTY3ZTBhNjExNTVmIiwidGVuYW50X2lkIjoiZXUuaWFtLmNoZWNrbWFyeC5uZXQ6Om9yZyIsInRlbmFudF9uYW1lIjoib3JnYW5pemF0aW9uIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJyb2xlcyI6WyJyZWFsbS1vd25lciIsIm1hbmFnZS11c2VycyIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJ1c2VyIiwiaWFtLWFkbWluIiwiY3JlYXRlLWFwaS1rZXlzIl0sInJvbGVzX2FzdCI6WyJjcmVhdGUtcHJvamVjdCIsInZpZXctcHJvamVjdHMiLCJ1cGRhdGUtcmVzdWx0IiwiZGVsZXRlLWFwcGxpY2F0aW9uIiwiZGVsZXRlLXdlYmhvb2siLCJjcmVhdGUtd2ViaG9vayIsInVwZGF0ZS1zY2FuIiwidmlldy13ZWJob29rcyIsImRlbGV0ZS1xdWVyeSIsInZpZXctcHJvamVjdC1wYXJhbXMiLCJkZWxldGUtcHJvamVjdCIsImRlbGV0ZS1wb29sIiwidmlldy1wb29scyIsImNyZWF0ZS1wb29sIiwidmlldy1lbmdpbmXigItzIiwidmlldy1hcHBsaWNhdGlvbnMiLCJ1cGRhdGUtYXBwbGljYXRpb24iLCJ1cGRhdGUtdGVuYW50LXBhcmFtcyIsInZpZXctcXVlcmllcyIsInZpZXctbGljZW5zZSIsInVwZGF0ZS1wcm9qZWN0LXBhcmFtcyIsIm9yZGVyLXNlcnZpY2VzIiwidXBkYXRlLXBvb2wiLCJjcmVhdGUtYXBwbGljYXRpb24iLCJ2aWV3LXRlbmFudC1wYXJhbXMiLCJ2aWV3LXJlc3VsdHMiLCJ1cGRhdGUtcXVlcnkiLCJ1cGRhdGUtcmVzdWx0LW5vdC1leHBsb2l0YWJsZSIsInZpZXctc2NhbnMiLCJhc3QtYWRtaW4iLCJjcmVhdGUtc2NhbiIsInVwZGF0ZS1wcm9qZWN0IiwiZGVsZXRlLXNjYW4iLCJjcmVhdGUtcXVlcnkiLCJ1cGRhdGUtd2ViaG9vayJdLCJncm91cHMiOltdLCJncm91cHNOYW1lcyI6W10sInByZWZlcnJlZF91c2VybmFtZSI6Im9yZ19hZG1pbiIsInRlbmFudCI6Im9yZ2FuaXphdGlvbiJ9.XH2ju-SUCMA6WXxDoA0_xZuiJcqtK_oiMDFDq-ecTPHyZZVYRUYtkabRpmekO6m7PSAqDsDStdBBXGuca6Inu4QkENRzCXi7FUF4JPWIFGQAqSg6AJnz2HVXb_M5pRX4BN7jSRtKmkFV-CRtpFT4KbgY0Kbx8kWdSf-l0KXQO4Dz0M2Kxda0NXHQ18ESnZpeLClotTCjzmGHl7GgC-vkFuGphiL70o8AZwWS4QU8nl_BMh5oVjUjQmOnM69T6wWHA2slLPWtEJ2t6LYkMpq0R7E7lumM83WXrSSPv-yjO-C15EVPm5EgLcqaG341FhtahqJ51uaQVYb7d05UCl6-8Q"

Get completed scans, sorted by name

curl -X GET "https://eu.ast.checkmarx.net/api/scans/?statuses=Completed&sort=%2Bname" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>

Get scans for a specific project

curl -X GET "https://eu.ast.checkmarx.net/api/scans/?statuses=&project-id=79153bb1-cceb-40fd-afeb-97932732b39e&sort=" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>

Success Response

The success response returns the total number of scans in your account and the number of scans returned by the API based on the filters that you applied. It also returns an array containing results for each scan, including the scan ID as well as info about the status, run info, handler, tags and metadata. For a description of the response parameters, see the Swagger visualization above.

Sample Success Response:

{
  "totalCount": 168,
  "filteredTotalCount": 152,
  "scans": [
    {
      "id": "1885f9bc-8a44-4606-b13b-97855faf7c70",
      "status": "Completed",
      "branch": ".unknown",
      "createdAt": "2021-08-18T14:52:52.827603Z",
      "updatedAt": "2021-08-18T14:55:27.147132Z",
      "projectId": "d5867c48-1221-4c72-ae1b-0e4d57f1911c",
      "projectName": "yuris-test",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36",
      "initiator": "org_admin",
      "tags": {},
      "metadata": {
        "id": "1885f9bc-8a44-4606-b13b-97855faf7c70",
        "type": "upload",
        "Handler": {
          "UploadHandler": {
            "branch": ".unknown",
            "upload_url": "https://eu.ast.checkmarx.net/storage/uploads.eu.ast.checkmarx.net-eu-west-1-602005780816/2021_08_18_14_52_34.146?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ast%2F20210818%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20210818T145234Z&X-Amz-Expires=86400&X-Amz-Signature=b0a6ef139cd65c515c9dcc968632370097b519fb9030a9b32a7e7eb6357ff745&X-Amz-SignedHeaders=host"
          }
        },
        "configs": [
          {
            "type": "sast",
            "value": {
              "presetName": "Checkmarx Default",
              "incremental": "false"
            }
          },
          {
            "type": "sca"
          },
          {
            "type": "kics"
          }
        ],
        "project": {
          "id": "d5867c48-1221-4c72-ae1b-0e4d57f1911c"
        },
        "created_at": {
          "nanos": 779707053,
          "seconds": 1629298372
        }
      },
      "engines": null,
      "sourceType": "",
      "sourceOrigin": ""
    },
    {

In this section:

Scans API

Overview

Scans URL

Authentication

Swagger

Workflow

Notice

Scans Endpoints Summary

POST Scans (Running a scan)

Scan Process

Prerequisites

Request Parameters

Notice

Upload (zip) Scan Sample

Request body

cURL

Git Scan Sample

Request body

cURL

GET Scans

Notice

Curl Samples

Success Response

Sample Success Response:

Search results