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 isAPI
, and the key type for Notifications isSIEM
. - 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.API
to a custom role and assign that custom role to an OAuth App.
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.SIEM
to 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.
-
Request (application/json)
$ curl -H X-Auth-Token:ABCD/1234 \ https://defense.conferdeploy.net/integrationServices/v3/notification
-
Response 200 (application/json)
{ "notifications": [ { "policyAction": { "sha256Hash": "2552332222112552332222112552332222112552332222112552332222112552", "action": "TERMINATE", "reputation": "KNOWN_MALWARE", "applicationName": "firefox.exe" }, "type": "POLICY_ACTION", "eventTime": 1423163263482, "eventId": "EV1", "url": "http://carbonblack.com/ui#device/100/hash/2552332222112552332222112552332222112552332222112552332222112552/app/firefox.exe/keyword/terminate policy action", "deviceInfo": { "deviceType": "WINDOWS", "email": "tester@carbonblack.com", "deviceId": 100, "deviceName": "testers-pc", "deviceHostName": null, "deviceVersion": "7 SP1", "targetPriorityType": "HIGH", "targetPriorityCode": 0, "internalIpAddress": "55.33.22.11", "groupName": "Executives", "externalIpAddress": "255.233.222.211" }, "eventDescription": "Policy action 1", "ruleName": "Alert Rule 1" }, { "threatInfo": { "time": 1423163263501, "indicators": [ { "sha256Hash": "aafafafafafafafafafafafafafafafafafafa7347878", "indicatorName": "BUFFER_OVERFLOW", "applicationName": "chrome.exe" }, { "sha256Hash": "ddfdhjhjdfjdfjdhjfdjfhjdfhjdhfjdhfjdhfjdh7347878", "indicatorName": "INJECT_CODE", "applicationName": "firefox.exe" } ], "summary": "Threat Summary 23", "score": 8, "incidentId": "ABCDEF" }, "type": "THREAT", "eventTime": 1423163263501, "eventId": "EV2", "url": "http://carbonblack.com/ui#device/100/incident/ABCDEF", "deviceInfo": { "deviceType": "WINDOWS", "email": "tester@carbonblack.com", "deviceId": 100, "deviceName": "testers-pc", "deviceHostName": null, "deviceVersion": "7 SP1", "targetPriorityType": "HIGH", "targetPriorityCode": 0, "internalIpAddress": "55.33.22.11", "groupName": "Executives", "externalIpAddress": "255.233.222.211" }, "eventDescription": "time|Threat summary 23|score", "ruleName": "Alert Rule 2" } ], "message": "Success", "success": true }