Checkmarx Go (REST) API - POST Scan

Title

POST Scans

Description

Creates a draft for a new scan. This sets up the framework for running the scan. However, the scan doesn’t actually run until you use POST Upload scan source source to submit the source file for scanning.

Each scan is created within an existing Project. You need to create a Project in your account, using the Checkmarx Go UI, before you can run scans via the API.

A success response for this API returns information about the scan, including a unique ID for accessing this scan in the system. It also returns “storage” information which specifies the storage location and authentication credentials that will be used for uploading the source file for this scan.

Workflow

  1. Use POST /scans to create a draft for a new scan within the specified Project.

  2. Use POST /upload scan source to submit the source file and run the scan.

  3. Use GET /scans{scan_id}/status to check the status of the scan.

  4. Use GET /scans{scan_id}/results to view the results of the scan.

Method

POST

URL

https://api.checkmarx.net/v1/scans

Curl Sample

curl -X POST "https://api.checkmarx.net/v1/scans" -H "accept: application/json" -H "Content-Type: application/json" -d "{"project_id": 8,"branch": "FeatureA","engine_types": ["SAST,SCA"],"tags": ["v1.2.0","Dept3"]}”

Media Type (header)

Authorization: Bearer <id_token value>
Accept: application/json

Parameters

Body Parameters

* indicates a required parameter

Parameter

Type

Enums

Description

Parameter

Type

Enums

Description

project_id*

integer

-

The unique identifier of the Project for which you would like to run the scan.

Note: the Project ID can be found in the Checkmarx Go UI.

branch*

string1

-

The branch of the Project for which you would like to run the scan.

Use GET Project Branches to view all existing branches for this Project.

Note: the default branch that is created for each new Project is “Main” (case sensitive).

You can create a new branch for this Project by entering a new branch name while submitting the POST scan request.

 

engine_types[]

 

string

  • SAST

  • SCA

The scan engine/s that that will run for the scan.

Note: if this parameter is not submitted then all available scans will run.

tags[]

string1

-

You can add tags to a scan. If the tag does not yet exist within this Project then a new tag is automatically created.

1 Branch and tag names in CxGo follows the GitHub naming restrictions. The precise logic for acceptable branch and tag names is defined as follows: /^(?!^@$)(?!\.)(?!-)(?!.*\/\.)(?!.*\.\.)(?!\/)(?!.*\/\/)(?!.*@\{)(?!.*\\)[^\040\177 ~^:?*[/]+(?:\/)?(?:[^\040\177 ~^:?*[/]+)?(?<!\.lock)(?<!\/)(?<!\.)$/

Success Response

Code: 201 Created

Attributes:

There are two sections in the response “scan” and “storage”.

The following attributes are shown under scan:

Attribute

Type

Enums

Description

Attribute

Type

Enums

Description

id

integer

-

The unique identifier of the scan.

Note: This value is automatically generated by Checkmard for your scan. Keep a record of this ID, as you will need to use it to check the status of the scan as well as to get the detailed results.

status

string

  • INITIALIZING - the scan has been created but a file hasn’t yet been uploaded for the scan.

  • STARTED - the file is being uploaded for the scan.

  • SCANNING - the scan is being executed.

  • COMPLETED - the scan has been successfully completed.

  • FAILED - the scan failed.

  • PARTIAL - one of the scan engines ran successfully and the other failed.

The status of the scan execution.

Note: When you run this command successfully, the status will be DRAFT until you run POST upload scan source.

progress

number

0-100

The percentage of the scan that has been executed.

Note: The progress will be “0” until you run POST upload scan source.

fail_code

string

Unexpected_Error

For a FAILED scan, the cause of the failure is shown.

engine_types[]

string

  • SAST

  • SCA

The scan engine/s used for the scan.

risk_level
(nullable)

string

  • LOW

  • MEDIUM

  • HIGH

These attributes show the extent of the vulnerabilities discovered by a COMPLETED scan.

Note: Values will be “null” since no vulnerabilities are detected until you run POST upload scan source.

high_severity
(nullable)

integer

-

medium_severity
(nullable)

integer

-

low_severity
(nullable)

integer

-

created_at

string

(date-time)

-

The date and time that the scan was created.

launched_at

string

(date-time)

-

The date and time that the scan began being processed.

Note: the scan isn’t launched until you run POST upload scan source.

allowed_to_delete

boolean

-

Indicates whether or not the scan can currently be deleted.

While the scan is in DRAFT status, the value is set as TRUE.

project_id

integer

-

The identifier of the Project for which the scan was run.

branch_name

string

-

The name of the Branch for which the scan was run.

application_id

integer

-

The identifier of the Application under which the scanned project is assigned.

business_unit_id

integer

-

The identifier of the Business Unit under which the scanned Project is assigned.

scanner_id

string

-

The CxGo internal ID of the user who submitted the scan.

tags[]

string

-

Tags that were assigned to the scan.

origin

integer

-

 

originName

string

  • API

  • WEB_PORTAL

Indicates how the scan was initiated, from the web portal (UI) or via API.

source_hash

string

-

A hashcode that represents the source code that was submitted for the scan. If two scans have an identical Hashcode, this indicates that the scan was run twice on the exact same source code.

The following attributes are shown under storage.

Attribute

Type

Description

Attribute

Type

Description

url

string

A unique URL to an S3 storage bucket that was designated by Checkmarx for uploading the source file for this scan.

fields

Shows the details of the AWS storage location and credentials that will be used to authenticate the HTTP POST request to upload the source file.

fields/key

string

A unique identifier for the storage location, generated by Checkmarx for this scan.

fields/bucket

string

The name of the bucket, designated by Checkmarx for this scan.

fields/X-Amz-Algorithm

string

The signing algorithm used to create the request signature.

fields/X-Amz-Credential

string

The credential scope value.

fields/X-Amz-Date

string

The date that is used to create the signature.

fields/X-Amz-Security-Token

string

The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS).

fields/Policy

string

The Base64-encoded security policy that describes what is permitted in the request.

fields/X-Amz-Signature

string

Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing key.

Sample Success Response:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 { "scan": { "id": 38, "status": "DRAFT", "progress": 0, "engine_types": [ "SAST" ], "risk_level": null, "high_severity": null, "medium_severity": null, "low_severity": null, "created_at": "2020-10-21T08:59:04.277Z", "launched_at": null, "allowed_to_delete": true, "project_id": 5, "branch_name": "main", "application_id": 7, "business_unit_id": 2, "scanner_id": "test820", "tags": [ "v1.2.0", "Dept3" ], "origin": 1, "originName": "API", "source_hash": "6f859d6302c2e25f6c0d3bd2382fd64e", }, "storage": { "url": "https://s3.amazonaws.com/cx-customers", "fields": { "key": "cx-customer-132/cx-project-5/SAST/cx-scan-38/sources.zip", "bucket": "cx-customers", "X-Amz-Algorithm": "AWS4-HMBC-SHF256", "X-Amz-Credential": "ASIAV4MVCDVCOGBH2WHU/20201022/us-east-1/s3/aws4_request", "X-Amz-Date": "20201021T085904Z", "X-Amz-Security-Token": "IQoJb3JpZ2luX2VfEEEaCXVzLWVhc3QtMSJGMEUCID4kBfLuz40ZlYNtW58r0vgCjZ/WZVauPk7Vj4x3ephiAiEBttUCodBzSNHcnzRIXQSEBNNgqD3d4ATWHS4GY+AuZmoq2QEIiv//////////ARABGgw0MDQ1Nzc1OTA1OTriDMiFOUmsLYZXLISQKwqtAU/4fNBQHp8gZrj2nybr9LebG1+V1ORCM2kszNPvs/XILHtcZ87XH/gRpR2AAmLO2hYOD4XklNkYuFPawZOdS0D+EjcQIj78/zTifUQ0hrNjqxk3USevrAkkNZ8xhq3DFJFEBtLvKEvdxDzEA1vD3AfuyUegHo0UJv2zGzhh2ADZFKbjIsyeUdhRJltN7yrLfByPcvdBVopiePD6jIN0ceX8F/4hXdDbNutqUbetMI6RxfwFOuABEo2HCYKatAgh3nk0Zv+iKgAfpbESioOswoxUq00Rddu76lbOjFUaNOzOtPA78GGvJjRdiWkWfFxjYiD+iyxztBbE4pGlzBltiOMRaV2CJx48cjZvBOwC9dVLJb8IbavydNG0OhywUqGLPg2z8WRSlb3a/cJlikRIcKWW+cryu1izhyccTLqNGIoUNLgkb8wNE8qorU/5HhzruXZoQQPmVcY6nGSOJfezCdxQjCXVeJL4EHFStEuDZW/GW7oHCjGttqUYql5Ky+R2YNejcV5wpxyQItVa1S/+b//Nt586fbo=", "Policy": "epJleHBpcmF0aW8uIjoiMjAlMC0xMC0yMlQwORo1OTowNFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbnd0aC1yYW5nZSIsMSwzMTQ1NzI4MDBdLHsia2V5IjoiY3ktY3VzdG9tZXItMTIyL2N4LXByb2plY3QtNy9TQVNUL2N4LXNjYW7tNDAvc291cmNlcy56aXAifSx7ImJ1Y2tldCI6ImN4LWN1c3RvbWVycyJ9LHsiWC1BbXotXWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsiWC1BbXotQ3JlZGVudGlhbCI6IkFTSUFWNE1WVURWQ1ZHQkgyWUhVLzIwMjAxMDIyL3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVlc3QifSx7IlgtQW16LURhdGUiOiIyMDIwMTAyMlQwODU5MDRaIn0seyJYLUFtei1TZWN1cml0eS1Ub2tlbiI6IklRb0piM0pwWjJsdVgyVmpFRUVhQ1hWekxXVmhjM1F0TVNKSE1FVUNJRDRrQmZMdXo0MFpsWU50VzU4cjB2Z0NqWi9XWlZhdVBrN1ZqNHgzZXBoaUFpRUF0dFVDb2RCelNOSGNuelJJWFFTRUJOTmdxRDNkNEFUV0hTM0dZK0F1RG1vcTJRRUlpdi8vLy8vLy8vLy9BUkFCR2d3ME1EUTFOemMxT1RBMU9UY2lETWlGT1Vtc0xZWlhMSVNRS3lxdEFVLzRmTkJRSHA4Z1pyajJueWJyOUxlYkcxK1YxT1JDTTJrc3pOUHZzL1hJTEh0Y1o4N1hIL2dScFIyQUFtTE8yaFlPRDRYa2xOa1l1RlBhd1pPZFMwRCtFamNRSWo3OC96VGlmVVEwaHJOanF4azNVU2V2ckFra05aOHhocTNERkpGRUJ0THZLRXZkeER6RUExdkQzQWZ1eVVlZ0hvMFVKdjJ6R3poaDJBRFpGS2JqSXN5ZVVkaFJKbHRON3lyTGZCeVBjdmRCVm9waWVQRDZqSU4wY2VYOEYvNGhYZERiTnV0cVViZXRNSTZSeGZ3Rk91QUJFbzJIQ1lLYXRBZ2gzbmswWnYraUtnQWZwYkVTaW9Pc3dveFVxMDBSZGR1NzZsYk9qRlVhTk96T3RQQTc4R0d2SmpSZGlXa1dmRnhqWWlEK2l5eHp0QmJFNHBHbHpCbHRpT01SYVYyQ0p4NDhjalp2Qk93QzlkVkxKYjhJYmF2eWRORzBPaHl3VXFHTFBnMno4V1JTbGIzYS9jSmxpa1JJY0tXVytjcnl1MWl6aHljY1RMcU5HSW9VTkxna2I4d05FOHFvclUvNUhoenJ1WFpvUVFQbVZjWTZuR1NPSmZlekNkeFFqQ1hWZUpMNEVIRlN0RXVEWlcvR1c3b0hDakd0dHFVWXFsNUt5K1IyWU5lamNWNXdweHlRSXRWYTFTLytiLy9OdDU4NmZibz0ifV19", "X-Amz-Signature": "374bade06d2fn12635c6az2b37485bf284d9b3c644fkk92d9edcc3a843979329" } } }

Error Responses:

Message: Engine types is a required field

Message: Engine types field must have at least 1 items

Message: Project id is a required field

Message: Project id must be a `number` type, but the final value was: `NaN` (cast from the value `NaN`)

Message: Unauthorized

Message: Project with id {projectId} not found

Message: Application with id {applicationId} not found

Message: Business Unit with id {businessUnitId} not found

Message: Method Not Allowed

Message: Internal Server Error