Skip to main content

Checkmarx One API - Projects

Introduction

A Project in Checkmarx One is a logical entity that represents a source repository, such as a component, microservice, etc. which you intend to scan for vulnerabilities. Each time that you run a scan on the source repository you do so under the same Project, enabling you to track vulnerabilities in Checkmarx One throughout your SDLC. When you create a Project, you configure the Project settings, including specifying Groups for access control.

Note

When scanning from a zip archive, you must first create a Project in your account 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.

Projects can be assigned to Applications, together with other related Projects. This enables you to view aggregated data for all of the related Projects.

You can perform all CRUD actions on Projects via API.

Notice

Once you have created a Project you can run a scan of that Project using the Scan APIs.

Projects Endpoints

The URL for Projects endpoints is <base_url>/api/projects

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 Projects in the definition field.

Creating Projects (POST Projects)

The POST method must be submitted with body parameters. Name is the only required parameter, the other parameters are optional.

Notice

The success response includes a Project ID which is used to refer to this Project in all subsequent API calls.

Parameter

Mandatory

Type

Description

Default

name

yes

string

The name that you would like to assign to the new Project.

The Project name must be unique.

n/a

groups[ ]

no

string

The group IDs of Groups (of users) that you would like to assign to this Project. The ID of a Group can be found using the GET /auth/groups API.

A group must already exist in your account before a Project can be assigned to it. Only users assigned to the designated Groups will have access to this Project.

You can create a Group via the Checkmarx One web portal, see Managing Groups .

If no Group is specified, by default the Project will be accessible only to users with global permissions in your tenant account.

repoUrl

no

string

The Git repo URL.

none

mainBranch

no

string

The Git branch of the source code that is designated as “primary” for this Project.

By default, all actions on the Project such as viewing results will relate to the primary branch.

origin

no

string

The manner by which the Project was created.

none

tags

no

JSON object

The tags you want assigned to the Project.

Tags need to be formatted in key-value pairs.

example:

"tags": {"Tag01": "", "Severity": "high"}

none

Body Parameters Sample

{
  "name": "EliDemo03",
  "groups": [
    "TeamA"
  ],
  "repoUrl": "https://github.com/EliDemoProjects/dsvw",
  "mainBranch": "master",
  "origin": "API",
  "tags": {
    "demo": "",
    "priority": "high"
  }
}

Sample cURL

curl -X POST "https://eu.ast.checkmarx.net/api/projects/" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token> -d "{\"name\":\"EliDemo03\",\"groups\":[\"TeamA\"],\"repoUrl\":\"https://github.com/EliDemoProjects/dsvw\",\"mainBranch\":\"master\",\"origin\":\"API\",\"tags\":{\"demo\":\"\",\"priority\":\"high\"}}"

Getting Project Info (GET projects and GET projects/{id})

Gets general info for Projects in your account, including mapping of Project Name to Project ID.

You can get info for all Projects, or limit results by using pagination and or by filtering by various scan attributes such as Project ID, Project Name, tagse etc. See query parameters in the Swagger visualization above.

You can get info about a specific Project by including /{id} in the path parameters.

cURL Samples

Get all projects

curl -X GET "https://eu.ast.checkmarx.net/api/projects/?offset=0&limit=20" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>"

Get all projects that have the string “demo” in their name

curl -X GET "https://eu.ast.checkmarx.net/api/projects/?offset=0&limit=20&name=demo" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>"

Getting last scan info (GET projects/last-scan)

You can get info about the most recent scan of each Project in your account. This shows a mapping of the Project ID to Scan ID as well as info about the scan status, how it was initiated etc.

You can get info for all Projects, or limit results by using pagination and or by filtering by various scan attributes such as Project ID, Project Name, tagse etc. See query parameters in the Swagger visualization above.

You can also set filters for which scan is returned. For example, you can specify a specific Project and a specific branch, so that the last scan of that Project for that branch will be returned.

cURL Sample

curl -X GET "https://eu.ast.checkmarx.net/api/projects/last-scan?offset=0&limit=20&project-ids=d743c74c-5342-4864-b949-b67b6cf691a4&branch=branch2" -H  "accept: application/json; version=1.0" -H  "Authorization: Bearer <token>"