Skip to main content

Projects API

Notice

A comprehensive Checkmarx One API Reference Guide is now available here.

Overview

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 URL

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

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.

Authentication

Authentication for all Checkmarx One endpoints is done using JWT (JSON Web Token) access token. Access tokens are generated using the Authentication API.

Pagination

GET projects, last-scan and branches use pagination. By default they return the first 20 results. Use limit to adjust the maximum number of results to return and offset to specify the number of results to skip before starting to return results. You can use offset=0 and limit=0 to get all results.

Projects Endpoints Summary

API

Method

Endpoint

Description

Create a project

POST

/projects

Create a new Checkmarx One project.

Get list of projects

GET

/projects

Get a list of all projects in your account.

Get list of tags

GET

/projects/tags

Get a list of all tags that have been applied to projects in your account. Tags can be simple strings or key:value pairs.

Get last scan list

GET

/projects/last-scan

Get a list of the most recent scans of each project (based on applied filters), with the scan IDs mapped out to the corresponding project IDs.

Get list of branches

GET

/projects/branches

Get a list of all branches of a particular project.

Get project info

GET

/projects/{project_id}

Get detailed info about a particular project

Update a project

PUT

/projects/{project_id}

Update the configuration of a project.

Delete a project

DELETE

/projects/{project_id}

Delete a project.

POST Projects (Create a Project)

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": [
    "a9ec8d69-96a6-4079-9ea9-676f31537f68"
  ],
  "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\":[\"a9ec8d69-96a6-4079-9ea9-676f31537f68\"],\"repoUrl\":\"https://github.com/EliDemoProjects/dsvw\",\"mainBranch\":\"master\",\"origin\":\"API\",\"tags\":{\"demo\":\"\",\"priority\":\"high\"}}"

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>"

GET projects/last-scan (last scan info)

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>"