Alerts API

Introduction

We have extended the capabilities of the Alerts API by improving the methods of retrieving alerts, and adding functionality to manage the workflow by updating the alert status. This will allow you to more efficiently call an API by providing a wider range of filterable fields, including creation time, category, type, status, tag and more, as well as the ability to dismiss alerts.

Authentication

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

  • Access Level: Before you create your API Key, you need to create a custom Access Level
    • for the category Alerts > General Information > “org.alerts” allow permissions for “READ”
    • for the category Alerts > Dismiss > “org.alerts.dismiss” allow permissions for “EXECUTE”
    • for the category Alerts > Notes > “org.alerts.notes” allow permissions for “CREATE”, “READ”, and “DELETE”
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
  • API Route: /appservices/v6/orgs/{org_key}/alerts/_search Note: when you insert your org_key, you must also remove the { } brackets.

API Calls

Note: As of August 5th, 2021 legacy_alert_id will equal id and use the GUID format to unify the alert identifiers. No changes will be needed to any API workflows as you’ll be able to search on either field.

Alert search request. Multiple pathways support similar request body schemas, including those listed below.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts READ

Requests

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_search

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/_search

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_search

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/_search

Below is an example request body for a request to /v6/orgs/{org_key}/alerts/_search. Additional criteria properties are available for the CbAnalytics, Device Control, and Watchlist pathways.

Request Body 

{
    "criteria": {
        "category": ["<string>", "<string>"],
        "create_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "device_id": ["<long>", "<long>"],
        "device_name": ["<string>", "<string>"],
        "device_os": ["<string>", "<string>"],
        "device_os_version": ["<string>", "<string>"],
        "device_username": ["<string>", "<string>"],
        "first_event_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "group_results": "<boolean>",
        "id": ["<string>", "<string>"],
        "last_event_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "legacy_alert_id": ["<string>", "<string>"],
        "minimum_severity": "<integer>",
        "policy_id": ["<long>", "<long>"],
        "policy_name": ["<string>", "<string>"],
        "process_name": ["<string>", "<string>"],
        "process_sha256": ["<string>", "<string>"],
        "reputation": ["<string>", "<string>"],
        "tag": ["<string>", "<string>"],
        "target_value": ["<string>", "<string>"],
        "threat_id": ["<string>", "<string>"],
        "type": ["<string>", "<string>"],
        "last_update_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "workflow": ["<string>", "<string>"],
    },
    "query": "<string>",
    "rows": "<long>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<long>"
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "device_id": [ 5, 12, 101 ]
}
Supported fields:
category,
create_time,
device_id,
device_name,
device_os_version,
device_os,
first_event_time,
group_results,
id,
last_event_time
legacy_alert_id,
minimum_severity,
policy_id,
policy_name,
process_name,
process_sha256,
reputation,
tag,
target_value,
device_username,
threat_id,
type,
workflow
query Query in lucene syntax and/or including value searches. String N/A
rows For pagination, how many results to return Integer Default: 20
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Only one sort can be specified at this time. Array 
[{
  "field": "device_timestamp",
  "order": "ASC"
}]
order supports ASC or DESC

Supported fields: first_event_time, last_event_time, create_time, last_update_time, severity, target_value
start For pagination, where to start retrieving results from Integer Default: 0

Rows + Start can not exceed 10k

Note: Events may take a few minutes to become available by API due to the asynchronous event processing. Consider delaying your search by 2-3 min or use the Data Forwarder for streaming behavior

Time Criteria

Alert APIs support filtering via the create_time, last_update_time, first_event_time, and last_event_time criteria fields. These time criteria filters can use either the range field or the start and end fields.

  • range can be either all (to indicate all time), or a specific duration specified as -[quantity][unit], where unit is one of:
    • s for seconds
    • m for minutes
    • h for hours
    • d for days
    • w for weeks
    • y for years
  • start and end are specified as ISO-8601 strings. start must be less than end.

Additional Alert specific criteria fields

Path Allowed Fields
/v6/orgs/{org_key}/alerts/cbanalytics/_search blocked_threat_category, device_location, kill_chain_status, not_blocked_threat_category, policy_applied, reason_code, run_state, sensor_action, threat_cause_vector
/v6/orgs/{org_key}/alerts/watchlist/_search report_id, report_name, watchlist_id, watchlist_name
/v6/orgs/{org_key}/alerts/devicecontrol/_search external_device_friendly_name, external_device_id, product_id, product_name, serial_number, vendor_id, vendor_name

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/_search

