Using the CxSAST (REST) API (v8.6.0 and up)

General Points

In this part of the documentation, we will use the words “CxSAST service” to refer to the base address of the REST service. For CxSAST, this URL can be found on the /<server-name/ip>:<port>/cxrestapi path, relative to the platform hostname (http://<host name>:<port>/cxrestapi).

Unless stated otherwise, all addresses in the rest of this documentation are relative to the CxSAST service, apart from when requesting an access token for authentication.

Versioning and Media Type

The CxSAST is installed with the latest version (i.e. v=1.0) of the CxSAST (REST) API. In order to use another version of the CxSAST (REST) API you will need to add ';v=<version>' to a media type header in the request. The media type header defined will depend on the request method used:

• GET Request – Accept: application/json;v=1.0
• POST, PUT, PATCH and DELETE Requests – Content-Type: application/json;v=1.0

Origin

In order to be compliant with an audit trail, you will need to add 'cxOrigin=<request_origin>' to the cxOrigin header in the request (e.g. Media Type = cxOrigin: cx-jenkins').

Specifying the origin ensures that all CxSAST (REST) API requests are logged to the audit trail with their original source. Not specifying the origin will automatically apply the default origin (i.e. other).

Format

The CxSAST service supports json format.

Testing

We will use authentication and request submission in Postman for most of the CxSAST (REST) API testing examples.

Authentication

An authenticated user can be granted access to restricted sets of data and benefit from extended quotas for API calls. The CxSAST (REST) API features an authentication mechanism for users to be granted their specific authorizations.

To complete the authentication procedure you need to know the following basic fundamentals:

• The basics of using REST APIs, e.g. requests, responses, headers
• The basics of using CxSAST

We will use access token-based authentication in Postman for this example.

Step 1: Requesting an access token for authentication

You need to receive an access token for authentication. The first thing you need to do is make a request to the authentication server by including the credentials received from the authorization server.

To do this, just submit (POST) the desired credentials to the token endpoint using the application/x-www-form-urlencoded format in the request body:

• Endpoint example: http://<server-name/ip>:<port>/cxrestapi/auth/identity/connect/token
• Credentials example:
  • username: <Cx username>
  • password: <Cx password>
  • grant_type: Value must be set as 'password'
  • scope: Value must be set as 'sast_rest_api’
  • client_id: Value must be set as 'resource_owner_client'
  • client_secret: Value must be set as '014DF517-39D1-4453-B7B3-9930C563627C'

The access token request will look some similar to the following:

This creates a login session and returns the requested access token response information, which will look similar to the following:

If the access token request is valid and authorized, the authorization server issues an access token response.

An example successful access token response:

   {
     "access_token": "eyJ0eXAiOiJKV1QiLCJhbGtr0hoV4Vj8GNkyk2A…………..",
     "expires_in": 3600,
     "token_type": "Bearer"
   }  

If the request failed client authentication or is invalid, the authentication server returns an access token error response.

An example access token error response:

   {
     "error":"invalid_grant"
   }

This error means that the provided authorization grant is invalid, expired, revoked or issued to another client. For more examples of errors with responses, see the Error Responses.

Step 2: Using the access token in a request to the resource server

When you want to make a request to the resource server, you should send the access token (access_token) received during authentication.

To do this, just submit (GET) the access token value to the resource in the request header:

• Resource example: http://<server-name/ip>:<port>/cxrestapi/projects
• Credentials example:
  • Authorization: Bearer <access token value>
  • Accept: application/json;v=1.0

The session request will look some similar to the following Postman example:

Now, when you submit the request, this access token value is used for authentication, until the token expires.

Token Expiration

If you have not used the CxSAST (REST) API for a while, you need to perform the authentication again because your token has expired. You will receive an error response. The response body will contain a message telling you that your token is invalid. At this point, you will need to re-authenticate using the access token request procedure in the CxSAST (REST) API.

Authorization Errors

In case of an error the authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following error with responses:

error – A single error code with one of the following:

• invalid_request – The request is missing a required parameter, includes an unsupported parameter, repeats a parameter or includes multiple credentials
• invalid_client – Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)
• invalid_grant – The provided authorization grant is invalid, expired, revoked or was issued to another client
• unauthorized_client – The authenticated client is not authorized to use this authorization grant type
• unsupported_grant_type – The authorization grant type is not supported by the authorization server
• invalid_scope – The requested scope is invalid, unknown or malformed.

Authentication Log

The authentication log can be found in the WebAPIAll file (<directory>:\Program Files\Checkmarx\Logs\WebAPI\Trace). The following is an example of the log:

2017-11-02 09:33:02,331 [19] INFO - Start token request
2017-11-02 09:33:02,331 [19] INFO - Secret id found: resource_owner_client
2017-11-02 09:33:02,347 [19] INFO - Client validation success
2017-11-02 09:33:02,347 [19] INFO - Start token request validation
2017-11-02 09:33:02,347 [19] INFO - Start password token request validation
2017-11-02 09:33:02,362 [19] INFO - REST login: Login Ended successfully. Username: 203186009069174177246150222065055136232142232254
2017-11-02 09:33:02,362 [19] INFO - Password token request validation success.
2017-11-02 09:33:02,362 [19] INFO - Token request validation success
{
  "ClientId": "resource_owner_client",
  "ClientName": "Cx Resource Owner Client",
  "GrantType": "password",
  "Scopes": "sast_rest_api",
  "UserName": "<username>",
  "AuthenticationContextReferenceClasses": [],
  "Raw": {
    "username": "<username>",
    "password": "******",
    "grant_type": "password",
    "scope": "sast_rest_api",
    "client_id": "resource_owner_client",
    "client_secret": "******"
  }
}
2017-11-02 09:33:02,362 [19] INFO - Creating token response
2017-11-02 09:33:02,362 [19] INFO - Processing token request
2017-11-02 09:33:02,768 [19] INFO - End token request
2017-11-02 09:33:02,768 [19] INFO - Returning token response.