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.Alert search request. Multiple pathways support similar request body schemas, including those listed below.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_search
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/_search
Below is an example request body for a request to /v6/orgs/{org_key}/alerts/_search
. Additional criteria
properties are available for the CbAnalytics, Device Control, and Watchlist pathways.
Request Body
{
"criteria": {
"category": ["<string>", "<string>"],
"create_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"device_id": ["<long>", "<long>"],
"device_name": ["<string>", "<string>"],
"device_os": ["<string>", "<string>"],
"device_os_version": ["<string>", "<string>"],
"device_username": ["<string>", "<string>"],
"first_event_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"group_results": "<boolean>",
"id": ["<string>", "<string>"],
"last_event_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"legacy_alert_id": ["<string>", "<string>"],
"minimum_severity": "<integer>",
"policy_id": ["<long>", "<long>"],
"policy_name": ["<string>", "<string>"],
"process_name": ["<string>", "<string>"],
"process_sha256": ["<string>", "<string>"],
"reputation": ["<string>", "<string>"],
"tag": ["<string>", "<string>"],
"target_value": ["<string>", "<string>"],
"threat_id": ["<string>", "<string>"],
"type": ["<string>", "<string>"],
"last_update_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"workflow": ["<string>", "<string>"],
},
"query": "<string>",
"rows": "<long>",
"sort": [
{
"field": "<string>",
"order": "<string>"
},
{
"field": "<string>",
"order": "<string>"
}
],
"start": "<long>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria |
Criteria is an object that represents values that must be in the results. | Object |
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 |
Time Criteria
Alert APIs support filtering via the create_time
, last_update_time
, first_event_time
, and last_event_time
criteria
fields.
These time criteria filters can use either the range
field or the start
and end
fields.
range
can be either all
(to indicate all time), or a specific duration specified as -[quantity][unit]
, where unit
is one of:
s
for secondsm
for minutesh
for hoursd
for daysw
for weeksy
for yearsstart
and end
are specified as ISO-8601 strings. start
must be less than end
.Additional Alert specific criteria
fields
Path | Allowed Fields |
---|---|
/v6/orgs/{org_key}/alerts/cbanalytics/_search |
blocked_threat_category , device_location , kill_chain_status , not_blocked_threat_category , policy_applied , reason_code , run_state , sensor_action , threat_cause_vector |
/v6/orgs/{org_key}/alerts/watchlist/_search |
report_id , report_name , watchlist_id , watchlist_name |
/v6/orgs/{org_key}/alerts/devicecontrol/_search |
external_device_friendly_name , external_device_id , product_id , product_name , serial_number , vendor_id , vendor_name |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/_search
Request Body
{
"criteria": {
"device_id": [388948],
"device_os": ["MAC"],
"device_os_version": ["10.14.6"],
"device_username": ["support@carbonblack.com"],
"group_results": false,
"id": ["038894832709076d63111e99466f73575fcf3ca"],
"minimum_severity": 3,
"policy_name": ["default"],
"process_name": ["IPv6-Off"]
},
"rows": 1,
"start": 1
}
Response
{
"num_found": 1,
"num_available": 1,
"results": [
{
"id": "038894832709076d63111e99466f73575fcf3ca",
"legacy_alert_id": "1DDU8H9N",
"type": "CB_ANALYTICS",
"org_key": "ABCD1234",
"create_time": "2019-09-13T14:17:21.668Z",
"last_update_time": "2019-09-13T14:17:21.668Z",
"first_event_time": "2019-09-13T14:16:55.878Z",
"last_event_time": "2019-09-13T14:16:55.878Z",
"threat_id": "b7ce4f79e8903c09d2cd6b615c965c9f",
"severity": 3,
"category": "MONITORED",
"device_id": 388948,
"device_os": "MAC",
"device_os_version": "10.14.6",
"device_name": "some-system",
"device_username": "support@carbonblack.com",
"policy_id": 1,
"policy_name": "default",
"target_value": "MISSION_CRITICAL"
}
]
}
NOTE: The response above has been abbreviated to show only the fields available in the Base Alert schema. Real responses will include the full alert body as defined by the different Alert Schemas.
Pagination
This API supports pagination via the rows
and start
parameters in the POST body and is limited to the first 10k
results.
They work as described in the API Basics pagination guide.
In the response, num_found
indicates the total number of hits for the search.
num_available
indicates the total number of retrievable hits for the search.
Not all results found are necessarily retrievable because deep pagination is limited for performance reasons.
When num_found
is greater than num_available
, consider adding more specific criteria to the request to retrieve more results.
Consuming all alerts
The best practice for a reliable, near-real-time stream of Alerts is through the Event 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 timestamp when the alerts datastore ingested the alert, which guarantees that once a time range has been queried no new alerts will be added into that same bucket.
Keep in mind the requested rows
count and the returned num_found
in the response.
Pagination may still be required when using the last_update_time
filter due to large alert volumes.
Get a single alert using an ID.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Request
GET <cbc-hostname>/appservices/v6/org/{org_key}/alerts/{alert_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207
Response
{
"type": "CB_ANALYTICS",
"id": "225219783948647d55b11e9962bf3b07592c207",
"legacy_alert_id": "L1QDMJUO",
"org_key": "ABCD1234",
"create_time": "2019-09-12T12:47:45.595Z",
"last_update_time": "2019-09-12T12:47:45.595Z",
"first_event_time": "2019-09-12T12:47:36.703Z",
"last_event_time": "2019-09-12T12:47:36.703Z",
"threat_id": "e7ba0f751456211fea35b9d955dc5098",
"severity": 7,
"category": "THREAT",
"device_id": "<device-id>",
"device_os": "<device-os>",
"device_os_version": "<device-os>",
"device_name": "<device-name>",
"device_username": "<device-username>",
"policy_id": 1,
"policy_name": "default",
"target_value": "MISSION_CRITICAL"
}
NOTE: The response above has been abbreviated to show only the fields available in the Base Alert schema. Real responses will include the full alert body as defined by the different Alert Schemas.
Alert facets search request. Multiple pathways support similar request body schemas, including those listed below.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts |
READ |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/_facet
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/_facet
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_facet
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/_facet
Below is an example request body for a request to /v6/orgs/{org_key}/alerts/_facet
. Additional criteria
properties are available for the CbAnalytics, Device Control, and Watchlist pathways.
Request Body
{
"criteria": {
"category": ["<string>", "<string>"],
"create_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"device_id": ["<long>", "<long>"],
"device_name": ["<string>", "<string>"],
"device_os": ["<string>", "<string>"],
"device_os_version": ["<string>", "<string>"],
"device_username": ["<string>", "<string>"],
"first_event_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"group_results": "<boolean>",
"id": ["<string>", "<string>"],
"last_event_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"legacy_alert_id": ["<string>", "<string>"],
"minimum_severity": "<integer>",
"policy_id": ["<long>", "<long>"],
"policy_name": ["<string>", "<string>"],
"process_name": ["<string>", "<string>"],
"process_sha256": ["<string>", "<string>"],
"reputation": ["<string>", "<string>"],
"tag": ["<string>", "<string>"],
"target_value": ["<string>", "<string>"],
"threat_id": ["<string>", "<string>"],
"type": ["<string>", "<string>"],
"last_update_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"workflow": ["<string>", "<string>"],
},
"query": "<string>",
"terms": {
"fields": ["<string>", "<string>"],
"rows": "<integer>"
}
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria |
Criteria is an object that represents values that must be in the results. | Object |
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 |
Time Criteria
Alert APIs support filtering via the create_time
, last_update_time
, first_event_time
, and last_event_time
criteria
fields.
These time criteria filters can use either the range
field or the start
and end
fields.
range
can be either all
(to indicate all time), or a specific duration specified as -[quantity][unit]
, where unit
is one of:
s
for secondsm
for minutesh
for hoursd
for daysw
for weeksy
for yearsstart
and end
are specified as ISO-8601 strings. start
must be less than end
.Fields Available for Faceting
Field | Definition | Values |
---|---|---|
ALERT_TYPE |
Type | CB_ANALYTICS , WATCHLIST , etc. |
CATEGORY |
Category | THREAT , MONITORED |
REPUTATION |
Reputation of the primary involved process | KNOWN_MALWARE , NOT_LISTED , etc. |
WORKFLOW |
Alert dismissal state | OPEN , DISMISSED |
TAG |
User-defined Tags | N/A |
POLICY_ID |
Policy ID | N/A |
POLICY_NAME |
Policy Name | N/A |
DEVICE_ID |
Device ID | N/A |
DEVICE_NAME |
Device Name | N/A |
APPLICATION_HASH |
SHA256 Hash of the primary involved process | N/A |
APPLICATION_NAME |
Name involved process | N/A |
RUN_STATE |
Whether the process ran | RAN , DID_NOT_RUN |
POLICY_APPLIED |
Whether a policy was applied | APPLIED , NOT_APPLIED |
SENSOR_ACTION |
Action taken by the sensor | ALLOW , DENY , TERMINATE , etc. |
Additional Alert specific criteria
fields
Path | Allowed Fields |
---|---|
/v6/orgs/{org_key}/alerts/cbanalytics/_facet |
blocked_threat_category , device_location , kill_chain_status , not_blocked_threat_category , policy_applied , reason_code , run_state , sensor_action , threat_cause_vector |
/v6/orgs/{org_key}/alerts/watchlist/_facet |
report_id , report_name , watchlist_id , watchlist_name |
/v6/orgs/{org_key}/alerts/devicecontrol/_facet |
external_device_friendly_name , external_device_id , product_id , product_name , serial_number , vendor_id , vendor_name |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/_facet
Request Body
{
"criteria": {
"category": ["THREAT", "INFO"],
},
"terms": {
"fields": ["ALERT_TYPE"],
"rows": 50
}
}
Response
{
"results": [
{
"field": "alert_type",
"values": [
{
"total": 587,
"id": "CB_ANALYTICS",
"name": "CB_ANALYTICS"
},
{
"total": 0,
"id": "WATCHLIST",
"name": "WATCHLIST"
}
]
}
]
}
Update the alert with the current state of the remediation.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Request
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/{alert_id}/workflow
Request Body
{
"state": "<string>",
"comment": "<string>",
"remediation_state": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
state REQUIRED
|
Workflow state to set. | String | DISMISSED , OPEN |
comment |
Comment to include with the operation | String | N/A |
remediation_state |
Description or justification for the change. | String | Accepts any string |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/225219783948647d55b11e9962bf3b07592c207/workflow
Request Body
{
"state": "OPEN",
"comment": "This is an example",
"remediation_state": "NOTHING"
}
Response
{
"state": "OPEN",
"remediation": "NOTHING",
"last_update_time": "2020-09-14T15:02:04.620Z",
"comment": "This is an example",
"changed_by": "A569S6YYRE"
}
Bulk update alerts’ workflow by search definition. Multiple pathways support similar request body schemas, including those listed below.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.alerts.dismiss |
EXECUTE |
Requests
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/workflow/_criteria
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/cbanalytics/workflow/_criteria
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/workflow/_criteria
POST <cbc-hostname>/appservices/v6/orgs/{org_key}/alerts/devicecontrol/workflow/_criteria
Below is an example request body for a request to v6/orgs/{org_key}/alerts/workflow/_criteria
. Additional criteria
properties are available for the CbAnalytics, Device Control, and Watchlist pathways.
Request Body
{
"state": "<string>",
"comment": "<string>",
"criteria": {
"category": ["<string>", "<string>"],
"create_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"device_id": ["<long>", "<long>"],
"device_name": ["<string>", "<string>"],
"device_os": ["<string>", "<string>"],
"device_os_version": ["<string>", "<string>"],
"device_username": ["<string>", "<string>"],
"group_results": "<boolean>",
"id": ["<string>", "<string>"],
"legacy_alert_id": ["<string>", "<string>"],
"minimum_severity": "<integer>",
"policy_id": ["<long>", "<long>"],
"policy_name": ["<string>", "<string>"],
"process_name": ["<string>", "<string>"],
"process_sha256": ["<string>", "<string>"],
"report_id": ["<string>", "<string>"],
"report_name": ["<string>", "<string>"],
"reputation": ["<string>", "<string>"],
"tag": ["<string>", "<string>"],
"target_value": ["<string>", "<string>"],
"threat_id": ["<string>", "<string>"],
"type": ["<string>", "<string>"],
"watchlist_id": ["<string>", "<string>"],
"watchlist_name": ["<string>", "<string>"],
"workflow": ["<string>", "<string>"],
},
"query": "<string>",
"remediation_state": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria |
Criteria is an object that represents values that must be in the results. | Object |
category ,
create_time ,
device_id ,
device_name ,
device_os_version ,
device_os ,
first_event_time ,
group_results ,
id ,
last_event_time
legacy_alert_id ,
minimum_severity ,
policy_id ,
policy_name ,
process_name ,
process_sha256 ,
reputation ,
tag ,
target_value ,
device_username ,
threat_id ,
type ,
workflow |
query |
Query in lucene syntax and/or including value searches. | String | N/A |
state REQUIRED
|
Workflow state to filter on. | String | DISMISSED , OPEN |
comment |
Comment to include with the operation | String | N/A |
remediation_state |
Description or justification for the change. | String | Accepts any string |
Additional Alert specific criteria
fields
Path | Allowed Fields |
---|---|
/v6/orgs/{org_key}/alerts/cbanalytics/workflow/_criteria |
blocked_threat_category , device_location , kill_chain_status , not_blocked_threat_category , policy_applied , reason_code , run_state , sensor_action , threat_cause_vector |
/v6/orgs/{org_key}/alerts/watchlist/workflow/_criteria |
report_id , report_name , watchlist_id , watchlist_name |
/v6/orgs/{org_key}/alerts/devicecontrol/workflow/_criteria |
external_device_friendly_name , external_device_id , product_id , product_name , serial_number , vendor_id , vendor_name |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful Request | application/json | View example response below |
400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/alerts/watchlist/workflow/_criteria
Request Body
{
"comment": "string",
"criteria": {
"category": ["THREAT"],
"create_time": {
"end": "2019-09-17T00:03:47.277Z",
"start": "2019-09-17T00:03:47.277Z"
},
"device_id": [324552, 12344, 997745],
"device_name": ["hostmachine", "device.local", "DOMAIN\\DEVICE"],
"device_os": ["WINDOWS"],
"device_os_version": ["string"],
"device_username": ["string"],
"group_results": true,
"id": ["string"],
"legacy_alert_id": ["CTAS5XKG", "TJFY5ZBW"],
"minimum_severity": 5,
"policy_id": [1, 525, 644],
"policy_name": ["Default", "Advanced", "Monitored"],
"process_name": ["explorer.exe", "chrome.app", "setup.py"],
"process_sha256": ["131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267"],
"report_id": ["string"],
"report_name": ["string"],
"reputation": ["KNOWN_MALWARE"],
"tag": ["string"],
"target_value": ["LOW"],
"threat_id": ["03ea43268c536a0bde8b765bca1696e9", "41edc35062138af3f1fea4b3bf7046a5"],
"type": ["CB_ANALYTICS"],
"watchlist_id": ["string"],
"watchlist_name": ["string"],
"workflow": ["OPEN"],
},
"query": "string",
"remediation_state": "string",
"state": "OPEN"
}
Response
{
"request_id": "14617a6cd8df11e9974f1d8882e43ec1"
}
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 | String | ISO 8601 timestamp |
device_id |
The identifier assigned by Carbon Black Cloud to the device associated with the alert. | Integer | N/A |
device_name |
The hostname of the device associated with the alert. | String | N/A |
device_os |
The operating system of the device associated with the alert | String | WINDOWS , MAC , LINUX , OTHER |
device_os_version |
The operating system and version on the device | String | N/A |
device_username |
The username of the logged on user during the alert. If the user is not available then it may be populated with the device owner | String | N/A |
first_event_time |
The time of the first event associated with the alert | String | ISO 8601 timestamp |
group_details |
Details about a group of alerts when “Group Alerts” is enabled in the search request | Object |
|
id |
The identifier for the alert | String | N/A |
last_event_time |
The time of the latest event associated with the alert | String | ISO 8601 timestamp |
last_update_time |
The last time the alert was updated | String | ISO 8601 timestamp |
legacy_alert_id |
Unique short id for the alerts to support easier consumption in the UI console. Use the id for API requests |
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 |
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 |
Process name or IP address of the threat actor | String | N/A |
threat_cause_actor_process_pid |
Process identifier (PID) of the actor process | String | N/A |
threat_cause_actor_sha256 |
SHA256 of the threat cause actor | String | N/A |
threat_cause_event_id |
ID of the Event that triggered the threat | String | N/A |
threat_cause_reputation |
Reputation of the threat cause | String | KNOWN_MALWARE , SUSPECT_MALWARE , PUP , NOT_LISTED , ADAPTIVE_WHITE_LIST , COMMON_WHITE_LIST , TRUSTED_WHITE_LIST , COMPANY_BLACK_LIST |
threat_cause_threat_category |
Category of the threat cause | String | UNKNOWN , NON_MALWARE , NEW_MALWARE , KNOWN_MALWARE , RISKY_PROGRAM |
threat_cause_vector |
The source of the threat cause | String | EMAIL , WEB , GENERIC_SERVER , GENERIC_CLIENT , REMOTE_DRIVE , REMOVABLE_MEDIA , UNKNOWN , APP_STORE , THIRD_PARTY |
threat_indicators |
List of the threat indicators that make up the threat | Array |
|
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 |
---|---|---|---|
reason |
Description of the alert | String | N/A |
reason_code |
Shorthand enum for the full-text reason | String | N/A |
device_location |
Whether the device was on or off premise when the alert started | String | ONSITE , OFFSITE , UNKNOWN |
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_cause_event_id |
ID of the Event that triggered the threat | 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 , TERMINATE , DENY |
run_state |
Whether the threat in the alert ran | String | DID_NOT_RUN , RAN , UNKNOWN |
policy_applied |
Whether a policy was applied | String | APPLIED , NOT_APPLIED |
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 |
product_name |
The name of the USB device’s product | String | N/A |
product_id |
The hexadecimal id of the USB device’s product | String | 0x5581 |
external_device_friendly_name |
The human readable USB device name | String | N/A |
serial_number |
The serial number of the USB device | String | N/A |
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 |
Process name or IP address of the threat actor | String | N/A |
threat_cause_actor_sha256 |
SHA256 of the threat cause actor | 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 |
|