Watchlist API for Enterprise EDR
Carbon Black Cloud Enterprise EDR (Endpoint Detection and Response) is the new name for the product formerly called CB ThreatHunter.
Version: v3
Introduction
The Watchlist API enables you to manage Watchlists for your organization throughout their lifecycle - creation, update and removal - as well as associated Reports and IOCs.
It allows you to manage both Watchlists subscribed from third party threat intelligence feeds (aka “classifier” watchlists) and those custom built for your organization’s specific needs from new and/or existing Reports (aka “report” watchlists).
With visibility across your fleet of monitored endpoints, you can identify processes that are acting abnormally and over time, focus your watchlists to generate hits and alerts only for unexpected or unwanted activity. This includes:
- Creating new report Watchlists from scratch and add/remove/disable/enable new or existing Reports to that custom Watchlist
- Configuring or disabling existing Watchlists including enabling “tagging” aka generating “hits” and/or “alerting” aka generating Watchlist Alerts
- Configuring or deleting Reports and their included IOCs
- Disabling (ignore) individual Reports and IOCs to stop generating tagged events aka hits in otherwise-tagging-enabled Watchlists
The information model for Carbon Black Cloud Watchlists is comprised of three units of information:
- IOCs are the smallest unit of information - a single indicator of compromise, to be searched across your organization’s Enterprise EDR data
- Reports collect one or more IOCs together as a unit of control - all collected IOCs can be enabled or disabled from generating hits and alerts in a single action
- Watchlists collect one or more Reports together as another unit of control - all Reports in one Watchlist can be enabled or disabled for Alerting or reporting in your organization in a single action
Requirements
- Enterprise EDR product
- All API calls require an API key with appropriate permissions
Healthcheck
Successful response indicates service reachability.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | No permissions required |
|
Majority of environments |
VMware Cloud Services Platform | No permissions required |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/healthcheck
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Service is available | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Create New Watchlist
Create a new report or classifier watchlist. Unique watchlist ID will be generated by the service. Request must only specify report_ids
(for report watchlist) or classifier
(for classifier watchlist), but not both.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
CREATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.create |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists
Request Body
{
"name": "<string>",
"description": "<string>",
"tags_enabled": "<boolean>",
"alerts_enabled": "<boolean>",
"report_ids": ["<string>"],
"classifier": ClassifierKeyValue
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
name REQUIRED
|
Watchlist name | String | N/A |
description |
Watchlist description | String | N/A |
tags_enabled |
Whether tags should be enabled for this watchlist | Boolean | true , false |
alerts_enabled |
Whether alerts should be enabled for this watchlist | Boolean | true , false |
report_ids |
Report ID’s to attach to this watchlist | [String] | N/A |
classifier |
Watchlist classifier key and value | ClassifierKeyValue | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Watchlist successfully created | 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 |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists
Request Body
{
"name": "My Watchlist",
"description": "Watchlist subscribed to a Feed",
"tags_enabled": true,
"alerts_enabled": false,
"classifier": {
"key": "feed_id",
"value": "ABCDEFGHIJKLMNOPQRSTU"
}
}
Response
{
"name": "My Watchlist",
"description": "Watchlist subscribed to a Feed",
"id": "MEjVbdeyS1uJtQ8auEq3A",
"tags_enabled": true,
"alerts_enabled": false,
"create_timestamp": 1604693936,
"last_update_timestamp": 1604693936,
"report_ids": null,
"classifier": {
"key": "feed_id",
"value": "ABCDEFGHIJKLMNOPQRSTU"
}
}
Get All Watchlists
Retrieve all watchlists owned by the caller.
Note that classifier watchlists will include a null-value report
object, and report watchlists will include a null-value classifier
object.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved watchlists | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists
Response
{
"results": [
{
"name": "My Watchlist",
"description": "Watchlist subscribed to Reports",
"id": "5LKpHr2SHiaE2QprfPhQ",
"tags_enabled": true,
"alerts_enabled": true,
"create_timestamp": 1553542270,
"last_update_timestamp": 1553542270,
"report_ids": [
"MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
"MLRtPcpQGKFh5OE4BT3tQ-e31ff772-6ca3-48ee-94ad-08de7dcea717"
],
"classifier": null
},
{
"name": "My Other Watchlist",
"description": "Watchlist subscribed to a Feed",
"id": "R4cMgFIhRaakgk749MRr6Q",
"tags_enabled": true,
"alerts_enabled": true,
"create_timestamp": 1578078507,
"last_update_timestamp": 1599574461,
"report_ids": null,
"classifier": {
"key": "feed_id",
"value": "ABCDEFGHIJKLMNOPQRSTU"
}
}
]
}
Get Watchlist
Retrieve watchlist with watchlist_id
.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved watchlist | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q
Response
{
"name": "My Other Watchlist",
"description": "Watchlist subscribed to a Feed",
"id": "R4cMgFIhRaakgk749MRr6Q",
"tags_enabled": true,
"alerts_enabled": true,
"create_timestamp": 1578078507,
"last_update_timestamp": 1599574461,
"report_ids": null,
"classifier": {
"key": "feed_id",
"value": "ABCDEFGHIJKLMNOPQRSTU"
}
}
Update Watchlist
Update watchlist with watchlist_id
. This will update the tags and alert status as well as any reports or classifiers attached to the watchlist. If a field is missing or null (e.g. tags_enabled
is not included) that field will not be updated. Cannot update report watchlist with empty report_ids
list.
Alerting is not supported on the following feeds due to the volume of hits:
- ATT&CK Framework
- Carbon Black Early Access Indicators
- Carbon Black Endpoint Visibility
- Carbon Black Suspicious Indicators
Attempting to enable an alert on any of these feeds will result in a 400 error.
Further information is available here.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}
Request Body
{
"name": "<string>",
"description": "<string>",
"tags_enabled": "<boolean>",
"alerts_enabled": "<boolean>",
"report_ids": ["<string>"],
"classifier": ClassifierKeyValue
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
name |
Watchlist name | String | N/A |
description |
Watchlist description | String | N/A |
tags_enabled |
Whether tags should be enabled for this watchlist | Boolean | true , false |
alerts_enabled |
Whether alerts should be enabled for this watchlist | Boolean | true , false |
report_ids |
Report ID’s to attach to this watchlist | [String] | N/A |
classifier |
Watchlist classifier key and value | ClassifierKeyValue | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Watchlist successfully updated | 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 |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q
Request Body
{
"name": "New Name for My Watchlist",
"description": "Updated Watchlist subscribed to a Feed",
"tags_enabled": false,
"alerts_enabled": false,
"classifier": {
"key": "feed_id",
"value": "FGHIJKLMNOPQRSTUVWXYZ"
}
}
Response
{
"name": "New Name for My Watchlist",
"description": "Updated Watchlist subscribed to a Feed",
"id": "R4cMgFIhRaakgk749MRr6Q",
"tags_enabled": false,
"alerts_enabled": false,
"create_timestamp": 1604693936,
"last_update_timestamp": 1604694841,
"report_ids": null,
"classifier": {
"key": "feed_id",
"value": "FGHIJKLMNOPQRSTUVWXYZ"
}
}
Delete Watchlist
Remove watchlist with watchlist_id
. Existing hits for this watchlist will remain in the Carbon Black Cloud for the data retention period.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully deleted watchlist | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q
Response
204 No Content
Delete All Watchlists
Remove all of an organization’s watchlists. Existing hits for watchlists will remain in the system.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully deleted all watchlists | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists
Response
204 No Content
Get Watchlist Alert Status
Retrieve alert status for watchlist with watchlist_id
i.e. whether the watchlist will generate alerts or not.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved watchlist alert status | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q
Response
{
"alert": true
}
Enable Watchlist Alerts
Turn on alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist hits; alerts will not be generated for previous watchlist hits. Future hits will trigger alerts.
Alerting is not supported on the following feeds due to the volume of hits:
- ATT&CK Framework
- Carbon Black Early Access Indicators
- Carbon Black Endpoint Visibility
- Carbon Black Suspicious Indicators
Attempting to enable an alert on any of these feeds will result in a 400 error.
Further information is available here.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert
Request Body
{
"alert": "<boolean>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
alert |
Whether alerts should be enabled or disabled | Boolean | true |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated alerting for the watchlist | 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 |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/alert
Request Body
{
"alert": true
}
Response
{
"alert": true
}
Disable Watchlist Alerts
Turn off alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist alerts, as watchlist alerts previously generated will not be removed. Future hits will not trigger alerts.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully turned off alerting for the watchlist | 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 |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/alert
Response
No Content
Disable All Watchlist Alerts
Turn off alerts for all watchlists. This is not retroactive for existing watchlist alerts. Future hits will not trigger alerts.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/alert
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully turned off alerts for all watchlists | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/alert
Response
204 No Content
Get Watchlist Tag Status
Determine whether tagging (aka generating “watchlist hits” from IOC matches) is enabled for watchlist with watchlist_id
.
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved tag status for this watchlist | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag
Response
{
"tag": true
}
Enable Watchlist Tags
Turn on tagging (aka generating “watchlist hits”) for watchlist with watchlist_id
. This is not retroactive for existing watchlist matches. Future matches will trigger event tagging.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag
Request Body
{
"tag": "<boolean>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
tag REQUIRED
|
Whether to turn on tagging for this watchlist | Boolean | true |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated watchlist tag status | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag
Request Body
{
"tag": true
}
Response
{
"tag": true
}
Disable Watchlist Tags
Turn off tagging (aka stop generating “watchlist hits”) for watchlist with watchlist_id
. This is not retroactive for existing watchlist tags/hits. Future matches will not generate tagged events.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully turned off tagging for this watchlist | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag
Response
204 No Content
Disable All Watchlist Tags
Turn off tagging (aka stop generating “watchlist hits”) for all watchlists. This is not retroactive for existing watchlist tags. Future matches will not generate tagged events.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/tag
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully turned off tagging for all watchlists | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/tag
Response
204 No Content
Get Report Ignore Status
Get current ignore status for report with report_id
i.e. whether that report has been disabled such that any watchlist that includes the report will not generate hits for any IOCs in that report. ignore: true
indicates the report is disabled.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved ignore status for this report | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore
Response
{
"ignored": false
}
Ignore Report
Report with report_id
and all contained IOCs will not match future events for any watchlist i.e. that report will be disabled such that any watchlist that includes the report will not generate hits for any IOCs in that report.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore
Request Body
{
"ignore": "<boolean>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
ignore REQUIRED
|
Whether to ignore this report | Boolean | true |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated ignore status for this report | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore
Request Body
{
"ignore": true
}
Response
{
"ignore": true
}
Re-activate Report
Report with report_id
and all contained IOCs will match future events for all watchlists i.e. if that report has been disabled (ignored), it will be re-enabled such that any watchlist that includes the report will start generating hits for any IOCs in that report. This is not retroactive for events that occured while the report was ignored.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully reactivated this report | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore
Response
204 No Content
Get IOC Ignore Status
Get current ignore status for IOC ioc_id
in report report_id
i.e. whether that IOC has been disabled such that the watchlist report that includes the IOC will not generate hits for that IOC.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved ignore status for this IOC | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore
Response
{
"ignored": false
}
Ignore IOC
IOC ioc_id
for report report_id
will not match future events for any watchlist i.e. this IOC will be disabled such that the watchlist report that includes the IOC will not generate hits for that IOC.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore
Request Body
{
"ignore": true
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
ignore REQUIRED
|
Whether to ignore this IOC | Boolean | true |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated ignore status for this IOC | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore
Request Body
{
"ignore": true
}
Response
{
"ignore": true
}
Re-activate IOC
IOC ioc_id
for report report_id
and will match future events for all watchlists i.e. this IOC has been disabled and will be re-enabled such that the watchlist report that includes the IOC will start generating hits for this IOC. This is not retroactive for events that occured while the IOC was ignored.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully reactivated this IOC | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore
Response
204 No Content
Get Custom Report Severities
Return all custom report severities. Custom report severities effect all watchlists.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/severity
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved custom report severities | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/severity
Response
{
"results": [
{
"report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-12345678910",
"severity": 9
},
{
"report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-01987654321",
"severity": 4
},
]
}
Get Custom Severity for Report
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Return custom severity for report_id
. This will return 404 error if custom severity doesn’t exist.
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved custom report severity | application/json | View example response below |
403 | Forbidden | N/A | N/A |
404 | Not Found | application/json |
|
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity
Response
{
"report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
"severity": 4
}
Set Custom Report Severity
Adjust the severity of report with report_id
. This will effect all watchlists.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity
Request Body { “report_id”: “”, “severity”: “” }
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
report_id REQUIRED
|
ID of the report to modify | String | N/A |
severity REQUIRED
|
Custom severity level | Integer | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated custom report severity | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity
Request Body
{
"report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
"severity": 4
}
Response
{
"report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
"severity": 4
}
Remove Custom Report Severity
Remove custom severity for report with report_id
.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully deleted custom severity for this report | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity
Response
204 No Content
Create New Report
Adds a new watchlist report. This endpoint will return a unique report id - the ‘id’ field is not required nor accepted as input for this request. This report will be private to the caller - i.e. only available in the requesting organization. IOCs will be converted to IOC_V2.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
CREATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.create |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports
Request Body
{
"title": "<string>",
"description": "<string>",
"timestamp": "<integer>",
"severity": "<integer>",
"link": "<string>",
"tags": ["<string>"],
"iocs": IOCs,
"iocs_v2": [IOCv2],
"visibility": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
title REQUIRED
|
Report title | String | N/A |
description REQUIRED
|
Report description | String | N/A |
timestamp REQUIRED
|
UNIX Epoch timestamp to associate with the report | Integer | N/A |
severity REQUIRED
|
Report severity | Integer | Between 1 and 10, inclusive |
link |
A URL to associate with the report | String | N/A |
tags |
Report tags | [String] | N/A |
iocs |
IOCs to associate with the report | IOCs | IOCs |
iocs_v2 |
IOCv2’s to associate with the report. Preferred over IOCs. | Array | IOCv2 |
visibility |
Report visibility | String | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully created this report | 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 |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports
Request Body
{
"title": "Persistence - Possible Tibet.c Backdoor Installation",
"description": "This query identifies files that are known to be associated with the installation of a backdoor in OSX.\n\nThreat:\nThis activity is associated with multiple variants of Tibet.c\n\nFalse Positives:\nWe are currently unaware of any specific conditions that would generate false positives for this query. Any hits would most likely warrant further investigation.\n\nScore:\n100",
"timestamp": 1603123890,
"severity": 10,
"link": "https://community.carbonblack.com/t5/Threat-Research-Docs/Cb-Response-Advanced-Threats-Threat-Intel-Feed/ta-p/38756",
"tags": [
"malware",
"backdoor",
"tibet",
"attackframework",
"attack",
"t1543",
"peristence",
"osx",
"macos"
],
"iocs": null,
"iocs_v2": [
{
"id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
"match_type": "query",
"values": [
"((filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\" OR filemod_name:\"\/Library\/LaunchAgents\/com.apple.AudioService.plist\" AND device_os:MAC)) -enriched:true"
],
"field": null,
"link": null
}
],
"visibility": "visible"
}
Response
{
"id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
"timestamp": 1603123890,
"title": "Persistence - Possible Tibet.c Backdoor Installation",
"description": "This query identifies files that are known to be associated with the installation of a backdoor in OSX.\n\nThreat:\nThis activity is associated with multiple variants of Tibet.c\n\nFalse Positives:\nWe are currently unaware of any specific conditions that would generate false positives for this query. Any hits would most likely warrant further investigation.\n\nScore:\n100",
"severity": 10,
"link": "https://community.carbonblack.com/t5/Threat-Research-Docs/Cb-Response-Advanced-Threats-Threat-Intel-Feed/ta-p/38756",
"tags": [
"malware",
"backdoor",
"tibet",
"attackframework",
"attack",
"t1543",
"peristence",
"osx",
"macos"
],
"iocs": null,
"iocs_v2": [
{
"id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
"match_type": "query",
"values": [
"((filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\" OR filemod_name:\"\/Library\/LaunchAgents\/com.apple.AudioService.plist\" AND device_os:MAC)) -enriched:true"
],
"field": null,
"link": null
}
],
"visibility": "visible"
}
Update a Report
Update report with report_id
. This will replace all fields in the report. Any fields not provided in the request will be remove from the report. All IOCs will be converted to IOCv2. The report must be owned by the caller.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}
Request Body
{
"title": "<string>",
"description": "<string>",
"timestamp": "<integer>",
"severity": "<integer>",
"link": "<string>",
"tags": ["<string>"],
"iocs": IOCs,
"iocs_v2": [IOCv2],
"visibility": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
title |
Report title | String | N/A |
description |
Report description | String | N/A |
timestamp |
UNIX Epoch timestamp to associate with the report | Integer | N/A |
severity |
Report severity | Integer | Between 1 and 10, inclusive |
link |
A URL to associate with the report | String | N/A |
tags |
Report tags | [String] | N/A |
iocs |
IOCs to associate with the report | IOCs | IOCs |
iocs_v2 |
IOCv2’s to associate with the report. Preferred over IOCs. | Array | IOCv2 |
visibility |
Report visibility | String | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated this report | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw
Request Body
{
"title": "My New Title",
"description": "My New Description",
"timestamp": 1604702592,
"severity": 1,
"tags": [
"macos"
],
"iocs_v2": [
{
"id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
"match_type": "query",
"values": [
"filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\""
]
}
],
"visibility": "visible"
}
Response
{
"id": "UZDbBhFPTamJbZGQcwUHEw",
"timestamp": 1604702592,
"title": "My New Title",
"description": "My New Description",
"severity": 1,
"link": null,
"tags": [
"macos"
],
"iocs": null,
"iocs_v2": [
{
"id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
"match_type": "query",
"values": [
"filemod_name:\"/Library/Audio/Plug\\-Ins/Components/AudioService\""
],
"field": null,
"link": null
}
],
"visibility": "visible"
}
Get Report
Retrieve report with report_id
. The report must be owned by the caller.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved report | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw
Response
{
"id": "UZDbBhFPTamJbZGQcwUHEw",
"timestamp": 1604702592,
"title": "My New Title",
"description": "My New Description",
"severity": 1,
"link": null,
"tags": [
"macos"
],
"iocs": null,
"iocs_v2": [
{
"id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
"match_type": "query",
"values": [
"filemod_name:\"/Library/Audio/Plug\\-Ins/Components/AudioService\""
],
"field": null,
"link": null
}
],
"visibility": "visible"
}
Remove Report
Remove report with report_id
. The report must be owned by the caller.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully deleted this report | application/json | None |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw
Response
204 No Content
Get Ignore Status for Provided Report IDs
Get current ignore status for report and embedded IOCs in provided list of comma-separated report_ids
. report_ids
can be a single id.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_ids}/ignore/bulk
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved report and IOC ignore statuses | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw,UZDbBhFPTamJb123456789/ignore/bulk
Response
{
"results": [
{
"ignore": false,
"report_id": "UZDbBhFPTamJbZGQcwUHEw",
"ioc_id": null
},
{
"ignore": true,
"report_id": "UZDbBhFPTamJb123456789",
"ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
}
]
}
Bulk Ignore Report and IOCs
All reports and IOCs as defined in the ReportIOCIgnore
list with ignore=True will not match future events for any watchlist. All items with ignore=False will enable matching on future events. A ReportIOCIgnore
that does not define an ioc_id
will effect the entire report (all IOCs).
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/ignore/bulk
Request Body
{
"ignores": [
{
"ignore": "<boolean>",
"report_id": "<string>",
"ioc_id": "<string>",
},
{
"ignore": "<boolean>",
"report_id": "<string>",
"ioc_id": "<string>",
}
]
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
ignore REQUIRED
|
Whether to ignore the specified report and it’s IOCs | Boolean | true , false |
report_id REQUIRED
|
ID of the Report to modify ignore status | String | N/A |
ioc_id |
ID of the IOC to modify ignore status. Defaults to all IOCs if not specified. | String | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated report and IOC ignore statuses | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw,UZDbBhFPTamJb123456789/ignore/bulk
Request Body
{
"ignores": [
{
"ignore": true,
"report_id": "UZDbBhFPTamJbZGQcwUHEw",
"ioc_id": null
},
{
"ignore": false,
"report_id": "UZDbBhFPTamJbZGQcwUHEw",
"ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
}
]
}
Response
{
"results": [
{
"ignore": true,
"report_id": "UZDbBhFPTamJbZGQcwUHEw",
"ioc_id": null
},
{
"ignore": false,
"report_id": "UZDbBhFPTamJbZGQcwUHEw",
"ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
}
]
}
Get Watchlist Telemetry
Returns hits and executions for watchlists over the provided intervals. By default will return telemetry aggregated over the past hour. Include comma seperated list of intervals in minutes as query param intervals
to aggregate over different ranges, eg intervals=1440,10080,43200.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | org.watchlists |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Custom.Detections:org.Watchlists.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/(watchlist_ids)/telemetry
Query Schema
Field | Definition | Data Type | Values |
---|---|---|---|
intervals |
Intervals to retrieve telemetry data for, in minutes | Comma separated integers | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved telemetry | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw/telemetry?intervals=1440,10080,43200
Response
{
"telemetry": [
{
"watchlist_id": "UZDbBhFPTamJbZGQcwUHEw",
"interval": 1440,
"hits": 1,
"executions": 0
},
{
"watchlist_id": "UZDbBhFPTamJbZGQcwUHEw",
"interval": 10080,
"hits": 5,
"executions": 1
},
{
"watchlist_id": "UZDbBhFPTamJbZGQcwUHEw",
"interval": 43200,
"hits": 25,
"executions": 2
}
]
}
Definitions
NOTE: fields with ‘*’ are required unless otherwise noted
Report
{
"id": str*,
"timestamp": int*,
"title": str*,
"description": str*,
"severity": int*,
"link": str,
"tags": [str],
"iocs": IOCs,
"iocs_v2": [IOCv2],
"visibility": str
}
IOCs
{
"md5": [str],
"ipv4": [str],
"ipv6": [str],
"dns": [str],
"query": [QueryIOC]
}
IOCv2
{
"id": str*,
"match_type": str*,
"values": [str]*,
"field": str,
"link": str
}
QueryIOC
{
"index_type": str,
"search_query": str*
}
ReportSeverity
{
"report_id": str*,
"severity": int*
}
ClassifierWatchlist
A classifier watchlist is one subscribed from a Carbon Black Cloud-published third party threat intelligence Feed.
{
"name": str*,
"classifier_key": str*,
"classifier_value": str*,
"description": str,
"watchlist_id": str,
"tags_enabled": bool,
"alerts_enabled": bool,
"create_timestamp": int,
"last_update_timestamp": int
}
ReportWatchlist
A report watchlist is one created for the organization, constructed from new and existing Reports.
{
"name": str*,
"report_ids": [str]*,
"description": str,
"watchlist_id": str,
"tags_enabled": bool,
"alerts_enabled": bool,
"create_timestamp": int,
"last_update_timestamp": int
}
Watchlist
A Watchlist object may populate one or other of the "classifier"
or "report"
objects but not both.
{
"classifier": ClassifierWatchlist,
"report": ReportWatchlist
}
ClassifierKeyValue
{
"key": str*,
"value": str*
}
WatchlistV2
{
"name": str*,
"description": str,
"id": str,
"tags_enabled": bool,
"alerts_enabled": bool,
"create_timestamp": int,
"last_update_timestamp": int,
"report_ids": [str],
"classifier": ClassifierKeyValue
}
ReportIOCIgnore
{
"ignore": bool*,
"report_id": str*,
"ioc_id": str
}
ReportIOCIgnoreList
{
"ignores": [ReportIOCIgnore]*
}
WatchlistTelemetry
{
"watchlist_id": str*,
"interval": int*,
"hits": int*,
"executions": int*
}
WatchlistTelemetryList
{
"telemetry": [WatchlistTelemetry]*
}
Examples
IOCs
IOCs can be written in three different ways: equality, regex, or query. The equality and regex IOCs are run on ingress whereas the query IOC is run using a rolling window once the data reaches the data store. Because the equality and regex IOCs happen on ingress and do not need any part of the query language, these IOC match types perform better than the query IOC.
- An equality IOC will hit when the field value is exactly equal to any of the values.
- A regex IOC will hit if the field value matches on the regular expression provided in the values array.
- A query IOC will hit if the query in the values array matches on a particular document. These IOCs are equivalent to running searches on the Investigate page. Query IOCs are useful when you need query language to determine if the process is important enough to generate a hit.
Which fields can be used in which types of IOCs? Consult the Platform Search Fields documentation for a list of all possible fields to use in Watchlists:
- query IOCs can use any Platform Search field which is documented as Searchable
- equality and regex IOCs can use any Platform Search field, except the Aggregation only fields i.e.
num_devices
,num_events
Equality IOCv2
{
"id": "1af4e5ff584a",
"match_type": "equality",
"field": "process_sha256",
"values": ["68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728"],
"link": "https://carbonblack.com"
}
Regular Expression IOCv2
This regular expression looks for double file extensions. Note the leading & trailing /
characters are not used by Watchlists regex IOCs, whereas Search APIs require those characters to know when to interpret a query as regex notation.
{
"id": "1af4e5ff584a",
"match_type": "regex",
"field": "process_name",
"values": [".*\\\\..{3}\\\\..{3}"],
"link": "https://carbonblack.com"
}
Query IOCv2
{
"id": "1af4e5ff584a",
"match_type": "query",
"values": ["process_name:malware.exe"],
"link": "https://carbonblack.com"
}