Checkmarx SCA (REST) API - POST Scan

Title

Post Scan

Description

Scan a previously uploaded ZIP file (or a GitHub file). The user specifies the Project ID and includes the previously generated Upload Link (or the GitHub file URL).

Method

POST

URL

US Environment - https://api-sca.checkmarx.net/api/scans
EU Environment - https://eu.api-sca.checkmarx.net/api/scans

Workflow

Notice

You need to have the Project ID of the project that you would like to scan in order to run the Scan Upload API. See Checkmarx SCA (REST) API - Projects.

To scan a zip file

Use POST /api/uploads to generate an upload link.
Use PUT {upload_url} , specifying the path to your ZIP file, 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 the Scan Reports API. Alternatively, you can view the results in the Checkmarx SCA web browser (UI), see Viewing Results.

To scan from GitHub repo

Use POST /api/scans (along with the Project ID and GitHub URL) to scan the Project.
Use GET /api/scans/{scanId} to check the status of the scan.
View the results using the Scan Reports API. Alternatively, you can view the results in the Checkmarx SCA web browser (UI), see Viewing Results.

Curl Sample

curl -X POST "https://api-sca.checkmarx.net/api/scans" -H "accept: application/json" -H "Authorization: Bearer <access_token>" -d "<json body>"
{
  "project" : {
    "id": "970d3dfa-4204-43c1-83f4-b3759f261234",
    "type": "upload",
    "handler": {
      "url": "https://uploads.sca.checkmarx.net/..."
    }
  }
}

Media Type (header)

Authorization: Bearer <access_token>

Accept: application/json

Parameters

Body Parameters

Required:

Parameter	Type	Enums	Description
project/id	string	-	The unique identifier of the Project.
project/type	string	git upload	The Type of Project being scanned, options are: “git” if the Project source code is located in a Git repository. “upload” if the Project source code is stored locally in a zip file.
project/handler/url	string	-	The Git url, or the `upload_url` that was generated by the `POST Generate Upload Link` request.

Sample Body Parameter Code (Git URL)

{
  "project" : {
    "id": "e7a64af1-1525-4ecb-b657-28131f471bf4",
    "type": "git",
    "handler": {
      "url": "https://github.com/OWASP/WebGoat.NET"
    }
  }
}

Sample Body Parameter Code (ZIP file)

{
  "project" : {
    "id": "f6ce5e79-ef06-4125-af3b-af848d62e847",
    "type": "upload",
    "handler": {
      "url": "{{uploadUrl}}"
    }
  }
}

Success Response

Code: 201 Created

Attributes:

Attribute	Type	Enums	Description
id	string	-	The unique identifier of the scan that was just initiated.
status	string	Created	The current status of the scan.
created	string (date-time)	-	The date and time the scan was initiated.
updated	string (date-time)	-	The date and time that the scan was last updated.
userAgent (nullable)	string	-	The user or Agent that initiated the scan.
initiator (nullable)	string	-	The intiator of the scan.
tags (nullable)	string	-	Tags that are associated with this scan.

Sample Success Response

{
    "id": "e326b56e -a2d1-4b92-bb43-3a55b5ecbb79",
    "status": "Created",
    "created": "2021-04-13T09:22:20.6846407+00:00",
    "updated": "0001-01-01T00:00:00",
    "userAgent": null,
    "initiator": null,
    "tags": null
}

Error Response

In this section: