API Paths

Watchlist API Definition
Note: <psc-hostname> is the parent URL for your Carbon Black Cloud instance.

Healthcheck

Successful response indicates service reachability.

Request

GET <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-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 <psc-hostname>/threathunter/watchlistmgr/v1/report/(report_id)

Responses

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

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}