Alerts API

Overview

Alerts v7 API (this version) was released on June 15th, 2023. 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.

If you require the earlier Alerts v6 API documentation it will be available here until the API is deactivated, no earlier than May 2024.

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

Carbon Black Cloud User Guide - Alerts
Carbon Black Cloud Python SDK
Carbon Black Cloud SDK Guide - Alerts
Alerts Fields - Fields available for each alert type and for searching.
Announcing the Alerts v7 API and “Observed Alerts” Become “Observations
Carbon Black Postman Workspace

Authentication

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

CBC Managed Identity

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

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

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

{cbc-hostname}/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.

CSP Managed Identity

Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

{cbc-hostname}/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 OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:

_API.Alerts:org.Alerts, allow permission to READ
_API.Alerts:org.Alerts.Close, allow permission to EXECUTE
_API.Alerts:org.Alerts.Notes, allow permission to READ, CREATE, DELETE, UPDATE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

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

Start and End

A 2-week query using explicit start and end timestamps

{
  "start": "2023-04-01T00:00:00.000Z",
  "end": "2023-04-15T00:00:00.000Z"
}

Range

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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.

Python SDK

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.

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.
Optionally, use Get Job Progress to check whether the job has completed.
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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK
Carbon Black Cloud	`jobs.status`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Background.Tasks:jobs.Status.read:org.Alerts:READ`	N/A - included in permission name	Prod UK

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

Start Export Alerts Job

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

Download Results of Alerts Export Job

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.

Validate Search

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.alerts`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

HTTP

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.

Python SDK

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.

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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)

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.alerts`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.notes:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Notes:CREATE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Notes:DELETE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

DELETE {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Notes:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Notes:CREATE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Notes:DELETE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Response Codes

Code	Description	Content-Type	Content

Examples

HTTP

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

HTTP

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Dismiss.EXECUTE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

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

Body Schema

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

Response

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

Example

Request

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

Request Body

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

Response

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

Bulk Create Threat Workflows

Bulk update threat workflow by threat_id.

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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Dismiss.EXECUTE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Requests

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

Request Body

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

Body Schema

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

Response

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

Example

Request

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

Request Body

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

Response

{
 "request_id": "14617a6cd8df11e9974f1d8882e43ec1"
}

Get Bulk 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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Dismisss.EXECUTE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/appservices/v6/orgs/{org_key}/workflow/status/{request_id}

Response

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

Example

Request

GET https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/workflow/status/14617a6cd8df11e9974f1d8882e43ec1

Response

{
  "errors": ["string"],
  "failed_ids": ["string"],
  "id": "string",
  "num_hits": 0,
  "num_success": 0,
  "status": "QUEUED",
  "workflow": {
    "changed_by": "string",
    "comment": "string",
    "last_update_time": "2019-09-17T00:39:23.823Z",
    "remediation": "string",
    "state": "OPEN"
  }
 }

Alert Workflow

Bulk Update Alerts Workflow

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

First call this route to start the update job.
The response contains a request_id. Use this in the job details route to check the progress of the operation.
When the job is complete, all alerts matching the criteria will have the updates applied.
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
VMware Cloud Services Platform	`_API.Alerts:org.Alerts.Close:EXECUTE`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

HTTP

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.

Python SDK

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

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.alerts.tags`	`READ`	Majority of environments
VMware Cloud Services Platform	`org.alerts.tags:READ`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Carbon Black Cloud

Page Contents

Alerts API

Overview

Use Cases

Requirements

Key Features

Guides and Resources

Authentication

API Calls

Common Request Attributes

Time Range Filter

Requests that accept time_range as a top-level parameter

Pagination

Individual Alert Operations

Get Alert by ID

Find Alerts

Alert Sorting

Export Alerts

Validate Search

Get Search Recommendations

Get Alert History

Get Alert Histogram

Facet Alerts - Ungrouped

Alert Facet Terms

Grouped Alerts Operations

Common Grouped Request Attributes

Group Field

Find Grouped Alerts

Grouped Alert Response Fields

Grouped Alert Sorting

Facet Grouped Alerts

Get Grouped Alert Histogram

Manage Notes on Alerts

Get Notes for an Alert

Create a Note on an Alert

Delete a Note from an Alert

Manage Threat Information

Get the History of a Threat

Get Notes for a Threat

Create a Note on a Threat

Delete a Note from a Threat

Create Threat Workflow

Bulk Create Threat Workflows

Get Bulk Threat Workflow Status

Tags

Get Tags

Update Tags

Delete a Tag

Alert Workflow

Bulk Update Alerts Workflow

Field Definitions

Note

Requests that accept `time_range` as a top-level parameter