Skip to main content

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

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.

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

  • 1 - None

  • 2 - Low

  • 3 - Medium

  • 4 - High

  • 5 - Critical

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

  • project.name.starts-with - Assign Projects with a name starting with the specified character(s). (case sensitive)

  • project.tag.key.exists - Assign Projects with the specified tag (key component). (case sensitive)

  • project.name.in - Assign Projects with the specified name. (case sensitive)

  • project.tag.value.exists - Assign Projects with the specified tag (value component). (case sensitive)

  • project.tag.key-value.exists - Assign Projects with the specified tag (key-value component). (case sensitive)

  • project.name.contains - Assign Projects whose name contains the specified string. (Not case sensitive)

  • project.name.regex - Assign Projects whose name matches the specified Regular Expression. (case sensitive)

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.

Tip

Key-value pairs and lists of IDs should be separated by a semicolon.

example:

{

"type": "project.tag.key-value.exists",

"value": "level;medium"

}

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>
In this section: