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
204service 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
200Watchlist created.application/json Watchlist
400invalid 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
200Array of watchlistsapplication/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
200Return watchlistapplication/json Watchlist
400Unknown 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
200Return watchlistapplication/json Watchlist
400Unknown 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
204Watchlist deleted*/* None
400Unknown 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
200Returns alert statusapplication/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
200Returns alert statusapplication/json {"alert": boolean*}
400Unknown 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
204Returns alert status*/* None
400Unknown 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
200Returns tag statusapplication/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
200Returns tag statusapplication/json {"tag": boolean*}
400Unknown 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
204Tagging stopped*/* None
400Unknown 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
200Returns ignore statusapplication/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
200Returns ignore statusapplication/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
204Report is active*/* None
400Unknown 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
200Returns ignore statusapplication/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
200Returns ignore statusapplication/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
204Ignore removed - IOC is active*/* None
400Unknown 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
200Returns list of report severitiesapplication/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
200Returns severity. (null if not set)application/json ReportSeverity
404No 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
200Returns 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
204Severity 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
200Report createdapplication/json Report
400invalid 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
200Report updatedapplication/json Report
400invalid report request.*/* None
404report 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
200Reportapplication/json Report
404report 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
204Report deleted*/* None
404report 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