Endpoint Standard REST API

Carbon Black Cloud Endpoint Standard is the new name for the product formerly called CB Defense.

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

API Key: Authentication is handled by an API Secret Key and API ID, which are generated from the API Access page of the Carbon Black Cloud console. The API Secret Key and API ID are concatenated together to form the X-Auth-Token HTTP header, which is used to control access to the API. When generating the API keys, you will select a key type from the dropdown. The key type for Audit Log Events is API, and the key type for Notifications is SIEM.
Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
API Route: /integrationServices/v3/

Pagination

Most APIs are paginated so that large result sets can be returned to your API client in chunks. Every paginated API has the same standard request and response template.

When using a paginated API, the request includes two optional query parameters: start and rows. The start query parameter indicates the first row number that the API client expects from the result, and rows indicates the maximum number of rows that the API client expects in the response. Note that the maximum value of the rows parameter can be limited on the Endpoint Standard server side. The start value is based on a one-index. To retrieve the first 10 results of a result set, use start=1&rows=10.

The response payload also includes a totalResults value that indicates the total number of objects that matched the query.

Response Codes

HTTP 200: Successful response
HTTP 400: Bad request. Check the messages response for more information on errors encountered parsing the incoming payload.
HTTP 401: Unauthorized. Double check the X-Auth-Token authentication HTTP header to make sure that the Connector ID and API key are valid.
HTTP 404: Object not found. The requested object could not be found in the backend data store, or it may have expired (over 30 days old, etc.)
HTTP 429: Rate limiting encountered. Try again in a minute.
HTTP 500: Internal server error. Check the messages response for more information.
In addition, each message returns a boolean success indicator that indicates whether the operation was successful. The response contents should be further examined or processed only if the success indicator is true.

Audit Log Events

Retrieves all new audit log notifications matching the input search criteria. Response is a list of events in JSON format, sorted by time in ascending order (oldest notification first). Once a notification is viewed/ingested, it is cleared and will not be included in future responses to this API request.

Required Key Type - API

If using Carbon Black Cloud identity management, choose the key type “API” when creating the API Key.
If using VMware Cloud Services Platform for identity management, assign the permission _ConnectorType.APIto a custom role and assign that custom role to an OAuth App.

Note: This API is not available in the AWS GovCloud (US) environment. Audit Logs can be exported from the Carbon Black Cloud console.

Get Audit Log Events

GET /integrationServices/v3/auditlogs

The response will include various types of notifications such as:

Log in attempts by users
Updates to connectors
Creation of connectors
LiveResponse events

Example Request & Response:

Request (application/json)

  $ curl -H X-Auth-Token:ABCD/1234 \
  "https://defense.conferdeploy.net/integrationServices/v3/auditlogs"

Response 200 (application/json)

{
    "notifications": [
        {
            "requestUrl": null,
            "eventTime": 1529332687006,
            "eventId": "37075c01730511e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.3",
            "verbose": false,
            "description": "Logged in successfully"
        },
        {
            "requestUrl": null,
            "eventTime": 1529332689528,
            "eventId": "38882fa2730511e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.3",
            "verbose": false,
            "description": "Logged in successfully"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345346615,
            "eventId": "b0be64fd732211e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.1",
            "verbose": false,
            "description": "Updated connector jason-splunk-test with api key Y8JNJZFBDRUJ2ZSM"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345352229,
            "eventId": "b41705e7732211e8bd7e5fdbf9c916a3",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.2",
            "verbose": false,
            "description": "Updated connector Training with api key GRJSDHRR8YVRML3Q"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345371514,
            "eventId": "bf95ae38732211e8bd7e5fdbf9c916a3",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.2",
            "verbose": false,
            "description": "Logged in successfully"
        }
    ],
    "success": true,
    "message": "Success"
}

Notifications

Notifications API allows consumers to get alert and policy action notifications that a connector is subscribed to.

Required Key Type - SIEM

If using Carbon Black Cloud identity management, choose the key type “SIEM” when creating the API Key.
If using VMware Cloud Services Platform for identity management, assign the permission _ConnectorType.SIEMto a custom role and assign that custom role to an OAuth App.

Note: Only CB Analytics and Watchlist alert notifications can be retrieved through the notifications API.
Note: This API is not available in the AWS GovCloud (US) environment. Instead, we recommend the Data Forwarder or Alerts API.

New integrations should use one of the following to receive all available data:

Data (Event) Forwarder to stream alerts or events to your own S3 bucket, where you can control retention
Alerts v6 API to search up to 180 days of historical alert data

Get Notifications

GET /integrationServices/v3/notification

Get new notifications since last checkin. The connector must be subscribed to at least one notification rule to get notifications.

Note that once a notification has been delivered, it will not be delivered again. There is also a retention limit of seven days for notifications via this endpoint. Any notifications not consumed within seven days will no longer be available. Customers using this endpoint must poll frequently enough to retrieve their notifications within that window, or utilize one of the other mechanisms available to retrieve this data:

Use the Data Forwarder to stream alerts or events to your own S3 bucket, where you can control retention.
Use the Alerts v6 API to search up to 180 days of historical alert data.

The API key associated with the request to the Notifications API must be of the “SIEM” type - “API” key types will return a HTTP 401 Unauthorized when attempting to access the notifications API.

Every SIEM key type can be subscribed to a different set of notifications in the product. Therefore, each SIEM key type will have a different “view” of the notifications available. Each SIEM key is considered separate from the others, and even if both are subscribed to the same set of notifications, the notifications will be delivered to both – retrieving a notification from one SIEM key will not automatically “remove” it from the view of the other SIEM key.