Carbon Black Cloud Enterprise EDR (Endpoint Detection and Response) is the new name for the product formerly called CB ThreatHunter.
Watchlist API Definition
Note: <cbc-hostname>
is the parent URL for your Carbon Black Cloud instance.
Successful response indicates service reachability.
GET <cbc-hostname>/threathunter/watchlistmgr/healthcheck
Code | Description | content-type | Content |
---|---|---|---|
204 | service is available | */* | None |
Create a new report or classifier watchlist. A unique watchlist ID will be generated by this request.
Request must specify report
or classifier
but not both.
POST <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist
content-type | Content |
---|---|
application/json | Watchlist |
Code | Description | content-type | Content |
---|---|---|---|
200 | Watchlist created. | application/json | Watchlist |
400 | invalid watchlist request. | application/json | None |
Retrieve all watchlists owned by the requester.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist
Code | Description | content-type | Content |
---|---|---|---|
200 | Array of watchlists | application/json | {"results": [Watchlist]} |
Retrieve watchlist with specified watchlist_id
.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)
Code | Description | content-type | Content |
---|---|---|---|
200 | Return watchlist | application/json | Watchlist |
400 | Unknown watchlist. | */* | None |
Update watchlist specified by 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 (ie tags_enabled) that field will not be updated.
Cannot update report watchlist with empty report_ids
list.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)
content-type | Content |
---|---|
application/json | Watchlist |
Code | Description | content-type | Content |
---|---|---|---|
200 | Return watchlist | application/json | Watchlist |
400 | Unknown watchlist or malformed request. | */* | None |
Remove watchlist specified by watchlist_id
. Existing hits for this watchlist will remain in the system.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)
Code | Description | content-type | Content |
---|---|---|---|
204 | Watchlist deleted | */* | None |
400 | Unknown watchlist. | */* | None |
Retrieve the alert status for watchlist with watchlist_id
.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns alert status | application/json | {"alert": boolean*} |
Turn on alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist hits, only future hits will trigger alerts.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns alert status | application/json | {"alert": boolean*} |
400 | Unknown watchlist | */* | None |
Turn off alerts for watchlist with watchlist_id
. This is not retroactive for existing watchlist alerts, only future hits will not trigger alerts.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert
Code | Description | content-type | Content |
---|---|---|---|
204 | Returns alert status | */* | None |
400 | Unknown watchlist | */* | None |
Retrieve tag status for watchlist with watchlist_id
.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns tag status | application/json | {"tag": boolean*} |
Turn on tagging for watchlist with watchlist_id
. This is not retroactive for existing watchlist matches, only future matches will trigger event tagging.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns tag status | application/json | {"tag": boolean*} |
400 | Unknown watchlist | */* | None |
Turn off tagging for watchlist with watchlist_id
. This is not retroactive for existing watchlist tags, only future matches will not trigger event tagging.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag
Code | Description | content-type | Content |
---|---|---|---|
204 | Tagging stopped | */* | None |
400 | Unknown watchlist | */* | None |
Get current ignore status for report with report_id
.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns ignore status | application/json | {"ignored": boolean*} |
Report with report_id
and all contained IOCs will not match future events for any watchlist.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns ignore status | application/json | {"ignored": boolean*} |
Report with report_id
and all contained IOCs will match future events for all watchlists. This is not retroactive for events that occurred while the report was ignored.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
204 | Report is active | */* | None |
400 | Unknown report | */* | None |
Get current ignore status for IOC ioc_id
in report report_id
.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns ignore status | application/json | {"ignored": boolean*} |
IOC ioc_id
for report report_id
will not match future events for any watchlist.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns ignore status | application/json | {"ignored": boolean*} |
IOC ioc_id
for report report_id
and will match future events for all watchlists. This is not retroactive for events that occurred while the IOC was ignored.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore
Code | Description | content-type | Content |
---|---|---|---|
204 | Ignore removed - IOC is active | */* | None |
400 | Unknown report/ioc | */* | None |
Return all custom report severities. Custom report severities effect all watchlists.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/severity
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns list of report severities | application/json | {"results": [ReportSeverity]} |
Return custom severity for report_id
. This will return 404 error if custom severity doesn’t exist.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns severity. (null if not set) | application/json | ReportSeverity |
404 | No override for report | */* | None |
Adjust the severity of report with report_id
. This will effect all watchlists.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)
Code | Description | content-type | Content |
---|---|---|---|
200 | Returns severity. | application/json | ReportSeverity |
Remove custom severity for report with report_id
.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)
Code | Description | content-type | Content |
---|---|---|---|
204 | Severity override removed | */* | None |
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 IOC_V2.
POST <cbc-hostname>/threathunter/watchlistmgr/v1/report
content-type | Content |
---|---|
application/json | Report |
Code | Description | content-type | Content |
---|---|---|---|
200 | Report created | application/json | Report |
400 | invalid report request. | */* | None |
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 IOC_V2. The report must be owned by the caller.
PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)
content-type | Content |
---|---|
application/json | Report |
Code | Description | content-type | Content |
---|---|---|---|
200 | Report updated | application/json | Report |
400 | invalid report request. | */* | None |
404 | report id not found | */* | None |
Retrieve report with report_id
. The report must be owned by the requester.
GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)
Code | Description | content-type | Content |
---|---|---|---|
200 | Report | application/json | Report |
404 | report id not found | */* | None |
Remove report with report_id
. The report must be owned by the caller.
DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)
Code | Description | content-type | Content |
---|---|---|---|
204 | Report deleted | */* | None |
404 | report id not found | */* | None |
NOTE: fields with *
are required
{"id": str*,
"timestamp": int*,
"title": str*,
"description": str*,
"severity": int*,
"link": str,
"tags": [str],
"iocs": IOCs,
"iocs_v2": [IOC_V2],
"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*}
{"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*}
{"name": str*,
"report_ids": [str]*,
"description": str*,
"watchlist_id": str,
"tags_enabled": bool,
"alerts_enabled": bool,
"create_timestamp": int*,
"last_update_timestamp": int*}
{"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}