Latest Updates: CB ThreatHunter App for Splunk 1.0.0 Released

CB Defense API Authentication

API Key and Connector Id

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

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

X-Auth-Token: ABCD/1234 

How to obtain an API key and Connector Id

A CB Defense API Connector needs to be set up in CB Defense Dashboard app under the Settings/Connector menu option. This allows a company administrator to define a connector and get access to the apiKey and connectorId that will be required to authenticate the API request. In addition, administrator 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 connectors 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.

Blacklisting

We request that our customers honor the rate limits. If you or your application abuse the rate limits, the API key and or Organization will 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 connectorId or apiKey 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 March 31, 2017