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

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}/appservices/v6/orgs/{org_key}/alerts/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Alerts > General Information > org.alerts, allow permission to READ
  • Alerts > Dismiss > org.alerts.dismiss, allow permission to EXECUTE
  • Alerts > Notes > org.alerts.notes, allow permission to CREATE, READ, DELETE

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}/appservices/v6/orgs/{org_key}/alerts/

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.Alerts, allow permission to READ
  • _API.Alerts:org.Alerts.Dismiss, allow permission to EXECUTE
  • _API.Alerts:org.Alerts.Notes, allow permission to CREATE, READ, DELETE

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.


Quick Start

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.

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. By default a create_time time range of one month will be applied if no time range is specified.

  • 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 UTC strings. start must be less than end.

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.

See [this guide}(/reference/carbon-black-cloud/guides/alert-bulk-export) for the algorithm and request bodies to perform bulk alert retrieval.

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. If you specify rows less than 10k while sorting by last_update_time then the API response will override and default to returning up to 10k results. This is to prevent the possibility of missing data due to the last_update_time updating while performing consecutive API calls.

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. For more information see the following blog post.

API Calls

Note: As of August 19th, 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.

Note: Alerts 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

RBAC Permissions Required

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

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

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/alerts/containerruntime/_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

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
/v6/orgs/{org_key}/alerts/containerruntime/_search cluster_name, namespace, workload_kind, workload_id, workload_name, replica_id, remote_ip, remote_domain, protocol, port, egress_group_id, egress_group_name, ip_reputation, rule_id,rule_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.

Get Alert by ID

Get a single alert using an ID.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/appservices/v6/orgs/{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.

RBAC Permissions Required

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

Requests

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/alerts/_facet
Additional facet URLs have been deprecated.

The /alerts/cbanalytics/_facet, /alerts/watchlist/_facet, and /alerts/devicecontrol/_facet URLs are no longer supported; criteria filtering using the main /alerts/_facet URL should be used instead.

Below is an example request body for a request to /v6/orgs/{org_key}/alerts/_facet.

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

Fields Available for Faceting all Alert Types

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 Fields Available for CONTAINER_RUNTIME Alerts

Field Definition Values
cluster_name Name of the K8s cluster associated with the alert N/A
namespace Namespace within the K8s cluster associated with the alert N/A
workload_name Name of the workload within a cluster_name/namespace pair N/A

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 workflow (dismissal state) of an alert.

To update many alerts at once, use the Bulk Create Workflows route instead.

RBAC Permissions Required

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

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 the workflow (dismissal state) for any alerts matching a search definition.

This method is suitable replacement for many sequential calls to the single-alert Create Workflow route. You can specify up to 1000 alert IDs per request using the id criteria. To improve performance, you should also specify the create_time criteria (limited to the range when the alerts were created). If a create_time is not specified the default of one month is applied.

RBAC Permissions Required

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

Requests

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/alerts/workflow/_criteria
Additional workflow creation URLs have been deprecated.

The /alerts/cbanalytics/workflow/_criteria, /alerts/watchlist/workflow/_criteria, and /alerts/devicecontrol/workflow/_criteria URLs are no longer supported; criteria filtering using the main /alerts/workflow/_criteria URL should be used instead.

Below is an example request body for a request to v6/orgs/{org_key}/alerts/workflow/_criteria.

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 which alerts will be updated. 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/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

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

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

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

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 which threats will be updated. 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

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

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

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

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

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

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

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

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

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

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

Fields

Base Alert

Field Definition Data Type Values
category The category of the alert String THREAT, MONITORED
create_time The time the alert was created as an ISO 8601 UTC timestamp String Example: 2021-04-07T17:49:58.792Z
device_id The identifier assigned by Carbon Black Cloud to the device associated with the alert. Integer N/A (Always empty for Container Runtime alerts)
device_name The hostname of the device associated with the alert. String N/A (Always empty for Container Runtime alerts)
device_os The operating system of the device associated with the alert String WINDOWS, MAC, LINUX, OTHER (Always empty for Container Runtime alerts)
device_os_version The operating system and version on the device String N/A (Always empty for Container Runtime alerts)
device_username The username of the user that owns the device String N/A (Always empty for Container Runtime alerts)
first_event_time The time of the first event associated with the alert as an ISO 8601 UTC timestamp String Example: 2021-04-07T17:49:58.792Z
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 as an ISO 8601 UTC timestamp String Example: 2021-04-07T17:49:58.792Z
last_update_time The last time the alert was updated as an ISO 8601 UTC timestamp String Example: 2021-04-07T17:49:58.792Z
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, CONTAINER_RUNTIME
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, RESOLVING
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>],
}
]

Container Runtime Alert

Container Runtime alerts are created from the Container Security offering

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

Field Definition Data Type Values
cluster_name Name of the K8s cluster associated with the alert string N/A
connection_type Type of connection enum INGRESS, EGRESS, INTERNAL_INBOUND, INTERNAL_OUTBOUND
egress_group_id ID of the egress group string N/A
egress_group_name Name of the egress group string N/A
ip_reputation Reputation assigned by Carbon Black Cloud; ranges 1-100, where 100 is “trustworthy” int N/A
namespace Namespace within the K8s cluster associated with the alert string N/A
port Listening port; remote or local int N/A
protocol Name of the protocol string Example values: HTTP, TLS, TCP, TELNET, SSH
remote_domain Name of the remote domain string N/A
remote_ip IP address of the remote side ip string N/A
remote_is_private Type of remote IP: public or private (“private” means within the cluster or the org’s network; “public” means outside of the cluster and the org’s network) boolean TRUE, FALSE
remote_namespace Namespace within the remote workload’s cluster; set if the remote side is another workload in the same cluster string N/A
remote_replica_id Remote workload replica ID; set if the remote side is another workload in the same cluster string N/A
remote_workload_id ID of the remote workload; set if the remote side is another workload in the same cluster string N/A
remote_workload_kind Kind of remote workload; set if the remote side is another workload in the same cluster string N/A
remote_workload_name Name of the remote workload; set if the remote side is another workload in the same cluster string N/A
replica_id Name of the pod within a workload string N/A
rule_id Unique identifier for the K8s policy rule string N/A
rule_name Name of the K8s policy rule string N/A
workload_id ID of the workload within a specific cluster_name/namespace pair string N/A
workload_kind Type of workload; Pod, Deployment, Job, etc. string N/A
workload_name Name of the workload within a cluster_name/namespace pair string N/A

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 September 6, 2022