Latest Updates: CB ThreatHunter App for Splunk 1.0.0 Released

CB Defense API Authentication

API Keys

PSC API Keys are used to authenticate API access. Users can view API Key settings within the PSC Console under Settings > API Keys.

API keys include two parts:

  • API Secret Key (previously API Key).
  • API ID (previously Connector ID).

Authentication is passed to the CB Defense API via the X-Auth-Token HTTP header. To generate the appropriate header, concatenate the API Secret Key with the API ID with a forward slash in between. For example, if the API Secret Key is ABCD and the API ID is 1234, the corresponding X-Auth-Token HTTP header will be:

X-Auth-Token: ABCD/1234

All API requests must be authenticated by using an API Secret Key and a API ID. Unauthenticated requests return an HTTP 401 error.

Note

Older versions of this document had “Connector” related terminology. This has now been updated to “API Key”.

  • The Connectors page has been renamed to API Keys.
  • Connector Type is now referred to as API Key Access Level.
  • The API Key button that revealed the secret key is renamed to Credentials and shows both the ID and the Key.

How to obtain an API Secret Key and API ID

  1. Log into your PSC Org
  2. Navigate to Settings > API Keys
  3. Click “Add API Key”
  4. Configure Name, Access level, etc.
  5. Obtain your API Secret Key and API ID pair

This allows a org administrator to define a API Key and get access to the API Secret Key and API ID that will be required to authenticate the API request. In addition, administrators can restrict use of this API key to a specific set of IP addresses for security reasons.

API Key Types

Currently there are three types of API keys available in the API Keys page. Each key type provides different access levels to API routes:

  1. API key type: provides access to all APIs except for the Notifications API and the Live Response API
  2. SIEM key type: provides access to the Notifications API
  3. Live Response key type: provides access to all APIs available to (1) above plus the Live Response API

Attempting to access an API not allowed by a given key type will result in an HTTP 401 Unauthorized error.

Rate Limiting

Rate limiting is done on a per API key basis. Rate limiting interval is 5 minutes: 25 API calls every 5 minutes.

When your request exceeds the rate limit for a given API key, the CB Defense API will return an HTTP 429 “Too Many Requests” response code.

If you expect a lot of use, consider caching the results in your application. This should reduce the possibility of being rate limited.

Current Enforcement

Rate limiting is currently not enforced. However, we do monitor excessive usage and can result in temporary enforcement of rate limiting.

Blacklisting

If you or your application abuse the rate limits, the API key and or Organization might be blacklisted. Once an API key or Organization is blacklisted, you will be unable to get a response from CB Defense API.

Response Codes

  • All successful API calls will return a HTTP status of 200 (OK).
  • If the request is not authorized the response status will be HTTP UNAUTHORIZED (status code 401). This can happen when the API Secret Key or API ID is invalid.
  • If request exceeds rate limit, HTTP response will be “Too many requests” (status code 429).
  • If the request is not valid in some manner, the response status will be HTTP BAD_REQUEST (status code 400).
  • Other HTTP error codes could be returned in some cases and the client may assume that the call failed for the associated HTTP status reason.
  • In addition, each message returns a boolean success indicator that indicates whether the operation was successful or not. The response contents should be further examined or processed only if the success indicator is true.
Last modified on May 7, 2019