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


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}/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 > Dismiss > org.alerts.dismiss, 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.


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}/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.Dismiss, 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

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

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

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": ""
        }
    ],
    "num_found": 147,
    "num_available": 147
}
To download or review the Carbon Black Cloud Postman collection, 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)

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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.

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
VMware Cloud Services Platform org.alerts.tags: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}/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
VMware Cloud Services Platform _API.Alerts:org.Alerts.Tags: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}/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
VMware Cloud Services Platform _API.Alerts:org.Alerts.Tags: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}/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 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.

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}/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.

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": {
      ...
    }
  }
}

Give Feedback

Use this form to give us feedback about this site or any of the documentation.


Last modified on October 18, 2023