Skip to main content

Checkmarx One API - Scans

Introduction

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 Endpoints

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

Standard 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:

  1. Use POST /api/projects to generate a Project ID.

  2. Use POST /api/uploads to generate an upload link.

  3. Use PUT /{uploadLink} , specifying the path to your zip archive, to upload your file.

  4. Use POST /api/scans , specifying the Project ID and upload link, to scan the zip file.

  5. Use GET /api/scans/{scanId} to check the status of the scan.

  6. 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:

  1. Use POST /api/scans, specifying the Git repo URL and Project ID (optional) to scan the Project.

  2. Use GET /api/scans/{scanId} to check the status of the scan.

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

Running Scans (POST scans)

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.

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": "true",
                "presetName": "Checkmarx Default"
            }
        }
    ]
}
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-c4308ab2a67c","tags":{"projectTag":"","projectPriority":"high"}},"config":[{"type":"sast","value":{"incremental":"true","presetName":"Checkmarx Default"}}],"tags":{"scanTest":"","scanPriority":"high"}}"

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"
            }
        }
    ]
}
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":"true","presetName":"Checkmarx Default"}}]}"

Getting Scan Info (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": ""
    },
    {