Carbon Black Cloud Enterprise EDR (Endpoint Detection and Response) is the new name for the product formerly called CB ThreatHunter.
The Watchlists API allows you to configure and review all Watchlists that are actively watching your fleet’s incoming endpoint data for selected indicators of compromise.
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:
Successful response indicates service reachability.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
No Permissions Required | N/A |
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 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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
CREATE |
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"
}
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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"
}
}
]
}
Retrieve watchlist with watchlist_id
.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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 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, that field will not be updated. Cannot update report watchlist with empty report_ids
list.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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
POST 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"
}
}
Remove watchlist with watchlist_id
. Existing hits for this watchlist will remain in the system.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
Remove all of an organization’s watchlists. Existing hits for watchlists will remain in the system.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
Retrieve alert status for watchlist with watchlist_id
.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
Turn on alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist hits. Future hits will trigger alerts.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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
}
Turn off alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist hits. Future hits will not trigger alerts.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
Turn off alerts for all watchlists. This is not retroactive for existing watchlist alerts. Future hits will not trigger alerts.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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 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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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 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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
Return all custom report severities. Custom report severities effect all watchlists.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
},
]
}
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
Adjust the severity of report with report_id
. This will effect all watchlists.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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 severity for report with report_id
.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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
Add a new watchlist report. This service will generate a unique report id. This report will be private to the caller. IOCs will be converted to IOCv2.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
CREATE |
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 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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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"
}
Retrieve report with report_id
. The report must be owned by the caller.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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 with report_id
. The report must be owned by the caller.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
DELETE |
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 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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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"
}
]
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
UPDATE |
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"
}
]
}
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
Permission (.notation name) | Operation(s) |
---|---|
org.watchlists |
READ |
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
}
]
}
NOTE: fields with ‘*’ are required
{
"id": str*,
"timestamp": int*,
"title": str*,
"description": str*,
"severity": int*,
"link": str,
"tags": [str],
"iocs": IOCs,
"iocs_v2": [IOCv2],
"visibility": str
}
{
"md5": [str],
"ipv4": [str],
"ipv6": [str],
"dns": [str],
"query": [QueryIOC]
}
{
"id": str*,
"match_type": str*,
"values": [str]*,
"field": str,
"link": str
}
{
"index_type": str,
"search_query": str*
}
{
"report_id": str*,
"severity": int*
}
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
}
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
}
A Watchlist object may populate one or other of the "classifier"
or "report"
objects but not both.
{
"classifier": ClassifierWatchlist,
"report": ReportWatchlist
}
{
"key": str*,
"value": str*
}
{
"name": str*,
"description": str,
"id": str,
"tags_enabled": bool,
"alerts_enabled": bool,
"create_timestamp": int,
"last_update_timestamp": int,
"report_ids": [str],
"classifier": ClassifierKeyValue
}
{
"ignore": bool*,
"report_id": str*,
"ioc_id": str
}
{
"ignores": [ReportIOCIgnore]*
}
{
"watchlist_id": str*,
"interval": int*,
"hits": int*,
"executions": int*
}
{
"telemetry": [WatchlistTelemetry]*
}
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.
{
"id": "1af4e5ff584a",
"match_type": "equality",
"field": "process_sha256",
"values": ["68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728"],
"link": "https://carbonblack.com"
}
This regular expression looks for double file extensions.
{
"id": "1af4e5ff584a",
"match_type": "regex",
"field": "process_name",
"values": ["/\\\\..{3}\\\\..{3}/"],
"link": "https://carbonblack.com"
}
{
"id": "1af4e5ff584a",
"match_type": "query",
"values": ["process_name:malware.exe"],
"link": "https://carbonblack.com"
}