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

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.

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

To comply with an audit trail, you must add 'cxOrigin=<request_origin>' to the cxOrigin header in the request (e.g. Media Type = cxOrigin: cx-jenkins').

Specifying the origin ensures 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).

The CxSAST service supports JSON format.

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

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

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

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 step is to make a request to the authentication server, 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 similar to the following:

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

The authorization server issues an access token response if the access token request is valid and authorized.

An example successful access token response:

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

If the request fails 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 similar to the following Postman example:

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

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 your token is invalid. You must re-authenticate using the access token request procedure in the CxSAST (REST) API.

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.