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 an Access Level type from the dropdown.
  • The Access Level type for Audit Log Events is Custom (recommended), or API (deprecated).
  • The Access Level type for Notifications is SIEM. This route is deprecated and integrations should be updated using this Migration Guide
  • 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 since the last time the call was made with the same API Key ID. The 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.

In June 2023, the Audit Log API was updated to accept an API key of type Custom, in addition to the (now deprecated) type API.

When you change to a new API key, the queue for reading audit logs will begin three days earlier. This may lead to duplicate data if Audit Log ingest was previously active with a different API key.

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/integrationServices/v3/auditlogs

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Audit Logs > View and Export Audits > org.audits, allow permission to READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/integrationServices/v3/auditlogs

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Alerts:org.audits, allow permission to READ

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.audits READ Majority of environments
VMware Cloud Services Platform _API.Audits:org.audits:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

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

Deprecated Access Level Type

  • If using Carbon Black Cloud identity management, choose the Access Level “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.

Get Audit Log Events

The response will include various types of notifications such as:

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

Request 
GET {cbc-hostname}/integrationServices/v3/auditlogs

Response Codes

Code Description Content-Type Content
200 Audit Logs correctly retrieved application/json See example below.
401 User is not Authenticated application\json 
{ "success": false,
  "message": "User is not authenticated" 
}

Examples

Request 
GET https://defense.conferdeploy.net/integrationServices/v3/auditlogs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "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"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Notifications

The integrationServices/v3/notification API has been deprecated and replaced by the platform Alerts v7 API or the Data Forwarder - Alerts Schema 2.0.0

Migration information is available in the Migration Guide.


Last modified on June 30, 2023