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.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.
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
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:
startis a one-based index of the first result to retrieve. It must be a whole number greater than or equal to 1.rowsis the number of results to return. It must be a whole number greater than or equal to 0. A value of"rows": 0will 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 | |
Examples
Request
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aaX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"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"
}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/_searchRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_searchX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"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"
}
]
}{
"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
}
By using the following the example, you can retrieve the first 5 [:5] alerts that have a minimum severity level of 7.
Code
Result
View the full Alerts SDK sample script here.
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.
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)d689e626-5d6a-<truncated> WINDOWS Alert-WinTestAlert 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_idis 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_idin the Download Job Output endpoint in the Jobs Service to get the results. The Download Job API requires the permissionjobs.status - READ.- If more than 25,000 records matched the criteria, the first 25,000 are returned, sorted by
backend_timestampin descending order.
- If more than 25,000 records matched the criteria, the first 25,000 are returned, sorted by
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/_exportRequest 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 | |
Examples
Request
Request Headers
Start Export Alerts Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_exportX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"time_range": {
"range": "-1d"
},
"criteria": {
"minimum_severity": 2,
"type": ["WATCHLIST"]
},
"format": "CSV"
} {
"job_id": "12345678"
} Examples
Request
Request Headers
Download Export Alerts Result Request Body
Download Job Output in CSV Format
GET https://defense.conferdeploy.net/jobs/v1/orgs/ABCD1234/jobs/12345678/downloadX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"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,,OPENValidate 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/_validateRequest 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
Request Headers
Request Body - Invalid Search, missing criteria or exclusions around minimum_severity
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_validateX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"time_range": {
"range": "-10d"
},
"minimum_severity": "1",
"start": 1,
"rows": 100,
"sort": [
{
"field": "backend_update_timestamp",
"order": "desc"
}
]
}{
"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"
}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_suggestionsQuery 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
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/search_suggestions?query=devi&count=5X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"suggestions": [
{
"term": "device_id"
},
{
"term": "device_os"
},
{
"term": "device_name"
},
{
"term": "device_uem_id"
},
{
"term": "device_policy"
}
]
}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}/historyResponse Codes
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 200 | OK | application/json | See example below |
Examples
Request
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/12ab345c-d6e7-4118-8a8d-04f521ae66aa/historyX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"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
}
}
]
}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/_histogramRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_histogramX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"bucket_size": "+5DAY",
"field": "LAST_EVENT_TIMESTAMP",
"min_count": 0
}{
"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
}
]
}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/_facetRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/_facetX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"terms": {
"fields": [
"type",
"THREAT_ID"
],
"rows": 3
},
"criteria": {
"minimum_severity": "3"
},
"exclusions": {
"type": [
"HOST_BASED_FIREWALL",
"CONTAINER_RUNTIME"
]
},
"filter_values": true
}{
"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"
}
]
}
]
}
The following snippet shows a valid request and printed response.
Code
Result
View the full Alerts SDK sample script here.
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.
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)))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"
}
]
}
]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/_searchRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_searchX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"group_by": {
"field": "THREAT_ID"
},
"time_range": {
"range": "-10d"
},
"criteria": {
"type": [
"WATCHLIST"
],
"minimum_severity": "1"
},
"rows":1,
"sort": [
{
"field": "count",
"order": "DESC"
}
]
}{
"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
}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/_facetRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_facetX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"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
}{
"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"
}
]
}
]
}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/_histogramRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/grouped_alerts/_histogramX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"group_by": {
"field": "THREAT_ID"
},
"bucket_size": "+5DAY",
"field": "LAST_EVENT_TIMESTAMP",
"min_count": 0
}{
"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
}
]
}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}/notesResponse Codes
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 200 | Successful search request | application/json | See example below and Notes schema |
Examples
Request
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aa/notesX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"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
}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}/notesRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notesX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"note": "The note that will be added to the alert"
}{
"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
}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 | |
| 404 | Note not found | application/json | |
Examples
Request
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/52fa009d-e2d1-4118-8a8d-04f521ae66aa/notes/39a3e335-9a31-4778-addd-fccbc40483a3X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"No request body{}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}/historyResponse Codes
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 200 | OK | application/json | See example below |
Examples
Request
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/historyX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"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
}
}
]
}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}/notesQuery 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
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/21471599-f528-4ecf-b4cf-85db9811e5f1/notes?sort_field=create_timestamp&sort_order=DESCX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"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
}
]
}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}/notesRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/notes/21471599-f528-4ecf-b4cf-85db9811e5f1X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"No request body{}Examples
Request
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/7103E507844087BE20351A50D8773029/notesX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"note": "A note from the API"
}{
"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
}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"
}
}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}/tagsResponse Codes
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 200 | OK | application/json | See example below |
Examples
Request
Request Headers
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
GET https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tagsX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"{
"list": [
"DemoTag"
]
}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}/tagsRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tagsX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"tags": [ "<string>" ]
}{
"tags": [ "<string>" ]
}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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
DELETE https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/threats/0569620088E6669121E38D9A64DBC24E/tags/DemoTagX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"No request body{
"tags": "[ <string> ]"
}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/workflowRequest 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
Request Headers
Request Body
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.
POST https://defense.conferdeploy.net/api/alerts/v7/orgs/ABCD1234/alerts/workflowX-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"{
"criteria": {
"id": [
"52fa009d-e2d1-4118-8a8d-04f521ae66aa"
]
},
"determination": "TRUE_POSITIVE",
"closure_reason": "OTHER",
"status": "CLOSED",
"note": "Closing this alert after triage"
}{
"request_id": "5372752"
}
1. Use an Alert Search to specify which Alerts will have their status updated.
2. Use the `update(status, closure_reason, determination, note)` method on the query. This will start an asynchronous job in the background.
4. Use the Job() cbc_sdk.platform.jobs.Job class to determine when the update is complete.
5. Execute the same Alert Search to get the updated alert data into the SDK.
View the full Alerts SDK sample script here.
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.
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.
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"]))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 | |
thread |
List of child note objects that make up the conversation around the parent note.
Only available if the note has children. |
Note[] | |
Last modified on August 30, 2024