Alerts API

Introduction

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

Search Request

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

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

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

POST <psc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_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, VMWare, and Watchlist pathways, listed below.

Request Body 

{
    "criteria": {
        "category": ["<string>", "<string>"],
        "create_time": {
            "all_time": "<boolean>",
            "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>"],
        "reputation": ["<string>", "<string>"],
        "tag": ["<string>", "<string>"],
        "target_value": ["<string>", "<string>"],
        "threat_id": ["<string>", "<string>"],
        "type": ["<string>", "<string>"],
        "workflow": ["<string>", "<string>"],
    },
    "query": "<string>",
    "rows": "<long>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<long>"
}

Body Schema

Field Description Default Required
criteria Map of criteria to filter results on. Allowed values: target_value, not_blocked_threat_category, Device_os_version, policy_id, minimum_severity, legacy_alert_id, tag, id, run_state, threat_cause_vector,device_username, threat_id, device_id, device_os, create_time, kill_chain_status, group_results, process_sha256, policy_name, reputation, type, category, workflow, reason_code, device_name, process_name, blocked_threat_category, device_location, sensor_action, policy_applied N/A No
query query to perform search N/A No
rows For pagination, how many results to return 20 No
sort.field Field to sort the results by. Allowed values: first_event_time, last_event_time, severity, target_value N/A No
sort.order How to order the results. Allowed values: ASC, DESC N/A No
start For pagination, where to start retrieving results from 0 No

Additional Supported criteria Parameter Values

Pathway Additional Allowed Values
/v6/orgs/{org_key}/alerts/cbanalytics/_search blocked_threat_category, policy_applied, sensor_action, device_location, reason_code, kill_chain_status, not_blocked_threat_category, run_state, threat_cause_vector
v6/orgs/{org_key}/alerts/vmware/_search group_id
/v6/orgs/{org_key}/alerts/watchlist/_search report_id, watchlist_name, report_name, watchlist_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

POST https://defense-dev01.cbdtest.io/appservices/v6/orgs/ASDF1234/alerts/_search

Request Body 

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

    },
    "rows": 1,
    "start": 0
}

Response 

{
 "results": [
   {
     "id": "038894832709076d63111e99466f73575fcf3ca",
     "legacy_alert_id": "1DDU8H9N",
     "org_key": "ASDF1234",
     "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": 123,
     "device_os": "MAC",
     "device_os_version": "<OS Version>",
     "device_name": "<System-Name>",
     "device_username": "support@carbonblack.com",
     "policy_id": 1,
     "policy_name": "default",
     "target_value": "MISSION_CRITICAL"
    }
  ]
}

Get Single Alert by ID

Get a single alert using an ID.

RBAC Permissions Required

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

Request

GET <psc-hostname>/appservices/v6/org/{org_key}/alerts/{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/ASDF1234/alerts/225219783948647d55b11e9962bf3b07592c207

Response 

{
 "type": "CB_ANALYTICS",
 "id": "225219783948647d55b11e9962bf3b07592c207",
 "legacy_alert_id": "L1QDMJUO",
 "org_key": "ASDF1234",
 "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"
}

Facet Request

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

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

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

POST <psc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/_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, VMWare, and Watchlist pathways, listed below.

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>"],
        "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>"],
        "reputation": ["<string>", "<string>"],
        "tag": ["<string>", "<string>"],
        "target_value": ["<string>", "<string>"],
        "threat_id": ["<string>", "<string>"],
        "type": ["<string>", "<string>"],
        "workflow": ["<string>", "<string>"],
    },
    "query": "<string>",
    "terms": {
        "fields": ["<string>", "<string>"],
        "rows": "<integer>"
    }
}

Body Schema

Field Description Default Required
criteria Map of criteria to filter results on. Allowed values: threat_id, target_value, device_id, device_os_versions, policy_id, device_os, minimum_severity,create_time, legacy_alert_id,group_results,process_sha256,policy_name,reputation,type,id,category,device_username, device_name,tag,workflow,process_name N/A No
query query to perform facet search N/A No
terms.fields Alert facet type. Allowed values: policy_applied_state, device_id, policy_id, policy_applied, status, device_name, policy_name, reputation, tag, sensor_action, run_state, category, workflow, application_name, application_hash, alert_type N/A Yes
terms.rows For pagination, how many results to return 20 No

Additional Supported criteria Parameter Values

Pathway Additional Allowed Values
/v6/orgs/{org_key}/alerts/cbanalytics/_facet blocked_threat_category, policy_applied, sensor_action, device_location, reason_code, kill_chain_status, not_blocked_threat_category, run_state, threat_cause_vector
v6/orgs/{org_key}/alerts/vmware/_facet group_id
/v6/orgs/{org_key}/alerts/watchlist/_facet report_id, watchlist_name, report_name, watchlist_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

POST https://defense.conferdeploy.net/appservices/v6/orgs/ASDF1234/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": "VMWARE",
                   "name": "VMWARE"
               },
               {
                   "total": 0,
                   "id": "WATCHLIST",
                   "name": "WATCHLIST"
               }
           ]
       }
   ]
}

Get Status of Workflow Update

Get the current status of a workflow update request.

RBAC Permissions Required

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

Request

GET <psc-hostname>/appservices/v6/orgs/{org_key}/workflow/status/{requestId}

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/ASDF1234/workflow/status/{requestId}

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"
  }
 }

Update Single Event Workflow

Update the workflow of a single event.

RBAC Permissions Required

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

Request

POST <psc-hostname>/appservices/v6/orgs/{org_key}/alerts/{id}/workflow

Request Body 

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

Body Schema

Field Description Default Required
state Workflow state to filter on. Allowed values: dismissed, open N/A No
comment Comment to include with operation N/A No
remediation state Description or justification for the change. Accepts any string. N/A No

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/ASDF1234/alerts/{id}/workflow

Request Body 

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

Response 

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

Update Bulk Event Workflows

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

RBAC Permissions Required

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

Requests

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

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

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

POST <psc-hostname>/appservices/v6/orgs/{org_key}/alerts/watchlist/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, VMWare, and Watchlist pathways, listed below.

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 Description Default Required
criteria Map of criteria to filter results on. Allowed values: threat_id, target_value, device_id, device_os_versions, policy_id, device_os, minimum_severity,create_time, legacy_alert_id,group_results,process_sha256,policy_name,reputation,type,id,category,device_username, device_name,tag,workflow,process_name N/A No
query query to perform N/A No
state Workflow state to filter on. Allowed values: dismissed, open N/A No
comment Comment to include with operation N/A No
remediation state Description or justification for the change. Accepts any string. N/A No

Additional Supported criteria Parameter Values

Pathway Additional Allowed Values
/v6/orgs/{org_key}/alerts/cbanalytics/workflow/_criteria blocked_threat_category, policy_applied, sensor_action, device_location, reason_code, kill_chain_status, not_blocked_threat_category, run_state, threat_cause_vector
v6/orgs/{org_key}/alerts/vmware/workflow/_criteria group_id
/v6/orgs/{org_key}/alerts/watchlist/workflow/_criteria report_id, watchlist_name, report_name, watchlist_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

POST https://defense.conferdeploy.net/appservices/v6/orgs/ASDF1234/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 Suggestions

Get suggestions on keys and field values.

RBAC Permissions Required

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

Parameters

Name Description Default Required
suggest.q The query string for which you want completion suggestions. Leave this value blank, suggest.q=, to return all key suggestions. N/A Yes

Request

GET <psc-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/ASDF1234/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
       }
   ]
}

Last modified on March 2, 2020