Alerts API

Overview

In Alerts v7 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, type, status, tag and more, as well as the ability to close alerts.


Use Cases

  • Poll for Alerts that meet specific criteria to ingest into a SIEM
  • Use the workflow APIs with SOAR products to synchronize status
  • Use the Facet endpoints to find frequently and rarely occurring values to direct investigations

Requirements

  • Any Carbon Black Cloud product
  • Some Alert Types are only generated by specific products

Key Features

  • Extended alert schema with additional metadata such as process command line and username, parent and child process information, netconn data, additional device fields, MITRE categorization when available, and more
  • Easier management and consumption of grouped alerts
  • Ability to mark alerts as “In Progress”
  • Ability to mark alerts as True Positive or False Positive
  • Additional fields available for both searching and faceting
  • Enhanced note management with the ability to add notes to both individual alerts and threats (alerts grouped by threat)
  • Observed Alerts have been removed from the Alerts API as these events are not considered actionable threats. They can now be called from the Observations API. For more information about this, see the announcement on Carbon Black Tech Zone.

Guides and Resources


Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes/{id}
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_validate
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_histogram
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/history
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_search
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_export
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags/{tag}
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/search_suggestions
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes/{id}
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_histogram
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/workflow
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_facet
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/history
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_search
  • {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_facet

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

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


API Calls

Calls are grouped based on the object they operate on such as Alert, Threat or Alert grouped by threat_id.

Common Request Attributes


Time Range Filter

The alerts api exposes several timestamp fields which can be filtered using the common time filter object. The time filter object can be defined with either start and end OR range. Supplying range with any other parameters is invalid.

Requests that accept time_range as a top-level parameter

Requests that accept time_range as a top-level parameter always filter by this field.

  • If it is not supplied in the request, the default value is "range": "-2w", i.e. the previous two weeks
  • For a longer or shorter period, specify a value for time_range

The time_range applies the filter to backend_timestamp. This is the timestamp when the Carbon Black Cloud processed the alert and made it available in searches. It corresponds to the Created column on the Alerts page.

When other timestamp fields are included in the criteria of a request, that filter is applied to records within the time_range period.

backend_timestamp is not valid in criteria; only as the top-level time_range parameter.

Field Definition Data Type Example
start The lower bound of the time range. Requires end and must be a timestamp before end. ISO 8601 Date String 2023-04-01T00:00:00.000Z
end The upper bound of the time range Requires start and must be a timestamp after start ISO 8601 Date String 2023-04-15T00:00:00.000Z
range Relative time range for the request (defined below) String -2w

The format of range is -<quantity><units> where quantity is an integer, and units is one of:

  • M: month(s)
  • w: week(s)
  • d: day(s)
  • h: hour(s)
  • m: minute(s)
  • s: second(s)

Examples

A 2-week query using explicit start and end timestamps 
{
  "start": "2023-04-01T00:00:00.000Z",
  "end": "2023-04-15T00:00:00.000Z"
}
A 2-week query using a relative range 
{
  "range": "-2w",
}

Pagination

All routes with start and rows support pagination:

  • start is a one-based index of the first result to retrieve. It must be a whole number greater than or equal to 1.
  • rows is the number of results to return. It must be a whole number greater than or equal to 0. A value of "rows": 0 will fetch only the count of matching results.

Only the first 10,000 results of any search are accessible. That means start + rows must be less than 10,000. To access rows beyond the first 10,000, apply additional filters to reduce the result count.


Individual Alert Operations

The calls in this section search for and operate on individual alerts. Compare with endpoints in Search Grouped Alerts which operates on alert_groups.

Get Alert by ID

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{id}

Response Codes

Code Description Content-Type Content
200 Alert successfully retrieved application/json See example below.
For all fields returned for each alert type see Search Fields - Alerts
404 Alert does not exist application/json 
{
    "error_code": "NOT_FOUND",
    "message": "Failed to look up alert, orgKey: ABCD1234, alert id: id_does_not_exist_demo",
    "org_key": "ABCD1234",
    "resource_type": "Alert"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aa
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "org_key": "ABCD1234",
    "alert_url": "https://defense.conferdeploy.net/alerts?s[c][query_string]=id:52fa009d-e2d1-4118-8a8d-04f521ae66aa&orgKey=ABCD1234",
    "id": "12ab345cd6-e2d1-4118-8a8d-04f521ae66aa",
    "type": "WATCHLIST",
    "backend_timestamp": "2023-04-14T21:30:40.570Z",
    "user_update_timestamp": null,
    "backend_update_timestamp": "2023-04-14T21:30:40.570Z",
    "detection_timestamp": "2023-04-14T21:27:14.719Z",
    "first_event_timestamp": "2023-04-14T21:21:42.193Z",
    "last_event_timestamp": "2023-04-14T21:21:42.193Z",
    "severity": 8,
    "reason": "Process infdefaultinstall.exe was detected by the report \"Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall\" in 6 watchlists",
    "reason_code": "05696200-88e6-3691-a1e3-8d9a64dbc24e:7828aec8-8502-3a43-ae68-41b5050dab5b",
    "threat_id": "0569620088E6669121E38D9A64DBC24E",
    "primary_event_id": "-7RlZFHcSGWKSrF55B_4Ig-0",
    "policy_applied": "NOT_APPLIED",
    "run_state": "RAN",
    "sensor_action": "ALLOW",
    "workflow": {
        "change_timestamp": "2023-04-14T21:30:40.570Z",
        "changed_by_type": "SYSTEM",
        "changed_by": "ALERT_CREATION",
        "closure_reason": "NO_REASON",
        "status": "OPEN"
    },
    "determination": null,
    "tags": [
        "tag1",
        "tag2"
    ],
    "alert_notes_present": false,
    "threat_notes_present": false,
    "is_updated": false,
    "device_id": 18118174,
    "device_name": "pscr-test-01-1677785028.620244-9",
    "device_uem_id": "",
    "device_target_value": "LOW",
    "device_policy": "123abcde-c21b-4d64-9e3e-53595ef9c7af",
    "device_policy_id": 1234567,
    "device_os": "WINDOWS",
    "device_os_version": "Windows 10 x64 SP: 1",
    "device_username": "demouser@demoorg.com",
    "device_location": "UNKNOWN",
    "device_external_ip": "1.2.3.4",
    "mdr_alert": false,
    "report_id": "oJFtoawGS92fVMXlELC1Ow-b4ee93fc-ec58-436a-a940-b4d33a613513",
    "report_name": "Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall",
    "report_description": "\n\nThreat:\nThis behavior may be abused by adversaries to execute malicious files that could bypass application whitelisting and signature validation on systems.\n\nFalse Positives:\nSome environments may legitimate use this, but should be rare.\n\nScore:\n85",
    "report_tags": [
        "attack",
        "attackframework",
        "threathunting"
    ],
    "report_link": "https://attack.mitre.org/wiki/Technique/T1218",
    "ioc_id": "b4ee93fc-ec58-436a-a940-b4d33a613513-0",
    "ioc_hit": "((process_name:InfDefaultInstall.exe)) -enriched:true",
    "watchlists": [
        {
            "id": "9x0timurQkqP7FBKX4XrUw",
            "name": "Carbon Black Advanced Threats"
        }
    ],
    "process_guid": "ABCD1234-0114761e-00002ae4-00000000-19db1ded53e8000",
    "process_pid": 10980,
    "process_name": "infdefaultinstall.exe",
    "process_sha256": "1a2345cd88666a458f804e5d0fe925a9f55cf016733458c58c1980addc44cd774",
    "process_md5": "12c34567894a49f13193513b0138f72a9",
    "process_effective_reputation": "LOCAL_WHITE",
    "process_reputation": "NOT_LISTED",
    "process_cmdline": "InfDefaultInstall.exe C:\\Users\\username\\userdir\\Infdefaultinstall.inf",
    "process_username": "DEMO\\DEMOUSER",
    "process_issuer": "Demo Code Signing CA - G2",
    "process_publisher": "Demo Test Authority",
    "childproc_guid": "",
    "childproc_username": "",
    "childproc_cmdline": "",
    "ml_classification_final_verdict": "NOT_ANOMALOUS",
    "ml_classification_global_prevalence": "LOW",
    "ml_classification_org_prevalence": "LOW"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Find Alerts

Search for alerts using query, criteria and exclusion operators.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_search

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "start": <integer>,
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
start Integer See Alerts API - Pagination
rows Integer See Alerts API - Pagination
sort Object See Alerts API - Find Alerts - Alert Sorting

Response Codes

Code Description Content-Type Content
200 Successful search request application/json See example below.
For all fields returned for each alert type see Search Fields - Alerts

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "time_range": {
        "range": "-2w"
    },
    "criteria": {
        "minimum_severity": 2,
        "device_os": [
            "WINDOWS"
        ]
    },
    "exclusions": {
        "type": [
            "WATCHLIST"
        ],
        "device_os_version": [
            "Windows 10 x64 SP: 1"
        ]
    },
    "start": "1",
    "rows": "1",
    "sort": [
        {
            "field": "severity",
            "order": "DESC"
        }
    ]
}
Response Body 
{
    "results": [
        {
            "org_key": "ABCD1234",
            "alert_url": "https://defense.conferdeploy.net/alerts?s[c][query_string]=id:708d7dbf-2020-42d4-9cbc-0cddd0ffa31a&orgKey=ABCD1234",
            "id": "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a",
            "type": "WATCHLIST",
            "backend_timestamp": "2023-04-03T08:48:47.211Z",
            "user_update_timestamp": "2023-04-13T11:55:20.860Z",
            "backend_update_timestamp": "2023-04-03T08:48:47.211Z",
            "detection_timestamp": "2023-04-03T08:46:52.302Z",
            "first_event_timestamp": "2023-04-03T08:44:43.552Z",
            "last_event_timestamp": "2023-04-03T08:44:43.552Z",
            "severity": 6,
            "reason": "Process taskhostw.exe was detected by the report \"Abnormally Large DNS Exchanges (exfil or zone transfer)\" in watchlist \"zzz_XDR Sample IOCs\"",
            "reason_code": "19261158-dbbf-3077-9959-f8aa7f7551a1:0cc402b0-ea96-35c6-8418-a2f07acf616d",
            "threat_id": "19261158DBBF00775959F8AA7F7551A1",
            "primary_event_id": "t6a_TNVuQb6seMjk_VyDsg-0",
            "policy_applied": "NOT_APPLIED",
            "run_state": "RAN",
            "sensor_action": "ALLOW",
            "workflow": {
                "change_timestamp": "2023-04-13T11:55:20.860Z",
                "changed_by_type": "USER",
                "changed_by": "demouser@demoorg.com",
                "closure_reason": "NO_REASON",
                "status": "IN_PROGRESS"
            },
            "determination": {
                "change_timestamp": "1970-01-01T00:00:00.000Z",
                "value": "ALERT_CLASSIFICATION_UNKNOWN",
                "changed_by_type": "OPERATOR_UNKNOWN",
                "changed_by": null
            },
            "tags": null,
            "alert_notes_present": false,
            "threat_notes_present": false,
            "is_updated": false,
            "device_id": 18078555,
            "device_name": "DEMO\\DEMOMACHINE",
            "device_uem_id": "",
            "device_target_value": "MEDIUM",
            "device_policy": "Demo-policy",
            "device_policy_id": 12345678,
            "device_os": "WINDOWS",
            "device_os_version": "Windows 10 x64",
            "device_username": "DEMOMACHINE\\Administrator",
            "device_location": "UNKNOWN",
            "device_external_ip": "1.2.3.4",
            "device_internal_ip": "1.2.3.4",
            "mdr_alert": false,
            "report_id": "Fm0YsPDyQ1Kp1Pdd6Lnd8w-abd-defg-123",
            "report_name": "Abnormally Large DNS Exchanges (exfil or zone transfer)",
            "report_description": "IOC leveraging XDR fields to identify abnormally large DNS exchanges. The typical client DNS query to your DNS server is between 50-550 bytes. Large exchanges could be indicative of attack exfiltration or zone transfer attempts.",
            "report_tags": [],
            "ioc_id": "abd-defg-123",
            "ioc_hit": "netconn_application_protocol:DNS AND netconn_bytes_sent:[551 TO *]",
            "watchlists": [
                {
                    "id": "lgaClyOmQ86ZwZttq3ZDxg",
                    "name": "Demo IOCs"
                }
            ],
            "process_guid": "ABCD1234-0113db5b-000011bc-00000000-1d966088928e609",
            "process_pid": 4540,
            "process_name": "c:\\windows\\system32\\taskhostw.exe",
            "process_sha256": "1234cd567ab3a577c4a13b907ad7375d27e74880b63f7371384f67d19197a0ad",
            "process_md5": "123a4566ab18f93b93d551cd10c1598e",
            "process_effective_reputation": "COMPANY_WHITE_LIST",
            "process_reputation": "TRUSTED_WHITE_LIST",
            "process_cmdline": "taskhostw.exe SYSTEM",
            "process_username": "DEMOSERVER\\DEMO",
            "process_issuer_": "Demo CA",
            "process_publisher": "Demo Publisher",
            "parent_guid": "ABCD1234-0113db5b-000006bc-00000000-1d94225f1bb0897",
            "parent_pid": 1724,
            "parent_name": "c:\\windows\\system32\\svchost.exe",
            "parent_sha256": "123ab451a82e0272c97c2a59f6020970d881af19c0ad5029db9c958c13b6558c7",
            "parent_md5": "a123456789f632dc8d9404d83bc16316",
            "parent_effective_reputation": "TRUSTED_WHITE_LIST",
            "parent_reputation": "TRUSTED_WHITE_LIST",
            "parent_cmdline": "C:\\Windows\\system32\\svchost.exe -k netsvcs -p -s Schedule",
            "parent_username": "NT AUTHORITY\\SYSTEM",
            "childproc_guid": "",
            "childproc_username": "",
            "childproc_cmdline": "",
            "ml_classification_anomalies": [
                {
                    "anomalous_field": "actor_process_modload_count",
                    "anomaly_name": "Process modloads",
                    "anomalous_field_baseline_values": [ "0", "1" ],
                    "anomalous_value": "65"
                },
                {
                    "anomalous_field": "actor_process_filemod_count",
                    "anomaly_name": "Process filemods",
                    "anomalous_field_baseline_values": [ "0" ],
                    "anomalous_value": "8"
                }
            ]
        }
    ],
    "num_found": 147,
    "num_available": 147
}
To download or review the Carbon Black Cloud Postman collection, click here.
By using the following the example, you can retrieve the first 5 [:5] alerts that have a minimum severity level of 7.

Code 
from cbc_sdk import CBCloudAPI
from cbc_sdk.platform import Alert
api = CBCloudAPI(profile='sample')

# Most search criteria use the add_criteria(key, [values]) function. 
# alerts = api.select(Alert).add_criteria("device_id", [123, 456])

# Fields that take a single value such as minimum_severity have dedicated set methods.
alerts = api.select(Alert).set_minimum_severity(7)[:5]

print(alerts[0].id, alerts[0].device_os, alerts[0].device_name)
Result 
d689e626-5d6a-<truncated> WINDOWS Alert-WinTest
View the full Alerts SDK sample script here. To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Alert Sorting

Requests can be sorted with the sort parameter. sort accepts a list of sort definitions like this: 

{
  ...other request parameters...
  "sort": [
    {
      "field": "primary_field",
      "order": "DESC"
    },
    {
      "field": "tiebreak_field",
      "order": "DESC"
    }
  ]
}

Field Definition Data Type Values
field field to sort on String backend_timestamp, user_update_timestamp, backend_update_timestamp, detection_timestamp, first_event_timestamp, last_event_timestamp, severity, workflow_change_timestamp, device_target_value, mdr_workflow_change_timestamp, workload_name
order order to sort String ASC (Ascending), DESC (Descending)

Export Alerts

Export Alerts in csv format. This is an asynchronous request which enables up to 25,000 records to be exported in each request.

  1. Use the Export Alerts endpoint defined here to create a job with required search criteria to limit the results. A job_id is returned.
    • This job may take up to 5 minutes to complete.
  2. Optionally, use Get Job Progress to check whether the job has completed.
  3. Use the job_id in the Download Job Output endpoint in the Jobs Service to get the results. The Download Job API requires the permission jobs.status - READ.
    • If more than 25,000 records matched the criteria, the first 25,000 are returned, sorted by backend_timestamp in descending order.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments
Carbon Black Cloud jobs.status READ Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_export

Request Body - application/json

{
"query": "<string>",
"time_range": {
  "start": "<string>",
  "end": "<string>",
  "range": "<string>"
},
"criteria": { "<object>" },
"exclusions": { "<object>" },
"format": "<string>",
"fields": ["<string>"]
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
format String The format of the export. Valid value is CSV.
fields Object A list of fields to include in the results. The default is to return all fields. Any alert field is able to be selected - see Search Fields - Alerts

Response Codes

Code Description Content-Type Content
200 Successful export request application/json 
{
    "job_id": "<string>"
}


Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Start Export Alerts Request Body 
{
    "time_range": {
        "range": "-1d"
    },
    "criteria": {
        "minimum_severity": 2,
        "type": ["WATCHLIST"]
    },
    "format": "CSV"
}
Response Body 
 {
    "job_id": "12345678"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Examples

Request 
GET https://defense.conferdeploy.net/jobs/v1/orgs/ABCD1234/jobs/12345678/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Download Export Alerts Result Request Body Download Job Output in CSV Format 
alert_notes_present,alert_url,asset_group,asset_id,attack_tactic,attack_technique,backend_timestamp,backend_update_timestamp,blocked_effective_reputation,blocked_md5,blocked_name,blocked_sha256,childproc_cmdline,childproc_effective_reputation,childproc_guid,childproc_md5,childproc_name,childproc_sha256,childproc_username,chrome_device_id,connection_type,container_id,container_image_hash,container_image_name,container_name,detection_timestamp,determination_change_timestamp,determination_changed_by,determination_changed_by_type,determination_value,device_external_ip,device_id,device_internal_ip,device_location,device_name,device_os,device_os_version,device_policy,device_policy_id,device_target_value,device_uem_id,device_username,egress_group_id,egress_group_name,external_device_friendly_name,first_event_timestamp,id,ioc_field,ioc_hit,ioc_id,ip_reputation,is_updated,k8s_cluster,k8s_kind,k8s_namespace,k8s_pod_name,k8s_policy,k8s_policy_id,k8s_rule,k8s_rule_id,k8s_workload_name,last_event_timestamp,mdr_alert,mdr_alert_notes_present,mdr_determination_value,mdr_threat_notes_present,mdr_workflow_is_assigned,mdr_workflow_status,ml_classification_anomalies,ml_classification_final_verdict,ml_classification_global_prevalence,ml_classification_org_prevalence,netconn_local_ip,netconn_local_ipv4,netconn_local_ipv6,netconn_local_port,netconn_protocol,netconn_remote_domain,netconn_remote_ip,netconn_remote_ipv4,netconn_remote_ipv6,netconn_remote_port,org_key,parent_cmdline,parent_effective_reputation,parent_guid,parent_md5,parent_name,parent_pid,parent_reputation,parent_sha256,parent_username,policy_applied,primary_event_id,process_cmdline,process_container_pid,process_effective_reputation,process_guid,process_issuer,process_md5,process_name,process_pid,process_publisher,process_reputation,process_sha256,process_username,product_id,product_name,reason,reason_code,remote_is_private,remote_k8s_kind,remote_k8s_namespace,remote_k8s_pod_name,remote_k8s_workload_name,report_description,report_id,report_link,report_name,report_tags,rule_category_id,rule_config_category,rule_config_id,rule_config_name,rule_id,run_state,sensor_action,serial_number,severity,tags,threat_hunt_id,threat_hunt_name,threat_id,threat_name,threat_notes_present,tms_rule_id,ttps,type,user_update_timestamp,vendor_id,vendor_name,watchlists,workflow_change_timestamp,workflow_changed_by,workflow_changed_by_rule_id,workflow_changed_by_type,workflow_closure_reason,workflow_status
false,defense.conferdeploy.net/alerts?s[c][query_string]=id:4870e071-9c7d-4147-b00d-0be988ff920a&orgKey=ABCD1234,,,,,2024-05-28T13:27:23.815596681Z,2024-05-28T13:27:23.815596681Z,,,,,,,,,,,,,,,,,,2024-05-28T13:24:28.335Z,2024-05-28T13:27:23.815596681Z,,,NONE,1.2.3.4,18741265,10.203.101.185,UNKNOWN,DEMO-WIN,WINDOWS,Windows 10 x64,Standard,165700,MEDIUM,,,,,,2024-05-28T13:20:42.954Z,4870e071-9c7d-4147-b00d-0be988ff920a,,(process_name:dllhost.exe) AND process_publisher_state:FILE_SIGNATURE_STATE_VERIFIED ,529de965-e1f6-4e7d-a37e-9e392da29740,,false,,,,,,1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9,,627bbdfe-55a7-3100-89bc-25d618fb9684,,2024-05-28T13:20:42.954Z,false,false,,false,false,,,,,,,,,0,,,,,,0,ABCD1234,C:\WINDOWS\system32\svchost.exe -k DcomLaunch -p,TRUSTED_WHITE_LIST,ABCD1234-011df811-00000330-00000000-1daa67e691ecdb8,7469cc568ad6821fd9d925542730a7d8,c:\windows\system32\svchost.exe,816,TRUSTED_WHITE_LIST,,NT AUTHORITY\SYSTEM,NOT_APPLIED,1yR4WspiQUmlqaWJRHV9eg-0,C:\WINDOWS\system32\DllHost.exe /Processid:{973D20D7-562D-44B9-B70B-5A0F49CCDF3F},0,TRUSTED_WHITE_LIST,ABCD1234-011df811-00001c44-00000000-1daa67eb00776e6,[Microsoft Windows Production PCA 2011],dfe1e4b1b8714cbe1005ee9413c2bae9,c:\windows\system32\dllhost.exe,7236,[Microsoft Windows],TRUSTED_WHITE_LIST,0309834d40475ccd5a88c48f7ff5ec62e5c6798900357dd83665c3d0345124e0,DEMO-WIN\DEMO-DOMAIN,,,"Process dllhost.exe was detected by the report ""demo-report"" in watchlist ""demo-watchlist""",1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9:627bbdfe-55a7-3100-89bc-25d618fb9684,false,,,,,,Q0O2FxEWSy2fSSYxEs2Pg,,demo-report,,1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9,,,,627bbdfe-55a7-3100-89bc-25d618fb9684,RAN,ALLOW,,5,,,,1B32B7CF7C3D40F117B46EC2E39530C9,,true,,,WATCHLIST,,,,,2024-05-28T13:27:23.815596681Z,ALERT_CREATION,,SYSTEM,,OPEN
false,defense.conferdeploy.net/alerts?s[c][query_string]=id:f3b3f70d-28a1-4764-9385-89331608e0f3&orgKey=ABCD1234,,,,,2024-05-28T12:55:56.709689187Z,2024-05-28T12:55:56.709689187Z,,,,,,,,,,,,,,,,,,2024-05-28T12:52:34.185Z,2024-05-28T12:55:56.709689187Z,,,NONE,1.2.3.4,19013608,9.8.7.6,UNKNOWN,DEMO-WIN02,WINDOWS,Windows 10 x64,Demo Policy,465946,MEDIUM,,,,,,2024-05-28T12:48:32.406Z,f3b3f70d-28a1-4764-9385-89331608e0f3,,(process_name:dllhost.exe) AND process_publisher_state:FILE_SIGNATURE_STATE_VERIFIED ,529de965-e1f6-4e7d-a37e-9e392da29740,,false,,,,,,1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9,,627bbdfe-55a7-3100-89bc-25d618fb9684,,2024-05-28T12:48:32.406Z,false,false,,false,false,,,,,,,,,0,,,,,,0,ABCD1234,C:\Windows\system32\svchost.exe -k DcomLaunch -p,TRUSTED_WHITE_LIST,ABCD1234-01221fe8-00000338-00000000-1daa710f1091653,7469cc568ad6821fd9d925542730a7d8,c:\windows\system32\svchost.exe,824,TRUSTED_WHITE_LIST,,NT AUTHORITY\SYSTEM,NOT_APPLIED,AZDQ1VvNSdyupi9rG-4nOg-0,C:\Windows\system32\DllHost.exe /Processid:{973D20D7-562D-44B9-B70B-5A0F49CCDF3F},0,TRUSTED_WHITE_LIST,ABCD1234-01221fe8-00001f70-00000000-1daa7113a0da2e2,[Microsoft Windows Production PCA 2011],dfe1e4b1b8714cbe1005ee9413c2bae9,c:\windows\system32\dllhost.exe,8048,[Microsoft Windows],TRUSTED_WHITE_LIST,0309834d40475ccd5a88c48f7ff5ec62e5c6798900357dd83665c3d0345124e0,DEMO-WIN02\DEMO-DOMAIN,,,"Process dllhost.exe was detected by the report ""demo-report"" in watchlist ""demo-watchlist""",1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9:627bbdfe-55a7-3100-89bc-25d618fb9684,false,,,,,,Q0O2FxEWSy2fSSYxEs2Pg,,demo-report,,1b32b7cf-7c3d-30f1-97b4-6ec2e39530c9,,,,627bbdfe-55a7-3100-89bc-25d618fb9684,RAN,ALLOW,,5,,,,1B32B7CF7C3D40F117B46EC2E39530C9,,true,,,WATCHLIST,,,,,2024-05-28T12:55:56.709689187Z,ALERT_CREATION,,SYSTEM,,OPEN
To download or review the Carbon Black Cloud Postman collection, click here.


Verifies that the search is valid and returns error messages if not.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_validate

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "start": <integer>,
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
start Integer See Alerts API - Pagination
rows Integer See Alerts API - Pagination
sort Object See Alerts API - Find Alerts - Alert Sorting

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_validate
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body - Invalid Search, missing criteria or exclusions around minimum_severity 
{
    "time_range": {
        "range": "-10d"
    },
    "minimum_severity": "1",
    "start": 1,
    "rows": 100,
    "sort": [
        {
            "field": "backend_update_timestamp",
            "order": "desc"
        }
    ]
}
Response Body 
{
    "error_code": "UNEXPECTED_PROPERTY",
    "message": "Malformed JSON input: minimum_severity",
    "field": "minimum_severity",
    "known_properties": [
        "start",
        "exclusions",
        "query",
        "rows",
        "time_range",
        "sort",
        "criteria"
    ],
    "property_name": "minimum_severity"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Search Recommendations

Get recommendations of fields to use in a search.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments


Request 

GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/search_suggestions

Query Parameters

Parameter Required Description Type Default
query Yes The query string for which you want completion suggestions. String N/A
count No The number of suggestions to return Integer 5

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/search_suggestions?query=devi&count=5
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "suggestions": [
        {
            "term": "device_id"
        },
        {
            "term": "device_os"
        },
        {
            "term": "device_name"
        },
        {
            "term": "device_uem_id"
        },
        {
            "term": "device_policy"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Alert History

Get the actions taken on an Alert such as Notes added and workflow state changes.

The history route does not include the current state details of the alert.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/history

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/12ab345c-d6e7-4118-8a8d-04f521ae66aa/history
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "history": [
        {
            "type": "USER_WORKFLOW_UPDATE",
            "workflow": {
                "change_timestamp": "2023-04-14T21:30:40.570Z",
                "changed_by_type": "SYSTEM",
                "changed_by": "ALERT_CREATION",
                "closure_reason": "NO_REASON",
                "status": "OPEN"
            }
        },
        {
            "type": "USER_DETERMINATION_UPDATE",
            "determination": {
                "changed_by": "demouser@demoorg.com",
                "changed_by_type": "USER",
                "change_timestamp": "2023-04-16T23:32:41.182Z",
                "value": "TRUE_POSITIVE"
            }
        },
        {
            "type": "ALERT_NOTE_ADDED",
            "note": {
                "author": "demouser@demoorg.com",
                "create_timestamp": "2023-04-16T23:35:10.295Z",
                "last_update_timestamp": "2023-04-16T23:35:10.295Z",
                "id": "eb0c0791-505b-408e-8b03-24562a95a875",
                "source": "CUSTOMER",
                "note": "A note for API demo",
                "parent_id": null,
                "read_history": null,
                "thread": null
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Alert Histogram

Get statistics about the Alerts over time. This is designed for use by the widget in the Carbon Black Cloud console.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_histogram

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>"},
  "exclusions": { "<object>" },
  "field": "<string>",
  "bucket_size": "<string>",
  "min_count": <integer>
}


Body Schema

Field Data Type Definition Values
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
field String Field used to bucket alerts BACKEND_TIMESTAMP, BACKEND_UPDATE_TIMESTAMP, FIRST_EVENT_TIMESTAMP, LAST_EVENT_TIMESTAMP
bucket_size String Bucket size. Expected format is +<quantity><units> where quantity is a positive integer and units is one of MINUTE, HOUR, DAY
min_count Integer Minimal count of each response bucket. Buckets with counts lower than this value will be excluded from the response. Default: 0

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_histogram
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "bucket_size": "+5DAY",
  "field": "LAST_EVENT_TIMESTAMP",
  "min_count": 0
}
Response Body 
{
    "start": "2023-04-03T00:00:00.000Z",
    "end": "2023-04-18T00:00:00.000Z",
    "results": [
        {
            "step_start": "2023-04-03T00:00:00.000Z",
            "total": 470
        },
        {
            "step_start": "2023-04-08T00:00:00.000Z",
            "total": 671
        },
        {
            "step_start": "2023-04-13T00:00:00.000Z",
            "total": 612
        },
        {
            "step_start": "2023-04-18T00:00:00.000Z",
            "total": 10
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Facet Alerts - Ungrouped


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/_facet

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "terms": {
    "rows": <integer>,
    "fields": "[ <string> ]"
  },
  "filter_values": "<true>"
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
terms Object See Alerts API - Facet Alerts - Terms
filter_values Boolean A flag to indicate whether any filters on a term should be applied to facet calculation. When false (default), a filter on the term is ignored while calculating facets. For example, filtering foo: [bar, baz] might return facets [bar, baz, bat]. When filter_values is enabled, the same request will only return [bar, baz]

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "terms": {
        "fields": [
            "type",
            "THREAT_ID"
        ],
        "rows": 3
    },
    "criteria": {
        "minimum_severity": "3"
    },
    "exclusions": {
        "type": [
            "HOST_BASED_FIREWALL",
            "CONTAINER_RUNTIME"
        ]
    },
    "filter_values": true
}
Response Body 
{
    "results": [
        {
            "field": "threat_id",
            "values": [
                {
                    "total": 1600,
                    "id": "0569620088E6669121E38D9A64DBC24E",
                    "name": "0569620088E6669121E38D9A64DBC24E"
                },
                {
                    "total": 52,
                    "id": "19261158DBBF00775959F8AA7F7551A1",
                    "name": "19261158DBBF00775959F8AA7F7551A1"
                },
                {
                    "total": 47,
                    "id": "d6ea0f3012e949cf08d4fbc813892170",
                    "name": "d6ea0f3012e949cf08d4fbc813892170"
                }
            ]
        },
        {
            "field": "type",
            "values": [
                {
                    "total": 1679,
                    "id": "WATCHLIST",
                    "name": "WATCHLIST"
                },
                {
                    "total": 73,
                    "id": "CB_ANALYTICS",
                    "name": "CB_ANALYTICS"
                },
                {
                    "total": 7,
                    "id": "NETWORK_TRAFFIC_ANALYSIS",
                    "name": "NETWORK_TRAFFIC_ANALYSIS"
                }
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
The following snippet shows a valid request and printed response.

Code 
import json
from cbc_sdk import CBCloudAPI
from cbc_sdk.platform import Alert
api = CBCloudAPI(profile='sample')
facet_list = api.select(Alert).facets(["policy_applied", "attack_technique"])
print("Facet Response: {}".format(json.dumps(facet_list, indent=4)))
Result 
Facet Response: [
    {
        "field": "attack_technique",
        "values": [
            {
                "total": 2,
                "id": "T1048.002",
                "name": "T1048.002"
            },
            {
                "total": 1,
                "id": "T1490",
                "name": "T1490"
            }
        ]
    },
    {
        "field": "policy_applied",
        "values": [
            {
                "total": 69224,
                "id": "NOT_APPLIED",
                "name": "NOT_APPLIED"
            },
            {
                "total": 450,
                "id": "APPLIED",
                "name": "APPLIED"
            }
        ]
    }
]
View the full Alerts SDK sample script here. To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Alert Facet Terms

The fields for which facets are calculated can be specified like this:

{
    "rows": <integer>,
    "fields": [ "<string>" ]
}

The Search Fields - Alerts page has details on what fields can be used for faceting.


Grouped Alerts Operations

Calls in this section work on Alerts that are grouped by Threat Id.


Common Grouped Request Attributes


Group Field

The field for grouping is specified as an object:

{                                                                                                       
  "field": "<string>"
}
Field Definition Data Type Values
field field to group by String threat_id

Find Grouped Alerts

Search for Alerts using query, criteria and exclusion operators. Alerts are grouped by the requested group_by field. Currently, only threat_id is available for grouping. The response schema varies by grouping field.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_search

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "start": <integer>,
  "rows": <integer>,
  "sort": {
    "field": "<string>",
    "order": "<string>"
  },
  "group_by": {
    "field": "<string>"
  }
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
start Integer See Alerts API - Pagination
rows Integer See Alerts API - Pagination
sort Object See Alerts API - Find Grouped Alerts - Grouped Alert Sorting
group_by Object See Alerts API - Group Field

Response Codes

Code Description Content-Type Content
200 Successful search request application/json See example below.
For all fields returned for each alert type see Search Fields - Alerts

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "group_by": {
        "field": "THREAT_ID"
    },
    "time_range": {
        "range": "-10d"
    },
    "criteria": {
        "type": [
            "WATCHLIST"
        ],
        "minimum_severity": "1"
    },
    "rows":1,
    "sort": [
        {
            "field": "count",
            "order": "DESC"
        }
    ]
}
Response Body 
{
    "num_found": 8,
    "num_available": 8,
    "results": [
        {
            "count": 1158,
            "workflow_states": {
                "IN_PROGRESS": 673,
                "OPEN": 484,
                "CLOSED": 1
            },
            "determination_values": {
                "NONE": 674
            },
            "ml_classification_final_verdicts": {
                "NOT_ANOMALOUS": 1026,
                "NOT_CLASSIFIED": 132
            },
            "first_alert_timestamp": "2023-04-07T19:21:23.978Z",
            "last_alert_timestamp": "2023-04-17T17:22:31.613Z",
            "highest_severity": 8,
            "policy_applied": "APPLIED",
            "threat_notes_present": false,
            "tags": [
                "demo_tag"
            ],
            "device_count": 9,
            "workload_count": 0,
            "most_recent_alert": {
                "org_key": "ABCD1234",
                "alert_url": "https://defense.conferdeploy.net/alerts?s[c][query_string]=id:df2b1916-4a62-4796-86af-88667c043d06&orgKey=ABCD1234",
                "id": "df2b1916-4a62-4796-86af-88667c043d06",
                "type": "WATCHLIST",
                "backend_timestamp": "2023-04-17T17:28:42.376Z",
                "user_update_timestamp": null,
                "backend_update_timestamp": "2023-04-17T17:28:42.376Z",
                "detection_timestamp": "2023-04-17T17:25:48.667Z",
                "first_event_timestamp": "2023-04-17T17:22:31.613Z",
                "last_event_timestamp": "2023-04-17T17:22:31.613Z",
                "severity": 8,
                "reason": "Process infdefaultinstall.exe was detected by the report \"Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall\" in 6 watchlists",
                "reason_code": "05696200-88e6-3691-a1e3-8d9a64dbc24e:7828aec8-8502-3a43-ae68-41b5050dab5b",
                "threat_id": "0569620088E6669121E38D9A64DBC24E",
                "primary_event_id": "0uYYJLu3TpuhPPaL7qehKA-0",
                "policy_applied": "NOT_APPLIED",
                "run_state": "RAN",
                "sensor_action": "ALLOW",
                "workflow": {
                    "change_timestamp": "2023-04-17T17:28:42.376Z",
                    "changed_by_type": "SYSTEM",
                    "changed_by": "ALERT_CREATION",
                    "closure_reason": "NO_REASON",
                    "status": "OPEN"
                },
                "determination": null,
                "tags": [
                    "demo_tag"
                ],
                "alert_notes_present": false,
                "threat_notes_present": false,
                "is_updated": false,
                "device_id": 12345678,
                "device_name": "DEMO_MACHINE",
                "device_uem_id": "",
                "device_target_value": "MEDIUM",
                "device_policy": "Demo Policy",
                "device_policy_id": 98765432,
                "device_os": "WINDOWS",
                "device_os_version": "Windows 10 x64 SP: 1",
                "device_username": "demouser@demoorg.com",
                "device_location": "UNKNOWN",
                "device_external_ip": "1.2.3.4",
                "mdr_alert": false,
                "report_id": "oJFtoawGS92fVMXlELC1Ow-b4ee93fc-ec58-436a-a940-b4d33a613513",
                "report_name": "Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall",
                "report_description": "\n\nThreat:\nThis behavior may be abused by adversaries to execute malicious files that could bypass application whitelisting and signature validation on systems.\n\nFalse Positives:\nSome environments may legitimate use this, but should be rare.\n\nScore:\n85",
                "report_tags": [
                    "attack",
                    "attackframework",
                    "threathunting"
                ],
                "report_link": "https://attack.mitre.org/wiki/Technique/T1218",
                "ioc_id": "b4ee93fc-ec58-436a-a940-b4d33a613513-0",
                "ioc_hit": "((process_name:InfDefaultInstall.exe)) -enriched:true",
                "watchlists": [
                    {
                        "id": "9x0timurQkqP7FBKX4XrUw",
                        "name": "Carbon Black Advanced Threats"
                    }
                ],
                "process_guid": "ABCD1234-01147626-00011e57-00000000-19db1ded53e8000",
                "process_pid": 73303,
                "process_name": "infdefaultinstall.exe",
                "process_sha256": "1a23456b7890c458f804e5d0fe925a9f55cf016733458c58c1980addc44cd774",
                "process_md5": "12ab34567c49f13193513b0138f72a9",
                "process_effective_reputation": "LOCAL_WHITE",
                "process_reputation": "NOT_LISTED",
                "process_cmdline": "InfDefaultInstall.exe C:\\Users\\userdir\\Infdefaultinstall.inf",
                "process_username": "DEMO\\DEMOUSER",
                "process_issuer": "Demo Code Signing CA",
                "process_publisher": "Demo Test Authority",
                "childproc_guid": "",
                "childproc_username": "",
                "childproc_cmdline": "",
                "ml_classification_final_verdict": "NOT_ANOMALOUS",
                "ml_classification_global_prevalence": "LOW",
                "ml_classification_org_prevalence": "LOW"
            }
        }
    ],
    "group_by_total_count": 1224
}
To download or review the Carbon Black Cloud Postman collection, click here.

Grouped Alert Response Fields

The fields returned as part of the group alert response vary by grouping type. The following fields are common to all grouped alert responses:

Field Data Type Definition
count Integer Count of individual alerts that are a part of the group
workflow_states Object Map of workflow state (OPEN, IN_PROGRESS, CLOSED) to the number of individual alerts in the group in that state. States with no alerts are omitted.
determination_values Object Map of determination (TRUE_POSITIVE, FALSE_POSITIVE, NONE) to the number of individual alerts in the group with that determination. Determinations with no alerts are omitted.
ml_classification_final_verdicts Object Map of ML classification (ANOMALOUS, NOT_ANOMALOUS, NO_PREDICTION) to the number of individual alerts in the group with that classification. Classifications with no alerts are omitted.

Grouping by threat_id also includes the following fields:

Field Data Type Definition
first_alert_timestamp ISO 8601 Date String Timestamp of the first (oldest) alert in the group
last_alert_timestamp ISO 8601 Date String Timestamp of the last (newest) alert in the group
highest_severity Integer Highest severity score of all alerts in the group
policy_applied String APPLIED, when any of the alerts in the group had actions blocked by the sensor due to a policy. NOT_APPLIED otherwise.
most_recent_alert Object The most recent alert in the group. Follows the Alerts Schema. This is an example of what an alert in the group looks like. Specific fields may vary between alert instances
threat_notes_present Boolean Whether there are threat-level notes available on this threat ID
tags String Array List of tags that have been applied to the threat ID
device_count Integer Count of unique devices where this alert can be found
workload_count Integer Count of unique Kubernetes workloads where this alert can be found

Grouped Alert Sorting

Requests can be sorted with the sort parameter. sort accepts a list of sort definitions like this: 

{
  ...other request parameters...
  "sort": [
    {
      "field": "primary_field",
      "order": "DESC"
    },
    {
      "field": "tiebreak_field",
      "order": "DESC"
    }
  ]
}

Field Definition Data Type Values
field field to sort on String first_alert_timestamp, last_alert_timestamp, highest_severity, count, device_count, workload_count
order order to sort String ASC (Ascending), DESC (Descending)

Facet Grouped Alerts


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_facet

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "terms": {
    "rows": <integer>,
    "fields": [ "<string>" ]
  },
  "filter_values": "<true>",
  "group_by": {
    "field": "<string>"
  }
}


Body Schema

Field Data Type Definition
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
group_by Object See Alerts API - Group Field
filter_values Boolean A flag to indicate whether any filters on a term should be applied to facet calculation. When false (default), a filter on the term is ignored while calculating facets. For example, filtering foo: [bar, baz] might return facets [bar, baz, bat]. When filter_values is enabled, the same request will only return [bar, baz]

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "group_by": {
        "field": "THREAT_ID"
    },
    "terms": {
        "fields": [
            "type",
            "THREAT_ID"
        ],
        "rows": 3
    },
    "criteria": {
        "minimum_severity": "3"
    },
    "exclusions": {
        "type": [
            "HOST_BASED_FIREWALL",
            "CONTAINER_RUNTIME"
        ]
    },
    "filter_values": true
}
Response Body 
{
    "results": [
        {
            "field": "threat_id",
            "values": [
                {
                    "total": 1,
                    "id": "0569620088E6669121E38D9A64DBC24E",
                    "name": "0569620088E6669121E38D9A64DBC24E"
                },
                {
                    "total": 1,
                    "id": "09c6f8b90b423b31ec17b29f6b714af5",
                    "name": "09c6f8b90b423b31ec17b29f6b714af5"
                },
                {
                    "total": 1,
                    "id": "0cf248835fc0f330c8e8176ec69aa3d9",
                    "name": "0cf248835fc0f330c8e8176ec69aa3d9"
                }
            ]
        },
        {
            "field": "type",
            "values": [
                {
                    "total": 7,
                    "id": "NETWORK_TRAFFIC_ANALYSIS",
                    "name": "NETWORK_TRAFFIC_ANALYSIS"
                },
                {
                    "total": 5,
                    "id": "WATCHLIST",
                    "name": "WATCHLIST"
                },
                {
                    "total": 5,
                    "id": "CB_ANALYTICS",
                    "name": "CB_ANALYTICS"
                }
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Grouped Alert Histogram

Get statistics about the Alerts when they are grouped. This is designed for use by the widget in the Carbon Black Cloud console.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/grouped_alerts/_histogram

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": {<object> },
  "field": "<string>",
  "bucket_size": "<string>",
  "min_count": <integer>,
  "group_by": {
    "field": "<string>"
  }
}


Body Schema

Field Data Type Definition Values
query String A lucene-formatted query using the Alert Search Fields
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}
criteria Object See Search Fields - Alerts
exclusions Object See Search Fields - Alerts
group_by Object See Alerts API - Group Field
field String Field used to bucket alerts BACKEND_TIMESTAMP, BACKEND_UPDATE_TIMESTAMP, FIRST_EVENT_TIMESTAMP, LAST_EVENT_TIMESTAMP
bucket_size String Bucket size. Expected format is +<quantity><units> where quantity is a positive integer and units is one of MINUTE, HOUR, DAY
min_count Integer Minimal count of each response bucket. Buckets with counts lower than this value will be excluded from the response. Default: 0

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_histogram
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "group_by": {
        "field": "THREAT_ID"
    },
    "bucket_size": "+5DAY",
    "field": "LAST_EVENT_TIMESTAMP",
    "min_count": 0
}
Response Body 
{
    "start": "2023-04-03T00:00:00.000Z",
    "end": "2023-04-18T00:00:00.000Z",
    "results": [
        {
            "step_start": "2023-04-03T00:00:00.000Z",
            "total": 6
        },
        {
            "step_start": "2023-04-08T00:00:00.000Z",
            "total": 10
        },
        {
            "step_start": "2023-04-13T00:00:00.000Z",
            "total": 16
        },
        {
            "step_start": "2023-04-18T00:00:00.000Z",
            "total": 1
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Manage Notes on Alerts

Calls in this section manipulate Notes on Alerts.


Get Notes for an Alert


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes READ Majority of environments

Request 
GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes

Response Codes

Code Description Content-Type Content
200 Successful search request application/json See example below and Notes schema

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aa/notes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "results": [
        {
            "author": "demouser@demoorg.com",
            "create_timestamp": "2023-04-16T23:35:10.295Z",
            "last_update_timestamp": "2023-04-16T23:35:10.295Z",
            "id": "eb0c0791-505b-408e-8b03-24562a95a875",
            "source": "CUSTOMER",
            "note": "A note for API demo",
            "parent_id": null,
            "read_history": null,
            "thread": null
        }
    ],
    "num_found": 1,
    "num_available": 1
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create a Note on an Alert


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes CREATE Majority of environments

Request 
POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes

Request Body - application/json

{
  "note": "<string>",
  "parent_id": "<string>"
}


Body Schema

Field Definition Data Type Values
note Note message String Maximum note length: 20,000. Cannot be empty.
parent_id Id of the parent note String N/A

Response Codes

Code Description Content-Type Content
201 Note created successfully application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "note": "The note that will be added to the alert"
}
Response Body 
{
    "author": "ABCD123456",
    "create_timestamp": "2023-04-17T00:12:18.441Z",
    "last_update_timestamp": "2023-04-17T00:12:18.441Z",
    "id": "eff9866e-70bd-4e78-b820-3b3b6e84e2c3",
    "source": "CUSTOMER",
    "note": "The note that will be added to the alert",
    "parent_id": null,
    "read_history": null,
    "thread": null
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete a Note from an Alert


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes DELETE Majority of environments

Request 
DELETE {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes/{id}

Response Codes

Code Description Content-Type Content
204 Note deleted successfully application/json 
"Note deleted successfully"
404 Note not found application/json 
"Note not found"

Examples

Request 
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aa/notes/39a3e335-9a31-4778-addd-fccbc40483a3
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Request Body 
No request body
Response Body 
{}
To download or review the Carbon Black Cloud Postman collection, click here.

Manage Threat Information

Calls in this section operate on a Threat.


Get the History of a Threat

Get the actions taken on a Threat such as Notes added.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts READ Majority of environments

Request 
GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/history

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/history
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "history": [
        {
            "type": "THREAT_NOTE_ADDED",
            "note": {
                "author": "demouser@demoorg.com",
                "create_timestamp": "2023-04-18T03:20:59.426Z",
                "last_update_timestamp": "2023-04-18T03:20:59.426Z",
                "id": "372ab282-7733-48fd-b26c-d58508b8c88f",
                "source": "CUSTOMER",
                "note": "A note on the threat",
                "parent_id": null,
                "read_history": null,
                "thread": null
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Notes for a Threat


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes READ Majority of environments


Request 

GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes

Query Parameters

Parameter Required Description Values Default
sort_field No Field to sort on create_timestamp, last_update_timestamp, author, source last_update_timestamp
sort_order No Order of the sort ASC (Ascending), DESC (Descending) DESC

Response Codes

Code Description Content-Type Content
200 Successful search request application/json See example below

Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/21471599-f528-4ecf-b4cf-85db9811e5f1/notes?sort_field=create_timestamp&sort_order=DESC
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "num_found": 2,
    "num_available": 2,
    "results": [
        {
            "author": "demouser@demoorg.com",
            "create_timestamp": "2023-04-18T03:30:55.408Z",
            "last_update_timestamp": "2023-04-18T03:30:55.408Z",
            "id": "21471599-f528-4ecf-b4cf-85db9811e5f1",
            "source": "CUSTOMER",
            "note": "A second note to test sorting",
            "parent_id": null,
            "read_history": null,
            "thread": null
        },
        {
            "author": "demouser@demoorg.com",
            "create_timestamp": "2023-04-18T03:25:44.397Z",
            "last_update_timestamp": "2023-04-18T03:25:44.397Z",
            "id": "321e5c6a-d55e-4687-82a3-769a34d1adef",
            "source": "CUSTOMER",
            "note": "My first note",
            "parent_id": null,
            "read_history": null,
            "thread": null
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create a Note on a Threat


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes CREATE Majority of environments

Request 
POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes

Request Body - application/json

{
  "note": "<string>",
  "parent_id": "<string>"
}


Body Schema

Field Definition Data Type Values
note Note message String maximum note length: 20,000. Cannot be empty.
parent_id Id of the parent note String N/A

Response Codes

Code Description Content-Type Content
201 Note created successfully application/json

Delete a Note from a Threat


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.notes DELETE Majority of environments


Request 

DELETE {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes/{id}

Response Codes

Code Description Content-Type Content

Examples

Request 
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/notes/21471599-f528-4ecf-b4cf-85db9811e5f1
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Request Body 
No request body
Response Body 
{}
To download or review the Carbon Black Cloud Postman collection, click here.

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/notes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "note": "A note from the API"
}
Response Body 
{
    "author": "ABCD123456",
    "create_timestamp": "2023-04-18T03:35:24.962Z",
    "last_update_timestamp": "2023-04-18T03:35:24.962Z",
    "id": "b924a3fd-a077-42e9-bbe6-a811d23df61d",
    "source": "CUSTOMER",
    "note": "A note from the API",
    "parent_id": null,
    "read_history": null,
    "thread": null
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create Threat Workflow

Update the threat with the current state of the remediation.

Note: This will dismiss all future alerts that are associated with the threat_id when marked as DISMISSED.

If you want to dismiss existing alerts use Bulk Update Alerts Workflow

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.dismiss EXECUTE Majority of environments

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/threat/{threat_id}/workflow

Request Body 

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

Body Schema

Field Definition Data Type Values
state REQUIRED Workflow state to set. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/threat/fbeca35516132a69747b7094e082b424/workflow

Request Body 

{
    "state": "OPEN",
    "comment": "This is an example",
    "remediation_state": "NOTHING"
}

Response 

{
  "state": "OPEN",
  "remediation": "NOTHING",
  "last_update_time": "2020-09-14T15:02:04.620Z",
  "comment": "This is an example",
  "changed_by": "A569S6YYRE"
}

Bulk Create Threat Workflows

Bulk update threat workflow by threat_id.

Note: This will dismiss all future alerts that are associated with the threat_id(s) when marked as DISMISSED.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.dismiss EXECUTE Majority of environments

Requests

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/threat/workflow/_criteria

Request Body 

{
  "comment": "string",
  "remediation_state": "string",
  "state": "OPEN",
  "threat_id": [
    "string"
  ]
}

Body Schema

Field Definition Data Type Values
threat_id REQUIRED List of threat ids to update. Array N/A
state REQUIRED Workflow state to which threats will be updated. String DISMISSED, OPEN
comment Comment to include with the operation String N/A
remediation_state Description or justification for the change. String Accepts any string

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/threat/workflow/_criteria

Request Body 

{
  "comment": "Initial triage complete",
  "remediation_state": "TRIAGED",
  "state": "OPEN",
  "threat_id": [
    "fbeca35516132a69747b7094e082b424",
    "8e991f4e1dbd3b5b92e5fc5509c24503"
  ]
}

Response 

{
 "request_id": "14617a6cd8df11e9974f1d8882e43ec1"
}

Get Bulk Threat Workflow Status

Get the current status of a bulk threat workflow request.

Note: The only input value for this API route that is supported is the value of request_id that's returned by the v6 Bulk Threat Workflow API route. If you are using the new Alert v7 Workflow please use the job service API to fetch the status.

If you want to dismiss existing alerts use Bulk Update Alerts Workflow

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.dismiss EXECUTE Majority of environments

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

Tags

Manage tags associated with a threat.


Get Tags

Get the list of tags attached to a threat.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.tags READ Majority of environments


Request 

GET {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags

Response Codes

Code Description Content-Type Content
200 OK application/json See example below


Examples

Request 
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tags
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "list": [
        "DemoTag"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Tags

Add tags to a Threat. The response includes all tags associated with a threat after the request completes.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.tags CREATE Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags

Request Body - application/json 
{
  "tags": [ "<string>" ]
}


Body Schema

Field Definition Data Type
tags List of tags to apply to all alerts with the given threat ID Array of String

Response Codes

Code Description Content-Type Content
200 OK application/json See example below


Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tags
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "tags": [ "<string>" ]
}
Response Body 
{
  "tags": [ "<string>" ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete a Tag

Delete a tag from a Threat.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.tags DELETE Majority of environments


Request 

DELETE {cbc-hostname}/api/alerts/v7/orgs/{org_key}}/threats/{threat_id}/tags/{tag}

Response Codes

Code Description Content-Type Content
200 OK application/json See example below


Examples

Request 
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tags/DemoTag
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Request Body 
No request body
Response Body 
{
  "tags": "[ <string> ]"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Alert Workflow

Bulk Update Alerts Workflow

This is an async operation that updates all existing alerts that match the search criteria of the request.

  1. First call this route to start the update job.
  2. The response contains a request_id. Use this in the job details route to check the progress of the operation.
  3. When the job is complete, all alerts matching the criteria will have the updates applied.
  4. Use the Alert Search request to view updated records.

If you want to dismiss future alerts associated to a threat_id then use Bulk Create Threat Workflows.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.alerts.close EXECUTE Majority of environments


Request 

POST {cbc-hostname}/api/alerts/v7/orgs/{org_key}/alerts/workflow

Request Body - application/json

{
  "query": "<string>",
  "time_range": {
    "start": "<string>",
    "end": "<string>",
    "range": "<string>"
  },
  "criteria": { "<object>" },
  "exclusions": { "<object>" },
  "determination": "<string>",
  "closure_reason": "<string>",
  "status": "<string>",
  "note": "<string>"
}


Body Schema

Field Data Type Definition Values
query String A lucene-formatted query using the Alert Search Fields N/A
time_range Object A Time Range Filter on backend_timestamp.
Default: {"range": "-2w"}		 N/A
criteria Object See Search Fields - Alerts N/A
exclusions Object See Search Fields - Alerts N/A
determination String Value judgement of whether the alert(s) represent a true or false positive. Optional. Omit to preserve existing determination TRUE_POSITIVE, FALSE_POSITIVE, NONE
closure_reason String Reason code for why the alert(s) are being updated. Optional NO_REASON, RESOLVED, RESOLVED_BENIGN_KNOWN_GOOD, DUPLICATE_CLEANUP, OTHER
status String New workflow status for the alert(s). Optional. Omit to preserve existing workflow status OPEN, IN_PROGRESS, CLOSED
note String Custom message to add to the note added to each modified alert N/A

Response Codes

Code Description Content-Type Content
200 OK application/json See example below

Examples

Request 
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/workflow
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "criteria": {
        "id": [
            "52fa009d-e2d1-4118-8a8d-04f521ae66aa"
        ]
    },
    "determination": "TRUE_POSITIVE",
    "closure_reason": "OTHER",
    "status": "CLOSED",
    "note": "Closing this alert after triage"
}
Response Body 
{
  "request_id": "5372752"
}
To download or review the Carbon Black Cloud Postman collection, click here.
1. Use an Alert Search to specify which Alerts will have their status updated. 

from cbc_sdk import CBCloudAPI
from cbc_sdk.platform import Alert
api = CBCloudAPI(profile='sample')

# This query selects only the alert that has the specified id:
ALERT_ID = "id of the alert to close"
alert_query = api.select(Alert).add_criteria("id", [ALERT_ID])
# This query selects all alerts that have the specified threat id.  It is not used again in this example
alert_query_for_threat = api.select(Alert).add_criteria("threat_id","CFED0B211ED09F8EC1C83D4F3FBF1709")

2. Use the `update(status, closure_reason, determination, note)` method on the query. This will start an asynchronous job in the background. 

from cbc_sdk.platform import Job
job = alert_query.update("CLOSED", "RESOLVED", "NONE", "Setting to closed for SDK demo")
  • The status can be OPEN, IN PROGRESS or CLOSED (previously DISMISSED).
  • You can include a Closure Reason.
3. The immediate response confirms that the job was successfully submitted.

4. Use the Job() cbc_sdk.platform.jobs.Job class to determine when the update is complete.
  • Your python script will wait while the SDK manages the polling to determine when the job is complete.
job.await_completion().result()

5. Execute the same Alert Search to get the updated alert data into the SDK. 

alert_query = api.select(Alert).add_criteria("id", [ALERT_ID])
for alert in alert_query:
    print("id: {}, status: {}".format(alert.id, alert.workflow["status"]))
View the full Alerts SDK sample script here. To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Field Definitions

Note

Field Definition Data Type Values
author Author of the note String
create_timestamp Time when the note was created ISO 8601 UTC timestamp
last_update_timestamp Time when the note was updated. Will be the same as the create_timestamp when the note has not been updated. ISO 8601 UTC timestamp
id Id of the note String
source The source of the note String MD Analyst, Customer, Suppression
note Content of note String
parent_id Id of the parent note, available only for the child notes/threads. String
read_history Read history map with readByUserX as key and an ISO 8601 UTC timestamp of the time the user last read the note as the value.
Only available if the note has children.		 Object 
{
  "read_history": {
      "readByUser1": "2023-04-28T19:21:17.487Z",
      "readByUser2": "2023-04-28T19:21:17.487Z",
      "readByUser3": "2023-04-28T19:21:17.487Z"
    }
}
thread List of child note objects that make up the conversation around the parent note.
Only available if the note has children.		 Note[] 
{
  "thread": [
  {
    "author": "analyst@vmware.com",
    "create_timestamp": "2023-04-28T19:21:17.487Z",
    "last_update_timestamp": "2023-04-28T19:21:17.487Z",
    "id": "8f2cb121-8569-48ea-8f9e-81cf9e533b56",
    "source": "MD Analyst",
    "note": "string",
    "parent_id": "7f2cb121-8569-48ea-8f9e-81cf9e533b56",
    "read_history": {
      ...
    }
  }
}

Last modified on August 30, 2024