- Checkmarx Documentation
- Checkmarx One
- Checkmarx One API Documentation
- Checkmarx One API Endpoints
- Applications API
Applications API
Notice
A comprehensive Checkmarx One API Reference Guide is now available here.
Overview
An Application in Checkmarx One is a logical entity that represents a group of related Projects. This enables you to view aggregated data for all of the related Projects. The Application configuration includes defining “rules” that determine which Projects are associated with that Application. For example, you can assign all Projects that either have the tag “demo” or have “demo” as part of their name to a particular Application.
Note
Scanning is done on the Project level. Applications are only relevant for viewing scan results.
Projects are not required to be assigned to an Application.
You can perform all CRUD actions on Applications and Application “rules” via API.
Notice
You can create rules within the POST Application API call. It is not necessary to create rules separately using the Application rule APIs.
Applications URL
The URL for Applications endpoints is <base_url>/api/applications
US Environment - https://ast.checkmarx.net
US2 Environment - https://us.ast.checkmarx.net
EU Environment - https://eu.ast.checkmarx.net
EU2 Environment - https://eu-2.iam.checkmarx.net/
Australia & New Zealand – https://anz.ast.checkmarx.net
India - https://ind.ast.checkmarx.net
Singapore - https://sng.ast.checkmarx.net
Swagger
To view these APIs in the Swagger UI and run sample API calls, go to <base_url>/spec/v1/ and select Applications in the definition field.
US Environment - https://ast.checkmarx.net/spec/v1/
US2 Environment - https://us.ast.checkmarx.net/spec/v1/
EU Environment - https://eu.ast.checkmarx.net/spec/v1/
EU2 Envitonment - https://eu-2.ast.checkmarx.net/spec/v1/
Australia & New Zealand – https://anz.ast.checkmarx.net/spec/v1/
Singapore - https://sng.ast.checkmarx.net/spec/v1/
Authentication
Authentication for all Checkmarx One endpoints is done using JWT (JSON Web Token) access token. Access tokens are generated using the Authentication API.
Applications Endpoints Summary
API | Method | Endpoint | Description |
---|---|---|---|
Create an application | POST | /applications | Create a new Checkmarx One application, which is used for organizing projects. |
Get list of applications | GET | /applications | Get a list of all applications in your account. |
Get list of application tags | GET | /applications/tags | Get a list of all tags that have been applied to applications in your account. Tags can be simple strings or key:value pairs. |
Get application info | GET | /applications/{application_id} | Get detailed info about a particular application. |
Update an application | PUT | /applications/{application_id} | Update the configuration of a application. |
Delete an application | DELETE | /applications/{application_id} | Delete an application. |
Applications Rules Endpoints Summary
API | Method | Endpoint | Description |
---|---|---|---|
Create an application rule | POST | /applications/{application_id}/project-rules | Create a new rule for a particular application. |
Get list of application rules | GET | /applications/{application_id}/project-rules | Get a list of all rules for a particular application. |
Get info about an application rule | GET | /applications/{application_id}/project-rules/{rule_id} | Get info about a particular application rule. |
Update an application rule | PUT | /applications/{application_id}/project-rules/{rule_id} | Update the configuration of an application rule. |
Delete an application rule | DELETE | /applications/{application_id}/project-rules/{rule_id} | Delete an application rule. |
POST Applications
POST applications
is used to create a new Application.
When creating an Application, you specify one or more rules that define which Projects are associated with the Application. An OR operator is used, so that Projects that match any one of the rules are included in the Application.
Notice
It is possible to create a new Application without any rules, in which case no Projects will be assigned to the Application. Rules can be added later using PUT /api/applications/{id}
orPOST /api/applications/{id}/project-rules
.
Parameters
The POST method must be submitted with body parameters. Name is the only required parameter, the other parameters are optional.
Notice
A success response includes an Application ID which is used to refer to this Application in all subsequent API calls.
Parameter | Mandatory | Type | Enums | Description | Default |
---|---|---|---|---|---|
name | yes | string | - | The name that you would like to assign to the new Application. The Application name must be unique. | n/a |
description | no | string | - | A description of the Application. | none |
criticality | no | integer |
| The criticality level you would like to assign to the Application. | 3 - Medium |
rules[ ] | no | The rules that you would like to assign to the Application in order to designate which Projects are associated with the Application. An OR operator is used, so that Projects that match any one of the rules are included in the Application. | If no rules are specified, then the Application will be created as a “shell” which doesn’t have any Projects assigned to it. You can add rules at a later time. | ||
rules/type | no | string |
| The type of rule that is used to assign Projects to the Application. | none |
rules/value | no | string | - | The value of the rule (based on the rule type). For example, if the rule type is project.name.contains and the value is “demo”, then any Project with a name that contains the string “demo” will be included in this Application. TipKey-value pairs and lists of IDs should be separated by a semicolon. example:
| none |
tags | no | string | - | The tags that you want to assign to the Application. Tags need to be formatted in key-value pairs. example: "tags": {"Tag01": "", "Severity": "high"} | none |
Body Parameters Sample
{ "name": "DemoApp", "description": "An application created for showing API demo.", "criticality": 3, "rules": [ { "type": "project.name.contains", "value": "demo" } ], "tags": { "test": "", "priority": "high" } }
Sample cURL
curl -X POST "https://eu.ast.checkmarx.net/api/applications/" -H "accept: application/json; version=1.0" -H "Authorization: Bearer <token> -H "Content-Type: application/json; version=1.0" -d "{\"name\":\"DemoApp\",\"description\":\"An app created for showing API demo.\",\"criticality\":3,\"rules\":[{\"type\":\"project.name.contains\",\"value\":\"demo\"}],\"tags\":{\"test\":\"\",\"priority\":\"high\"}}"
Editing Applications and Application Rules
There are several methods that can be used to edit existing Applications. You can edit the Application settings such as name, description criticality etc. You can also add, remove and edit the rules that define which projects are included in the Application.
PUT applications/{applicationId}
is used to edit an existing Application. This enables you to adjust the Application settings as well as the rules. All exiting settings and rules are overwritten.POST applications/{applicationID}/project-rules
is used to add a new rule to an existing Application. All existing rules remain in place.PUT applications/{applicationID}/project-rules/{rule-id}
is used to edit a rule in an existing Application. All other rules remain in place.DELETE applications/{applicationID}/project-rules/{rule-id}
is used to delete a rule from an existing Application.
PUT applications/{application_id}
Use this method to edit the Application parameters and adjust the rules that define which Projects are associated with the Application.
Warning
When you update an application, all existing settings are overwritten.
Parameters
The ID of the Application that you would like to update is given as a path parameter. The body parameters are submitted in the same format as for the POST method.
Sample cURL
curl -X PUT "https://eu.ast.checkmarx.net/api/applications/e13b5d35-b64f-402e-8fbd-eaf1a495e3d0" -H "accept: */*" -H "Authorization: Bearer <token> -H "Content-Type: application/json; version=1.0" -d "{\"name\":\"DemoApp\",\"description\":\"An application created for showing API demo.\",\"criticality\":4,\"rules\":[{\"type\":\"project.name.contains\",\"value\":\"demo\"}],\"tags\":{\"test\":\"\",\"priority\":\"high\"}}"
POST applications/{application_id}/project-rules
Use this method to add a new rule to an existing Application. All existing rules remain in place.
Parameters
The ID of the Application to which you want to add the rule is given as a path parameter. The rule type and value are submitted as body parameters.
Sample cURL
curl -X POST "https://eu.ast.checkmarx.net/api/applications/c62ff150-ee56-4354-840b-b5b1cf1fb811/project-rules" -H "accept: application/json; version=1.0" -H "Authorization: Bearer <token> -H "Content-Type: application/json; version=1.0" -d "{\"type\":\"project.name.contains\",\"value\":\"dev\"}"
PUT applications/{application_id}/project-rules/{rule_id}
Use this method to edit a rule in an existing Application. All other rules remain in place.
Parameters
The ID of the Application for which you want to edit a rule and the ID of the rule are given as path parameters. The rule type and value are submitted as body parameters.
Sample cURL
curl -X PUT "https://eu.ast.checkmarx.net/api/applications/c62ff150-ee56-4354-840b-b5b1cf1fb811/project-rules/bbe2780c-a16b-4b06-b4f0-7ed1bbc95b66" -H "accept: application/json; version=1.0" -H "Authorization: Bearer <token> -H "Content-Type: application/json; version=1.0" -d "{\"type\":\"project.tag.key-value.exists\",\"value\":\"team;02\"}"
DELETE applications/{application_id}/project-rules/{rule_id}
Use this method to delete a rule from an existing Application.
Parameters
The ID of the Application for which you want to delete a rule and ID of the rule are given as path parameters. There is no body.
Sample cURL
curl -X DELETE "https://eu.ast.checkmarx.net/api/applications/c62ff150-ee56-4354-840b-b5b1cf1fb811/project-rules/a1fb20d8-fd7c-4fbc-ad45-3450f6a4cbf4" -H "accept: */*" -H "Authorization: Bearer <token>