Alerts v6 API

This API will be deactivated on September 5, 2024.

The appServices v6 Alert API has been deprecated and replaced by the platform api/alerts/v7 API.

More information on the new alert service can be found here.

Migration information is available here.

Note: As part of the Alerts v7 API release a new alert type of Intrusion Detection System (IDS) is available. The Alert v6 API search does not return these alerts. The v6 Get Alert by Id route will return the record but data will be incomplete, and the Alert Type will incorrectly show as CB_ANALYTICS. Please transition to Alerts v7 API to work with this new alert type and get the most from your integration.

Note: As part of the Alerts v7 API release and Alert Forwarder Schema v2, Observed Alerts were removed.

Observed Alerts will continue to be returned in Alerts v6 API responses and Data Forwarder Alert Schema v1.
An Observed Alert can only be enriched by
- Searching Enriched Events by alert_id
- Searching Observations by event_id using created_by_event_id from the Observed Alert
An Observed Alert is identified by category = MONITORED in the API response and WARNING in the Alert Forwarder output.
Observed Alerts are not returned in Alerts v7 API responses or in the Data Forwarder Alert Schema v2.
See Announcing the Alerts V7 API and “Observed Alerts” Become “Observations” for more information.

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.

CBC Managed Identity

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.

CSP Managed Identity

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.

Note: If an empty list is provided as search criteria, the API will treat it as a wildcard and match everything.

Ex: Returns only results with a category of "THREAT" or "INFO"


    "criteria": {
        "category": ["THREAT", "INFO"]
        }

Ex: Returns all results


    "criteria": {
        "category": []
        }

API Calls

Alert Search

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.

API 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.

API 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.

Alert facets search request.

API 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.

API 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.

API 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.

API 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.

API 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.

API 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

API 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.

API 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.

API 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

API 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 in the Carbon Black Cloud 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, recorded by the sensor, 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, recorded by the sensor, 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 in the Carbon Black Cloud 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`, `CONTAINER_RUNTIME`, `DEVICE_CONTROL`, `HOST_BASED_FIREWALL`, `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`, `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 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 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`

Host-Based Firewall

Host-Based Firewall alerts are created from network detections in the Endpoint Standard Host-Based Firewall add-on

Note: This alert will also include all 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`
`policy_applied`	Whether a policy was applied	String	`APPLIED`, `NOT_APPLIED`
`reason`	Description of the alert	String	N/A
`reason_code`	Shorthand enum for the full-text reason	String	N/A
`rule_id`	The id of the host-based firewall rule config	String	N/A
`rule_category_id`	The category id of the host-based firewall rule config	String	N/A
`sensor_action`	The action taken by the sensor, according to the rule of the policy	String	`POLICY_NOT_APPLIED`, `ALLOW`, `ALLOW_AND_LOG`, `DENY`
`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`

Watchlist Alert

Watchlist alerts are created from alert enabled watchlists in Enterprise EDR

Note: This alert will also include all 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 October 10, 2023

Carbon Black Cloud

Page Contents

Alerts v6 API

Introduction

Authentication

Quick Start

API Calls

Alert Search

Get Alert by ID

Facet Alerts

Create Workflow

Bulk Create Workflows

Create Threat Workflow

Bulk Create Threat Workflows

Get Bulk Workflow Status

Get Alert Search Suggestions

Create Note

Get Notes

Delete Note

Fields

Base Alert

CB Analytics Alert

Container Runtime Alert

Device Control Alert

Host-Based Firewall

Watchlist Alert