Projects API
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 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\"}}"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>"