Request Body 

{
    "criteria": {
		"device_id": [388948],
		"device_os": ["MAC"],
		"device_os_version": ["10.14.6"],
		"device_username": ["support@carbonblack.com"],
		"group_results": false,
		"id": ["038894832709076d63111e99466f73575fcf3ca"],
		"minimum_severity": 3,
		"policy_name": ["default"],
		"process_name": ["IPv6-Off"]
    },
    "rows": 1,
    "start": 1
}

Response 

{
 "num_found": 1,
 "num_available": 1,
 "results": [
   {
     "id": "038894832709076d63111e99466f73575fcf3ca",
     "legacy_alert_id": "1DDU8H9N",
     "type": "CB_ANALYTICS",
     "org_key": "ABCD1234",
     "create_time": "2019-09-13T14:17:21.668Z",
     "last_update_time": "2019-09-13T14:17:21.668Z",
     "first_event_time": "2019-09-13T14:16:55.878Z",
     "last_event_time": "2019-09-13T14:16:55.878Z",
     "threat_id": "b7ce4f79e8903c09d2cd6b615c965c9f",
     "severity": 3,
     "category": "MONITORED",
     "device_id": 388948,
     "device_os": "MAC",
     "device_os_version": "10.14.6",
     "device_name": "some-system",
     "device_username": "support@carbonblack.com",
     "policy_id": 1,
     "policy_name": "default",
     "target_value": "MISSION_CRITICAL"
    }
  ]
}

NOTE: The response above has been abbreviated to show only the fields available in the Base Alert schema. Real responses will include the full alert body as defined by the different Alert Schemas.

Pagination

This API supports pagination via the rows and start parameters in the POST body and is limited to the first 10k results. They work as described in the API Basics pagination guide.

In the response, num_found indicates the total number of hits for the search. num_available indicates the total number of retrievable hits for the search. Not all results found are necessarily retrievable because deep pagination is limited for performance reasons. When num_found is greater than num_available, consider adding more specific criteria to the request to retrieve more results.

Consuming all alerts

The best practice for a reliable, near-real-time stream of Alerts is through the Data Forwarder

Alternatively, this API can be used as a RESTful replacement for using the legacy /integrationServices/v3/notification route to export all alert details.

Instead of configuring a notification rule to limit the alerts retrieved, the v6 route relies on the use of the criteria object:

  • Alert crosses a threshold can be replicated with the minimum_severity criteria
  • Alert includes specific TTPs can be replicated with a custom query (ttp:SOME_TTP)
  • Policy Action is enforced can be replicated with the sensor_action criteria
  • Watchlist gets a hit can be replicated by using setting the type criteria to just WATCHLIST

The v6 alert APIs do not track any state; it is up to the developer to keep track of the last alert seen and query for alerts that have been generated since then.

Use the last_update_time criteria to retrieve alerts that have come in since your last call. This field contains the datastore ingestion timestamp of the latest version of the alert. The timestamp can be the creation time or the time Carbon Black Cloud updates an aspect of the alert.

To guarantee that once a time range has been queried no new alerts will be added into that same bucket, keep a 15min delay from current time. This will allow the Carbon Black Cloud to update the alert based on additional events associated with the incident and any binary reputations that are adjusted.

Avoid using pagination when sorting and fetching by last_update_time, instead request the max rows of 10k. Additionally, be mindful that if num_found is greater than 10k in the response, you will need to adjust the next fetch to start at the latest timestamp from your previous fetch to retrieve all alerts otherwise you’ll miss out on alerts in that time window.

Get Alert by ID

Get a single alert using an ID.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts READ

Request

GET <cbc-hostname>/appservices/v6/org/{org_key}/alerts/{alert_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207

Response 

{
 "type": "CB_ANALYTICS",
 "id": "225219783948647d55b11e9962bf3b07592c207",
 "legacy_alert_id": "L1QDMJUO",
 "org_key": "ABCD1234",
 "create_time": "2019-09-12T12:47:45.595Z",
 "last_update_time": "2019-09-12T12:47:45.595Z",
 "first_event_time": "2019-09-12T12:47:36.703Z",
 "last_event_time": "2019-09-12T12:47:36.703Z",
 "threat_id": "e7ba0f751456211fea35b9d955dc5098",
 "severity": 7,
 "category": "THREAT",
 "device_id": "<device-id>",
 "device_os": "<device-os>",
 "device_os_version": "<device-os>",
 "device_name": "<device-name>",
 "device_username": "<device-username>",
 "policy_id": 1,
 "policy_name": "default",
 "target_value": "MISSION_CRITICAL"
}

NOTE: The response above has been abbreviated to show only the fields available in the Base Alert schema. Real responses will include the full alert body as defined by the different Alert Schemas.

Facet Alerts

Alert facets search request. Multiple pathways support similar request body schemas, including those listed below.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts READ

Requests

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_facet

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/_facet

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_facet

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/_facet

Below is an example request body for a request to /v6/orgs/{org_key}/alerts/_facet. Additional criteria properties are available for the CbAnalytics, Device Control, and Watchlist pathways.

Request Body 

{
    "criteria": {
        "category": ["<string>", "<string>"],
        "create_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "device_id": ["<long>", "<long>"],
        "device_name": ["<string>", "<string>"],
        "device_os": ["<string>", "<string>"],
        "device_os_version": ["<string>", "<string>"],
        "device_username": ["<string>", "<string>"],
        "first_event_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "group_results": "<boolean>",
        "id": ["<string>", "<string>"],
        "last_event_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "legacy_alert_id": ["<string>", "<string>"],
        "minimum_severity": "<integer>",
        "policy_id": ["<long>", "<long>"],
        "policy_name": ["<string>", "<string>"],
        "process_name": ["<string>", "<string>"],
        "process_sha256": ["<string>", "<string>"],
        "reputation": ["<string>", "<string>"],
        "tag": ["<string>", "<string>"],
        "target_value": ["<string>", "<string>"],
        "threat_id": ["<string>", "<string>"],
        "type": ["<string>", "<string>"],
        "last_update_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "workflow": ["<string>", "<string>"],
    },
    "query": "<string>",
    "terms": {
        "fields": ["<string>", "<string>"],
        "rows": "<integer>"
    }
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "device_id": [ 5, 12, 101 ]
}
Supported fields:
category,
create_time,
device_id,
device_name,
device_os_version,
device_os,
first_event_time,
group_results,
id,
last_event_time
legacy_alert_id,
minimum_severity,
policy_id,
policy_name,
process_name,
process_sha256,
reputation,
tag,
target_value,
device_username,
threat_id,
type,
workflow
query Query in lucene syntax and/or including value searches. String N/A
terms REQUIRED The alert fields to facet and how many of the top entries to return. Object 
{
  "fields": [
    "application_name"
  ],
  "rows": 100
}
Default Rows: 20
Supported Fields: listed in the table below

Time Criteria

Alert APIs support filtering via the create_time, last_update_time, first_event_time, and last_event_time criteria fields. These time criteria filters can use either the range field or the start and end fields.

  • range can be either all (to indicate all time), or a specific duration specified as -[quantity][unit], where unit is one of:
    • s for seconds
    • m for minutes
    • h for hours
    • d for days
    • w for weeks
    • y for years
  • start and end are specified as ISO-8601 strings. start must be less than end.

Fields Available for Faceting

Field Definition Values
ALERT_TYPE Type CB_ANALYTICS, WATCHLIST, etc.
CATEGORY Category THREAT, MONITORED
REPUTATION Reputation of the primary involved process KNOWN_MALWARE, NOT_LISTED, etc.
WORKFLOW Alert dismissal state OPEN, DISMISSED
TAG User-defined Tags N/A
POLICY_ID Policy ID N/A
POLICY_NAME Policy Name N/A
DEVICE_ID Device ID N/A
DEVICE_NAME Device Name N/A
APPLICATION_HASH SHA256 Hash of the primary involved process N/A
APPLICATION_NAME Name involved process N/A
RUN_STATE Whether the process ran RAN, DID_NOT_RUN
POLICY_APPLIED Whether a policy was applied APPLIED, NOT_APPLIED
SENSOR_ACTION Action taken by the sensor ALLOW, DENY, TERMINATE, etc.

Additional Alert specific criteria fields

Path Allowed Fields
/v6/orgs/{org_key}/alerts/cbanalytics/_facet blocked_threat_category, device_location, kill_chain_status, not_blocked_threat_category, policy_applied, reason_code, run_state, sensor_action, threat_cause_vector
/v6/orgs/{org_key}/alerts/watchlist/_facet report_id, report_name, watchlist_id, watchlist_name
/v6/orgs/{org_key}/alerts/devicecontrol/_facet external_device_friendly_name, external_device_id, product_id, product_name, serial_number, vendor_id, vendor_name

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/_facet

Request Body

{
    "criteria": {
        "category": ["THREAT", "INFO"],
    },
    "terms": {
    	"fields": ["ALERT_TYPE"],
        "rows": 50
    }
}

Response 

{
   "results": [
       {
           "field": "alert_type",
           "values": [
               {
                   "total": 587,
                   "id": "CB_ANALYTICS",
                   "name": "CB_ANALYTICS"
               },
               {
                   "total": 0,
                   "id": "WATCHLIST",
                   "name": "WATCHLIST"
               }
           ]
       }
   ]
}

Create Workflow

Update the alert with the current state of the remediation.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.dismiss EXECUTE

Request

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/workflow

Request Body 

{
    "state": "<string>",
    "comment": "<string>",
    "remediation_state": "<string>"
}

Body Schema

Field Definition Data Type Values
state REQUIRED Workflow state to set. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/workflow

Request Body 

{
    "state": "OPEN",
    "comment": "This is an example",
    "remediation_state": "NOTHING"
}

Response 

{
  "state": "OPEN",
  "remediation": "NOTHING",
  "last_update_time": "2020-09-14T15:02:04.620Z",
  "comment": "This is an example",
  "changed_by": "A569S6YYRE"
}

Bulk Create Workflows

Bulk update alerts’ workflow by search definition. Multiple pathways support similar request body schemas, including those listed below.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.dismiss EXECUTE

Requests

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/workflow/_criteria

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/workflow/_criteria

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/workflow/_criteria

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/workflow/_criteria

Below is an example request body for a request to v6/orgs/{org_key}/alerts/workflow/_criteria. Additional criteria properties are available for the CbAnalytics, Device Control, and Watchlist pathways.

Request Body 

{
    "state": "<string>",
    "comment": "<string>",
    "criteria": {
        "category": ["<string>", "<string>"],
        "create_time": {
            "end": "<dateTime>",
            "range": "<string>",
            "start": "<dateTime>"
        },
        "device_id": ["<long>", "<long>"],
        "device_name": ["<string>", "<string>"],
        "device_os": ["<string>", "<string>"],
        "device_os_version": ["<string>", "<string>"],
        "device_username": ["<string>", "<string>"],
        "group_results": "<boolean>",
        "id": ["<string>", "<string>"],
        "legacy_alert_id": ["<string>", "<string>"],
        "minimum_severity": "<integer>",
        "policy_id": ["<long>", "<long>"],
        "policy_name": ["<string>", "<string>"],
        "process_name": ["<string>", "<string>"],
        "process_sha256": ["<string>", "<string>"],
        "report_id": ["<string>", "<string>"],
        "report_name": ["<string>", "<string>"],
        "reputation": ["<string>", "<string>"],
        "tag": ["<string>", "<string>"],
        "target_value": ["<string>", "<string>"],
        "threat_id": ["<string>", "<string>"],
        "type": ["<string>", "<string>"],
        "watchlist_id": ["<string>", "<string>"],
        "watchlist_name": ["<string>", "<string>"],
        "workflow": ["<string>", "<string>"],
    },
    "query": "<string>",
    "remediation_state": "<string>"
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "device_id": [ 5, 12, 101 ]
}
Supported fields:
category,
create_time,
device_id,
device_name,
device_os_version,
device_os,
first_event_time,
group_results,
id,
last_event_time
legacy_alert_id,
minimum_severity,
policy_id,
policy_name,
process_name,
process_sha256,
reputation,
tag,
target_value,
device_username,
threat_id,
type,
workflow
query Query in lucene syntax and/or including value searches. String N/A
state REQUIRED Workflow state to filter on. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Additional Alert specific criteria fields

Path Allowed Fields
/v6/orgs/{org_key}/alerts/cbanalytics/workflow/_criteria blocked_threat_category, device_location, kill_chain_status, not_blocked_threat_category, policy_applied, reason_code, run_state, sensor_action, threat_cause_vector
/v6/orgs/{org_key}/alerts/watchlist/workflow/_criteria report_id, report_name, watchlist_id, watchlist_name
/v6/orgs/{org_key}/alerts/devicecontrol/workflow/_criteria external_device_friendly_name, external_device_id, product_id, product_name, serial_number, vendor_id, vendor_name

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/watchlist/workflow/_criteria

Request Body 

{
  "comment": "string",
  "criteria": {
    "category": ["THREAT"],
    "create_time": {
      "end": "2019-09-17T00:03:47.277Z",
      "start": "2019-09-17T00:03:47.277Z"
    },
    "device_id": [324552, 12344, 997745],
    "device_name": ["hostmachine", "device.local", "DOMAIN\\DEVICE"],
    "device_os": ["WINDOWS"],
    "device_os_version": ["string"],
    "device_username": ["string"],
    "group_results": true,
    "id": ["string"],
    "legacy_alert_id": ["CTAS5XKG", "TJFY5ZBW"],
    "minimum_severity": 5,
    "policy_id": [1, 525, 644],
    "policy_name": ["Default", "Advanced", "Monitored"],
    "process_name": ["explorer.exe", "chrome.app", "setup.py"],
    "process_sha256": ["131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267"],
    "report_id": ["string"],
    "report_name": ["string"],
    "reputation": ["KNOWN_MALWARE"],
    "tag": ["string"],
    "target_value": ["LOW"],
    "threat_id": ["03ea43268c536a0bde8b765bca1696e9", "41edc35062138af3f1fea4b3bf7046a5"],
    "type": ["CB_ANALYTICS"],
    "watchlist_id": ["string"],
    "watchlist_name": ["string"],
    "workflow": ["OPEN"],
  },
  "query": "string",
  "remediation_state": "string",
  "state": "OPEN"
}

Response 

{
 "request_id": "14617a6cd8df11e9974f1d8882e43ec1"
}

Create Threat Workflow

Update the threat with the current state of the remediation.

Note: This will dismiss all future alerts that are associated with the threat_id when marked as DISMISSED

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.dismiss EXECUTE

Request

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/threat/{threat_id}/workflow

Request Body 

{
    "state": "<string>",
    "comment": "<string>",
    "remediation_state": "<string>"
}

Body Schema

Field Definition Data Type Values
state REQUIRED Workflow state to set. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/threat/fbeca35516132a69747b7094e082b424/workflow

Request Body 

{
    "state": "OPEN",
    "comment": "This is an example",
    "remediation_state": "NOTHING"
}

Response 

{
  "state": "OPEN",
  "remediation": "NOTHING",
  "last_update_time": "2020-09-14T15:02:04.620Z",
  "comment": "This is an example",
  "changed_by": "A569S6YYRE"
}

Bulk Create Threat Workflows

Bulk update threat’ workflow by threat_id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.dismiss EXECUTE

Requests

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/threat/workflow/_criteria

Request Body 

{
  "comment": "string",
  "remediation_state": "string",
  "state": "OPEN",
  "threat_id": [
    "string"
  ]
}

Body Schema

Field Definition Data Type Values
threat_id REQUIRED List of threat ids to update. Array N/A
state REQUIRED Workflow state to filter on. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/threat/workflow/_criteria

Request Body 

{
  "comment": "Initial triage complete",
  "remediation_state": "TRIAGED",
  "state": "OPEN",
  "threat_id": [
    "fbeca35516132a69747b7094e082b424",
    "8e991f4e1dbd3b5b92e5fc5509c24503"
  ]
}

Response 

{
 "request_id": "14617a6cd8df11e9974f1d8882e43ec1"
}

Get Bulk Workflow Status

Get the current status of a bulk workflow request.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.dismiss EXECUTE

Request

GET <cbc-hostname>/appservices/v6/orgs/{org_key}/workflow/status/{request_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/workflow/status/14617a6cd8df11e9974f1d8882e43ec1

Response 

{
  "errors": ["string"],
  "failed_ids": ["string"],
  "id": "string",
  "num_hits": 0,
  "num_success": 0,
  "status": "QUEUED",
  "workflow": {
    "changed_by": "string",
    "comment": "string",
    "last_update_time": "2019-09-17T00:39:23.823Z",
    "remediation": "string",
    "state": "OPEN"
  }
 }

Get Alert Search Suggestions

Get recommendations for key or values based on the specified search query

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts READ

Query Schema

Field Definition Data Type Values
suggest.q REQUIRED The query string for which you want completion suggestions. Leave this value blank, suggest.q=, to return all key suggestions. String N/A

Request

GET <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/search_suggestions

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/search_suggestions?suggest.q=

Response 

{
   "suggestions": [
       {
           "term": "threat_category",
           "weight": 525
       },
       {
           "term": "watchlist_name",
           "weight": 512
       },
       {
           "term": "ttp",
           "weight": 486
       },
       {
           "term": "run_state",
           "weight": 481
       },
       {
           "term": "device_name",
           "weight": 477
       },
       {
           "term": "alert_id",
           "weight": 472
       },
       {
           "term": "event_id",
           "weight": 472
       },
       {
           "term": "threat_vector",
           "weight": 468
       },
       {
           "term": "device_username",
           "weight": 461
       },
       {
           "term": "report_id",
           "weight": 458
       },
       {
           "term": "process_guid",
           "weight": 431
       },
       {
           "term": "process_name",
           "weight": 431
       },
       {
           "term": "sensor_action",
           "weight": 424
       },
       {
           "term": "alert_severity",
           "weight": 419
       },
       {
           "term": "device_id",
           "weight": 412
       },
       {
           "term": "device_os",
           "weight": 412
       },
       {
           "term": "device_policy",
           "weight": 401
       },
       {
           "term": "process_pid",
           "weight": 311
       },
       {
           "term": "process_hash",
           "weight": 306
       },
       {
           "term": "process_reputation",
           "weight": 287
       }
   ]
}

Create Note

Add segments of text to an alert to track notes while investigating the potential threat.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.notes CREATE

Request

POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes

Request Body

{
  "note": "<string>"
}

Body Schema

Field Definition Data Type Values
note REQUIRED A segment of text to attach to the specified Alert String Max: 255 characters

Response

Code Description Content-Type Content
200 Successful creation of a note application/json View example response below
400 Bad request. application/json N/A
404 Resource not found N/A N/A
500 Internal server error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes

Request Body

{
  "note": "This is an example"
}

Response

{
  "author": "A569S6YYRE",
  "create_time": "2020-09-14T13:56:26.429Z",
  "id": "71d04030f69311eabf1ad95d2b04fece",
  "note": "This is an example"
}

Get Notes

Fetch the notes created for the specified alert

Note: The UI console uses an older API currently so notes from the console will be associated with the threat_id instead of the alert_id. Therefore, the notes from the console will not be returned from this API.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.notes READ

Request

GET <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes

Response

Code Description Content-Type Content
200 Successful fetch of the notes application/json View example response below
404 Resource not found N/A N/A
500 Internal server error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes

Response

{
  "num_found": 1,
  "results": [
    {
      "author": "A569S6YYRE",
      "create_time": "2020-09-14T13:56:26.429Z",
      "id": "71d04030f69311eabf1ad95d2b04fece",
      "note": "This is an example"
    }
  ]
}

Delete Note

Deletes the specified note for the specified alert

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.alerts.notes DELETE

Request

DELETE <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes/{note_id}

Response

Code Description Content-Type Content
204 Successful delete of the note No Content View example response below
404 Resource not found N/A N/A
500 Internal server error N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes/71d04030f69311eabf1ad95d2b04fece

Response

No Content

Schemas

Base Alert

Field Definition Data Type Values
category The category of the alert String THREAT, MONITORED
create_time The time the alert was created String ISO 8601 timestamp
device_id The identifier assigned by Carbon Black Cloud to the device associated with the alert. Integer N/A
device_name The hostname of the device associated with the alert. String N/A
device_os The operating system of the device associated with the alert String WINDOWS, MAC, LINUX, OTHER
device_os_version The operating system and version on the device String N/A
device_username The username of the user that owns the device String N/A
first_event_time The time of the first event associated with the alert String ISO 8601 timestamp
group_details Details about a group of alerts when “Group Alerts” is enabled in the search request Object 
{
  "count": 5,
  "total_devices": 3
}
id The identifier for the alert String N/A
last_event_time The time of the latest event associated with the alert String ISO 8601 timestamp
last_update_time The last time the alert was updated String ISO 8601 timestamp
legacy_alert_id Deprecated

Use id for referencing an alert		 String N/A
notes_present Indicates if notes are associated with the threat_id Boolean N/A
org_key The unique identifier for the organization associated with the alert String N/A
policy_id The identifier for the policy associated with the device at the time of the alert String N/A
policy_name The name of the policy associated with the device at the time of the alert String N/A
severity The threat ranking of the alert Integer 1-10
tags Tags associated with the alert Array 
[ "tag1", "tag2" ]
target_value The priority of the device assigned by the policy String LOW, MEDIUM, HIGH, MISSION_CRITICAL
threat_id The identifier of a threat which this alert belongs. Threats are comprised of a combination of factors that can be repeated across devices. String N/A
type Type of alert String CB_ANALYTICS, DEVICE_CONTROL WATCHLIST
workflow Tracking system for alerts as they are triaged and resolved Object 
{
  "changed_by": "username",
  "comment": "Beginning to investigate",
  "last_update_time": "2019-09-13T14:17:21.668Z",
  "remediation": null,
  "state": "OPEN"  
}
remediation supports ACTION_TAKEN, NO_ACTION_NEEDED, FALSE_POSITIVE_KNOWN_GOOD_SOFTWARE, FALSE_POSITIVE_KNOWN_GOOD_BEHAVIOR or a custom string

state supports OPEN or DISMISSED

CB Analytics Alert

CB Analytic alerts are created from the Endpoint Standard NGAV offering

Note: This alert will also include all of the fields from Base Alert

Field Definition Data Type Values
blocked_threat_category The category of threat which we were able to take action on String UNKNOWN, NON_MALWARE, NEW_MALWARE, KNOWN_MALWARE, RISKY_PROGRAM
created_by_event_id Event identifier that initiated the alert String N/A
device_location Whether the device was on or off premise when the alert started String ONSITE, OFFSITE, UNKNOWN
kill_chain_status The stage within the Cyber Kill Chain sequence most closely associated with the attributes of the alert Array 
[ "EXECUTE_GOAL", "BREACH" ]
supported values RECONNAISSANCE, WEAPONIZE, DELIVER_EXPLOIT, INSTALL_RUN, COMMAND_AND_CONTROL, EXECUTE_GOAL, BREACH
not_blocked_threat_category Other potentially malicious activity involved in the threat that we weren’t able to take action on (either due to policy config, or not having a relevant rule) String UNKNOWN, NON_MALWARE, NEW_MALWARE, KNOWN_MALWARE, RISKY_PROGRAM
policy_applied Whether a policy was applied String APPLIED, NOT_APPLIED
process_name The process that triggered the alert String N/A
reason Description of the alert String N/A
reason_code Shorthand enum for the full-text reason String N/A
run_state Whether the threat in the alert ran String DID_NOT_RUN, RAN, UNKNOWN
sensor_action The action taken by the sensor, according to the rule of the policy String POLICY_NOT_APPLIED, ALLOW, ALLOW_AND_LOG, TERMINATE, DENY
threat_activity_c2 Whether the alert involved a command and control (c2) server String NOT_ATTEMPTED, ATTEMPTED, SUCCEEDED
threat_activity_dlp Whether the alert involved data loss prevention (DLP) String NOT_ATTEMPTED, ATTEMPTED, SUCCEEDED
threat_activity_phish Whether the alert involved phishing String NOT_ATTEMPTED, ATTEMPTED, SUCCEEDED
threat_cause_actor_name The name can be one of the following: process commandline, process name, or analytic matched threat. Analytic matched threats are Exploit, Malware, PUP, or Trojan String N/A
threat_cause_actor_process_pid Process identifier (PID) of the actor process String N/A
threat_cause_actor_sha256 SHA256 or remote IP of the threat cause actor. The actor will be a remote IP when the alert is created from a netconn event String N/A
threat_cause_cause_event_id ID of the Event that triggered the threat String N/A
threat_cause_reputation Reputation of the threat cause String KNOWN_MALWARE, SUSPECT_MALWARE, PUP, NOT_LISTED, ADAPTIVE_WHITE_LIST, COMMON_WHITE_LIST, TRUSTED_WHITE_LIST, COMPANY_BLACK_LIST
threat_cause_threat_category Category of the threat cause String UNKNOWN, NON_MALWARE, NEW_MALWARE, KNOWN_MALWARE, RISKY_PROGRAM
threat_cause_vector The source of the threat cause String EMAIL, WEB, GENERIC_SERVER, GENERIC_CLIENT, REMOTE_DRIVE, REMOVABLE_MEDIA, UNKNOWN, APP_STORE, THIRD_PARTY
threat_indicators List of the threat indicators that make up the threat Array 
[
{
  "process_name": "<string>",
  "sha256": "<string>",
  "ttps": ["<string>", <string>],
}
]

Device Control Alert

Device Control alerts are created when an endpoint attempts to access a blocked USB device

Note: This alert will also include all of the fields from Base Alert

Field Definition Data Type Values
device_location Whether the device was on or off premise when the alert started String ONSITE, OFFSITE, UNKNOWN
external_device_friendly_name The human readable USB device name String N/A
policy_applied Whether a policy was applied String APPLIED, NOT_APPLIED
product_id The hexadecimal id of the USB device’s product String 0x5581
product_name The name of the USB device’s product String N/A
reason Description of the alert String N/A
reason_code Shorthand enum for the full-text reason String N/A
run_state Whether the threat in the alert ran String DID_NOT_RUN, RAN, UNKNOWN
sensor_action The action taken by the sensor, according to the rule of the policy String POLICY_NOT_APPLIED, ALLOW, ALLOW_AND_LOG, TERMINATE, DENY
serial_number The serial number of the USB device String N/A
threat_cause_cause_event_id ID of the Event that triggered the threat String N/A
threat_cause_threat_category Category of the threat cause String UNKNOWN, NON_MALWARE, NEW_MALWARE, KNOWN_MALWARE, RISKY_PROGRAM
threat_cause_vector The source of the threat cause String EMAIL, WEB, GENERIC_SERVER, GENERIC_CLIENT, REMOTE_DRIVE, REMOVABLE_MEDIA, UNKNOWN, APP_STORE, THIRD_PARTY
vendor_name The name of the USB device’s vendor String N/A
vendor_id The hexadecimal id of the USB device’s vendor String 0x0781

Watchlist Alert

Watchlist alerts are created from alert enabled watchlists in Enterprise EDR

Note: This alert will also include all of the fields from Base Alert

Field Definition Data Type Values
ioc_field The field the indicator of comprise (IOC) hit contains String N/A
ioc_hit IOC field value or IOC query that matches String N/A
ioc_id The identifier of the IOC that cause the hit String N/A
process_guid The global unique identifier of the process that triggered the hit String N/A
process_name The name of the process that triggered the hit String N/A
reason Description of the alert String N/A
report_id The identifier of the report that contains the IOC String N/A
report_name The name of the report that contains the IOC String N/A
run_state Run state is always RAN for watchlist alerts String RAN
threat_cause_actor_md5 MD5 of the threat cause actor String N/A
threat_cause_actor_name The process path of the threat actor String N/A
threat_cause_actor_sha256 SHA256 or remote IP of the threat cause actor. The actor will be a remote IP when the alert is created from a netconn event String N/A
threat_cause_reputation Reputation of the threat cause String KNOWN_MALWARE, SUSPECT_MALWARE, PUP, NOT_LISTED, ADAPTIVE_WHITE_LIST, COMMON_WHITE_LIST, TRUSTED_WHITE_LIST, COMPANY_BLACK_LIST
threat_cause_threat_category Category of the threat cause String UNKNOWN, NON_MALWARE, NEW_MALWARE, KNOWN_MALWARE, RISKY_PROGRAM
threat_cause_vector The source of the threat cause String EMAIL, WEB, GENERIC_SERVER, GENERIC_CLIENT, REMOTE_DRIVE, REMOVABLE_MEDIA, UNKNOWN, APP_STORE, THIRD_PARTY
threat_indicators List of the threat indicators that make up the threat Array 
[
{
  "process_name": "<string>",
  "sha256": "<string>",
  "ttps": ["<string>", <string>],
}
]
watchlists List of watchlists associated with an alert Array 
[
{
  "id": "<string>",
  "name": "<string>",
}
]
Last modified on July 27, 2021