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.
Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.
/appservices/v6/orgs/{org_key}/alerts/_search
Note: when you insert your org_key, you must also remove the { } brackets.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 secondsm
for minutesh
for hoursd
for daysw
for weeksy
for yearsstart
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.
Instead of configuring a notification rule to limit the alerts retrieved, the v6 route relies on the use of the criteria
object:
minimum_severity
criteriaquery
(ttp:SOME_TTP
)sensor_action
criteriatype
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.
October 20th, 2021
: a default create_time
time range of one month
will be applied to _search
, _facet
, and workflow/_criteria
when no time range specified. See blog for more details.
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
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/_search
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 |
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 |
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 a single alert using an ID.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
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.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_facet
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 |
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 |
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"
}
]
}
]
}
Update the workflow (dismissal state) of an alert.
To update many alerts at once, use the Bulk Create Workflows route instead.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Request
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/workflow
Request Body
{
"state": "<string>",
"comment": "<string>",
"remediation_state": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
state REQUIRED
|
Workflow state to set. | String | DISMISSED , OPEN |
comment |
Comment to include with the operation | String | N/A |
remediation_state |
Description or justification for the change. | String | Accepts any string |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/workflow
Request Body
{
"state": "OPEN",
"comment": "This is an example",
"remediation_state": "NOTHING"
}
Response
{
"state": "OPEN",
"remediation": "NOTHING",
"last_update_time": "2020-09-14T15:02:04.620Z",
"comment": "This is an example",
"changed_by": "A569S6YYRE"
}
Bulk 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
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/workflow/_criteria
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 |
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"
}
Update the threat with the current state of the remediation.
Note: This will dismiss all future alerts that are associated with the threat_id when marked as DISMISSED
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Request
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/threat/{threat_id}/workflow
Request Body
{
"state": "<string>",
"comment": "<string>",
"remediation_state": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
state REQUIRED
|
Workflow state to set. | String | DISMISSED , OPEN |
comment |
Comment to include with the operation | String | N/A |
remediation_state |
Description or justification for the change. | String | Accepts any string |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/threat/fbeca35516132a69747b7094e082b424/workflow
Request Body
{
"state": "OPEN",
"comment": "This is an example",
"remediation_state": "NOTHING"
}
Response
{
"state": "OPEN",
"remediation": "NOTHING",
"last_update_time": "2020-09-14T15:02:04.620Z",
"comment": "This is an example",
"changed_by": "A569S6YYRE"
}
Bulk update threat workflow by threat_id.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/threat/workflow/_criteria
Request Body
{
"comment": "string",
"remediation_state": "string",
"state": "OPEN",
"threat_id": [
"string"
]
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
threat_id REQUIRED
|
List of threat ids to update. | Array | N/A |
state REQUIRED
|
Workflow state to 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 the current status of a bulk workflow request.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Request
GET <cbc-hostname>/appservices/v6/orgs/{org_key}/workflow/status/{request_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/workflow/status/14617a6cd8df11e9974f1d8882e43ec1
Response
{
"errors": ["string"],
"failed_ids": ["string"],
"id": "string",
"num_hits": 0,
"num_success": 0,
"status": "QUEUED",
"workflow": {
"changed_by": "string",
"comment": "string",
"last_update_time": "2019-09-17T00:39:23.823Z",
"remediation": "string",
"state": "OPEN"
}
}
Get recommendations for key or values based on the specified search query
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Query Schema
Field | Definition | Data Type | Values |
---|---|---|---|
suggest.q REQUIRED
|
The query string for which you want completion suggestions. Leave this value blank, suggest.q= , to return all key suggestions. |
String | N/A |
Request
GET <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/search_suggestions
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/search_suggestions?suggest.q=
Response
{
"suggestions": [
{
"term": "threat_category",
"weight": 525
},
{
"term": "watchlist_name",
"weight": 512
},
{
"term": "ttp",
"weight": 486
},
{
"term": "run_state",
"weight": 481
},
{
"term": "device_name",
"weight": 477
},
{
"term": "alert_id",
"weight": 472
},
{
"term": "event_id",
"weight": 472
},
{
"term": "threat_vector",
"weight": 468
},
{
"term": "device_username",
"weight": 461
},
{
"term": "report_id",
"weight": 458
},
{
"term": "process_guid",
"weight": 431
},
{
"term": "process_name",
"weight": 431
},
{
"term": "sensor_action",
"weight": 424
},
{
"term": "alert_severity",
"weight": 419
},
{
"term": "device_id",
"weight": 412
},
{
"term": "device_os",
"weight": 412
},
{
"term": "device_policy",
"weight": 401
},
{
"term": "process_pid",
"weight": 311
},
{
"term": "process_hash",
"weight": 306
},
{
"term": "process_reputation",
"weight": 287
}
]
}
Add segments of text to an alert to track notes while investigating the potential threat.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.notes |
CREATE |
Request
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes
Request Body
{
"note": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
note REQUIRED
|
A segment of text to attach to the specified Alert | String | Max: 255 characters |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful creation of a note | application/json | View example response below |
400 | Bad request. | application/json | N/A |
404 | Resource not found | N/A | N/A |
500 | Internal server error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes
Request Body
{
"note": "This is an example"
}
Response
{
"author": "A569S6YYRE",
"create_time": "2020-09-14T13:56:26.429Z",
"id": "71d04030f69311eabf1ad95d2b04fece",
"note": "This is an example"
}
Fetch the notes created for the specified alert
Note: The UI console uses an older API currently so notes from the console will be associated with the threat_id instead of the alert_id. Therefore, the notes from the console will not be returned from this API.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.notes |
READ |
Request
GET <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful fetch of the notes | application/json | View example response below |
404 | Resource not found | N/A | N/A |
500 | Internal server error | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes
Response
{
"num_found": 1,
"results": [
{
"author": "A569S6YYRE",
"create_time": "2020-09-14T13:56:26.429Z",
"id": "71d04030f69311eabf1ad95d2b04fece",
"note": "This is an example"
}
]
}
Deletes the specified note for the specified alert
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.notes |
DELETE |
Request
DELETE <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes/{note_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successful delete of the note | No Content | View example response below |
404 | Resource not found | N/A | N/A |
500 | Internal server error | N/A | N/A |
Example
Request
DELETE https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/notes/71d04030f69311eabf1ad95d2b04fece
Response
No Content
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 |
|
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 |
|
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 |
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 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 |
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 |
|
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 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 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 |
|
watchlists |
List of watchlists associated with an alert | Array |
|