Watchlist API for Enterprise EDR

WARNING: This is a legacy document, please view the latest version here.

Carbon Black Cloud Enterprise EDR (Endpoint Detection and Response) is the new name for the product formerly called CB ThreatHunter.

API Paths

Watchlist API Definition

Note: <cbc-hostname> is the parent URL for your Carbon Black Cloud instance.

Healthcheck

Successful response indicates service reachability.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/healthcheck

Responses

Code	Description	content-type	Content
204	service is available	/	None

Create a New Watchlist

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.

Request

POST <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist

Watchlist Payload

content-type	Content
application/json	Watchlist

Responses

Code	Description	content-type	Content
200	Watchlist created.	application/json	Watchlist
400	invalid watchlist request.	application/json	None

Get All Watchlists

Retrieve all watchlists owned by the requester.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist

Responses

Code	Description	content-type	Content
200	Array of watchlists	application/json	{"results": [Watchlist]}

Get Specific Watchlist

Retrieve watchlist with specified watchlist_id.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)

Responses

Code	Description	content-type	Content
200	Return watchlist	application/json	Watchlist
400	Unknown watchlist.	/	None

Update Watchlist

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.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)

Watchlist Payload

content-type	Content
application/json	Watchlist

Responses

Code	Description	content-type	Content
200	Return watchlist	application/json	Watchlist
400	Unknown watchlist or malformed request.	/	None

Delete Watchlist

Remove watchlist specified by watchlist_id. Existing hits for this watchlist will remain in the system.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)

Responses

Code	Description	content-type	Content
204	Watchlist deleted	/	None
400	Unknown watchlist.	/	None

Get Watchlist Alert Status

Retrieve the alert status for watchlist with watchlist_id.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert

Responses

Code	Description	content-type	Content
200	Returns alert status	application/json	{"alert": boolean*}

Enable Watchlist Alerts

Turn on alerts for watchlist with watchlist_id. This is not retroactive for existing watchlist hits, only future hits will trigger alerts.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert

Responses

Code	Description	content-type	Content
200	Returns alert status	application/json	{"alert": boolean*}
400	Unknown watchlist	/	None

Disable Watchlist Alerts

Turn off alerts for watchlist with watchlist_id. This is not retroactive for existing watchlist alerts, only future hits will not trigger alerts.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/alert

Responses

Code	Description	content-type	Content
204	Returns alert status	/	None
400	Unknown watchlist	/	None

Get Watchlist Tag Status

Retrieve tag status for watchlist with watchlist_id.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag

Responses

Code	Description	content-type	Content
200	Returns tag status	application/json	{"tag": boolean*}

Enable Watchlist Tags

Turn on tagging for watchlist with watchlist_id. This is not retroactive for existing watchlist matches, only future matches will trigger event tagging.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag

Responses

Code	Description	content-type	Content
200	Returns tag status	application/json	{"tag": boolean*}
400	Unknown watchlist	/	None

Disable Watchlist Tags

Turn off tagging for watchlist with watchlist_id. This is not retroactive for existing watchlist tags, only future matches will not trigger event tagging.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/watchlist/(watchlist_id)/tag

Responses

Code	Description	content-type	Content
204	Tagging stopped	/	None
400	Unknown watchlist	/	None

Get Report Ignore Status

Get current ignore status for report with report_id.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore

Responses

Code	Description	content-type	Content
200	Returns ignore status	application/json	{"ignored": boolean*}

Ignore Report

Report with report_id and all contained IOCs will not match future events for any watchlist.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore

Responses

Code	Description	content-type	Content
200	Returns ignore status	application/json	{"ignored": boolean*}

Re-activate Report

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.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ignore

Responses

Code	Description	content-type	Content
204	Report is active	/	None
400	Unknown report	/	None

Get IOC Ignore Status

Get current ignore status for IOC ioc_id in report report_id.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore

Responses

Code	Description	content-type	Content
200	Returns ignore status	application/json	{"ignored": boolean*}

Ignore IOC

IOC ioc_id for report report_id will not match future events for any watchlist.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore

Responses

Code	Description	content-type	Content
200	Returns ignore status	application/json	{"ignored": boolean*}

Re-activate IOC

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.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)/ioc/(ioc_id)/ignore

Responses

Code	Description	content-type	Content
204	Ignore removed - IOC is active	/	None
400	Unknown report/ioc	/	None

Get Custom Report Severities

Return all custom report severities. Custom report severities effect all watchlists.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/severity

Responses

Code	Description	content-type	Content
200	Returns list of report severities	application/json	{"results": [ReportSeverity]}

Get custom severity for report

Return custom severity for report_id. This will return 404 error if custom severity doesn’t exist.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)

Responses

Code	Description	content-type	Content
200	Returns severity. (null if not set)	application/json	ReportSeverity
404	No override for report	/	None

Set Custom Report Severity

Adjust the severity of report with report_id. This will effect all watchlists.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)

Responses

Code	Description	content-type	Content
200	Returns severity.	application/json	ReportSeverity

Remove Custom Report Severity

Remove custom severity for report with report_id.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/severity/report/(report_id)

Responses

Code	Description	content-type	Content
204	Severity override removed	/	None

Create New Report

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.

Request

POST <cbc-hostname>/threathunter/watchlistmgr/v1/report

Report Payload

content-type	Content
application/json	Report

Responses

Code	Description	content-type	Content
200	Report created	application/json	Report
400	invalid report request.	/	None

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 IOC_V2. The report must be owned by the caller.

Request

PUT <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)

Report Payload

content-type	Content
application/json	Report

Responses

Code	Description	content-type	Content
200	Report updated	application/json	Report
400	invalid report request.	/	None
404	report id not found	/	None

Get Report

Retrieve report with report_id. The report must be owned by the requester.

Request

GET <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)

Responses

Code	Description	content-type	Content
200	Report	application/json	Report
404	report id not found	/	None

Remove Report

Remove report with report_id. The report must be owned by the caller.

Request

DELETE <cbc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)

Responses

Code	Description	content-type	Content
204	Report deleted	/	None
404	report id not found	/	None

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.

###Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/(watchlist_ids)/telemetry

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

Report

{"id": str*,
 "timestamp": int*,
 "title": str*,
 "description": str*,
 "severity": int*,
 "link": str,
 "tags": [str],
 "iocs": IOCs,
 "iocs_v2": [IOC_V2],
 "visibility": str}

IOCs

{"md5": [str],
 "ipv4": [str],
 "ipv6": [str],
 "dns": [str],
 "query": [QueryIOC]}

IOC_V2

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

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

{"name": str*,
 "report_ids": [str]*,
 "description": str*,
 "watchlist_id": str,
 "tags_enabled": bool,
 "alerts_enabled": bool,
 "create_timestamp": int*,
 "last_update_timestamp": int*}

Watchlist

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

Last modified on November 12, 2022

Page Contents

Watchlist API for Enterprise EDR

API Paths

Healthcheck

Request

Responses

Create a New Watchlist

Request

Watchlist Payload

Responses

Get All Watchlists

Request

Responses

Get Specific Watchlist

Request

Responses

Update Watchlist

Request

Watchlist Payload

Responses

Delete Watchlist

Request

Responses

Get Watchlist Alert Status

Request

Responses

Enable Watchlist Alerts

Request

Responses

Disable Watchlist Alerts

Request

Responses

Get Watchlist Tag Status

Request

Responses

Enable Watchlist Tags

Request

Responses

Disable Watchlist Tags

Request

Responses

Get Report Ignore Status

Request

Responses

Ignore Report

Request

Responses

Re-activate Report

Request

Responses

Get IOC Ignore Status

Request

Responses

Ignore IOC

Request

Responses

Re-activate IOC

Request

Responses

Get Custom Report Severities

Request

Responses

Get custom severity for report

Request

Responses

Set Custom Report Severity

Request

Responses

Remove Custom Report Severity

Request

Responses

Create New Report

Request

Report Payload

Responses

Update a Report

Request

Report Payload

Responses

Get Report