This guide covers the steps required for accessing Carbon Black Cloud APIs:
As either a quick start or to know where we are going, this a sample request to get all devices with a specific id.
$ curl https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search \
-X POST \
-H 'X-Auth-Token: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \
-d '{"criteria": {"id": [ "4034605" ]}}'
This is the same request with the variables named. Follow the information on this page for info on how to create them.
$ curl {hostname}/{API Service Category}/{API path} \
-X POST \
-H 'X-Auth-Token: {API Secret}/{API ID}' \
-H 'Content-Type: application/json' \
-d '{{request body}}'
Coming soon: Getting Started with APIs on Tech Zone
Carbon Black Cloud APIs and Services are authenticated via API Keys. This means that in order to access the data in Carbon Black Cloud via API, you must set up Access Levels and API Keys in the Carbon Black Cloud Console.
The first step of Authentication is determining the appropriate access level for the API. The majority of APIs use an
API Key type of Custom
. The exceptions are three APIs in Endpoint Standard:
API
API
SIEM
Custom
Access Level, an Access Level with minimal permissions should be created to follow the practice of least privilege.
Go to your Carbon Black Cloud console, and open the “Add Access Level” panel from Settings > API Access > Access Levels tab.This example shows the permissions “Create”, “Read”, “Update”, and “Delete” are granted for the Settings permissions in the Data Forwarding category.
For more information about Role-Based Access, see the RBAC Guide.
This is like adding a user to a system and setting their access level, except you are granting access to your application or script instead of a user.
You will need to construct your base URL in order to run the API calls.
The base URL is comprised of the following:
These components are put together in the following structure:
Hostname / API Service Category / API Path / Org Key
First you need to determine which environment, or product URL you use. You can find this by looking at the web address of your Carbon Black Cloud console. Select your URL to view a table with the base URL for each product and API.
Environment | hostname |
---|---|
EAP01 | https://defense-eap01.conferdeploy.net |
Prod 01 | https://dashboard.confer.net |
Prod 02 | https://defense.conferdeploy.net |
Prod 05 | https://defense-prod05.conferdeploy.net |
Prod 06 | https://defense-eu.conferdeploy.net |
Prod NRT | https://defense-prodnrt.conferdeploy.net |
Prod Syd | https://defense-prodsyd.conferdeploy.net |
The API Service Category corresponds to the Carbon Black Cloud product and API you use
/appservices/
for Alerts, Devices, Live Response and Reputation Override APIs v6/data_forwarder/
for the Data Forwarder Configuration APIs (previously Event Forwarder)/investigate/
for the Platform Search APIs (Processes or Enriched Events)/jobs/
for the Jobs Service APIs/sus/
for the Sensor Update Service APIs/vulnerability/assessment/api/
for the Vulnerability Assessment APIs/threathunter/
for the Feed Search and Feed Manager APIs/ubs/
for the Unified Binary Store REST API/livequery/
/device_control/
for the Device Control APIs/integrationServices/
for the Integration Service APIs for Audit Logs, Policy and Notification APIs/investigate/
for the Enriched Events Search APIs/applianceservice/
for the Appliance Service APIs/lcm/view/
for the VM Workloads Search APIs/lcm/
for the Sensor Lifecycle Management APIsThe API Path is specific to the API call you’re using. Usually it is the API version, e.g. v1.
Most Carbon Black Cloud APIs or Services require an org_key
in the API request path to support customers who manage multiple organizations.
org_key
in the Carbon Black Cloud Console under Settings > API Access.Get your {hostname} from the section above.
Follow the API Name for details on the request and response structure for each API call.
Product & API Name | Service Category | API Key Access Level Type | Base URL Structure |
---|---|---|---|
Platform (Any Carbon Black Cloud Product) | |||
Access Profiles and Grants | /access/ |
Custom (with appropriate permissions) | {hostname}/access/v2/orgs/{org_key}/ |
Alerts | /appservices/ |
Custom (with appropriate permissions) | {hostname}/appservices/v6/orgs/{org_key}/alerts |
Data Forwarder Configuration | /data_forwarder/ |
Custom (with appropriate permissions) | {hostname}/data_forwarder/v2/orgs/{org_key}/configs |
Devices | /appservices/ |
Custom (with appropriate permissions) | {hostname}/appservices/v6/orgs/{org_key}/devices |
Jobs Service | /jobs/ |
Custom (with appropriate permissions) | {hostname}/jobs/v1/orgs/{org_key} |
Live Response v6 | /appservices/ |
Custom (with appropriate permissions) | {hostname}/appservices/v6/orgs/{org_key}/liveresponse |
Process Search | /investigate/ |
Custom (with appropriate permissions) | {hostname}/investigate/{v1 or v2}/orgs/{org_key} |
Reputation Override v6 | /appservices/ |
Custom (with appropriate permissions) | {hostname}/appservices/v6/orgs/{org_key}/reputations/overrides |
Sensor Update Service | /sus/ |
Custom (with appropriate permissions) | {hostname}/sus/v2/orgs/{org_key} |
User Management | /appservices/ |
Custom (with appropriate permissions) | {hostname}/appservices/v6/orgs/{org_key}/users |
Vulnerability Assessment | /vulnerability/assessment/api/ |
Custom (with appropriate permissions) | {hostname}/vulnerability/assessment/api/v1/orgs/{org_key} |
Endpoint Standard | |||
Audit Logs | /integrationServices/ |
API (Live Response is deprecated) | {hostname}/integrationServices/v3/auditlogs |
Device Control | /device_control/ |
Custom (with appropriate permissions) | {hostname}/device_control/v3/orgs/{org_key} |
Enriched Events Search | /investigate/* |
Custom (with appropriate permissions) | {hostname}/investigate/{v1 or v2}/orgs/{org_key} |
Notifications | /integrationServices/ |
SIEM | {hostname}/integrationServices/v3/notification |
Policy | /integrationServices/ |
API (Live Response is deprecated) | {hostname}/integrationServices/v3/policy |
Enterprise EDR | |||
Feed Manager | /threathunter/feedmgr |
Custom (with appropriate permissions) | {hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds |
Feed Search | /threathunter/feedsearch |
Custom (with appropriate permissions) | {hostname}/threathunter/feedsearch/v1/orgs/{org_key}/search |
Unified Binary Store | /ubs/ |
Custom (with appropriate permissions) | {hostname}/ubs/v1/orgs/{org_key} |
Watchlist | /threathunter/watchlistmgr/ |
Custom (with appropriate permissions) | {hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists |
Audit and Remediation | |||
Live Query | /livequery/ |
Custom (with appropriate permissions) | {hostname}/livequery/v1/orgs/{org_key} |
Workload | |||
Appliance Service | /applianceservice/ |
Custom (with appropriate permissions) | {hostname}/applianceservice/v1/orgs/{org_key} |
Sensor Lifecycle Management | /lcm/ |
Custom (with appropriate permissions) | {hostname}/lcm/v1/orgs/{org_key} |
NSX Remediation | /applianceservice/ |
Custom (with appropriate permissions) | {hostname}/applianceservice/v1/orgs/{org_key} |
VM Workloads Search | /lcm/view/ |
Custom (with appropriate permissions) | {hostname}/lcm/view/v1/orgs/{org_key} |
Now you have all the information needed to populate the template curl request from the beginning and make your own request.
$ curl {hostname}/{API Service Category}/{API path} \
-X POST \
-H 'X-Auth-Token: {API Secret}/{API ID}' \
-H 'Content-Type: application/json' \
-d '{{request body}}'
Error Code | Reason for Error | Suggested Fix |
---|---|---|
HTTP 400 Bad request |
Usually means that request contains unexpected parameters. | Verify that your request adheres to API documentation. |
HTTP 401 Unauthorized |
Either authentication (invalid token) or access control (missing RBAC) error. | Check that your X-Auth-Token matches the format secret_key/api_id and that the values are correct. |
HTTP 403 Forbidden |
The specified object cannot be accessed or changed. | If it has a Custom access level, check it has been assigned the correct RBAC permissions. If it is an API, SIEM or LIVE_RESPONSE type key, verify it is the right key type for the API in use. |
HTTP 404 Not found |
The object referenced in the request cannot be found. | Verify that your request contains objects that haven’t been deleted. Verify that theorg_key in the path is correct. |
HTTP 409 Conflict |
Either the name you chose already exists, or there is an unacceptable character used. | Change any spaces in the name to underscores. Look through your list of API Keys and see if there is an existing key with the same name. |
HTTP 410 Gone |
Access to the target resource is no longer available at the origin server and that this condition is likely to be permanent. | It is likely this API was deactivated. Review the documentation to find the replacement and migration information. |
HTTP 503 Service unavailable |
Cannot return object at this moment because service is unavailable. | This can happen if too many file downloads are happening at the same time. You can try later. |
HTTP 500 Internal Server Error |
An unexpected error occured on the server | Something went wrong on the back end. Try the request again and if it happens consistently open a support case. |