Watchlist API for Enterprise EDR

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

Version: v3

Healthcheck

Successful response indicates service reachability.

RBAC Permissions Required

Permission (.notation name) Operation(s)
No Permissions Required N/A

Request

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

Responses

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

Create New Watchlist

Create a new report or classifier watchlist. Unique watchlist ID will be generated by the service. Request must specify report or classifier but not both.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists CREATE

Request

POST <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists

Watchlist payload
content-type content
application/json WatchlistV2
Responses
code description content-type content
200Watchlist created.application/json WatchlistV2
400invalid watchlist request.application/json None

Get All Watchlists

Retrieve all watchlists owned by the caller.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists

Responses

code description content-type content
200Array of watchlistsapplication/json {"results": [WatchlistV2]}

Get Watchlist

Retrieve watchlist with watchlist_id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_id)

Responses

code description content-type content
200Return watchlistapplication/json WatchlistV2
400Unknown watchlist.*/* None

Update Watchlist

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 (ie tags_enabled) that field will not be updated. Cannot update report watchlist with empty report_ids list.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_id)

Watchlist payload
content-type content
application/json WatchlistV2
Responses
code description content-type content
200Return watchlistapplication/json WatchlistV2
400Unknown watchlist or malformed request.*/* None

Delete Watchlist

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_id)

Responses

code description content-type content
204Watchlist deleted*/* None
400Unknown watchlist.*/* None

Get Watchlist Alert Status

Retrieve alert status for watchlist with watchlist_id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(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. Future hits will trigger alerts.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(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. Future hits will not trigger alerts.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_id)/alert

Responses

code description content-type content
204Returns alert status*/* None
400Unknown watchlist*/* None

Get Watchlist Tag Status

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_id)/tag

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

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. Future matches will trigger event tagging.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(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. Future matches will not trigger event tagging.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(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 occured while the report was ignored.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/iocs/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/iocs/(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 occured while the IOC was ignored.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/iocs/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/severity

Responses

code description content-type content
200Returns list of report severitiesapplication/json {"results": [ReportSeverity]}

Get Custom Severity for Report

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

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

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/severity

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/severity

Responses

code description content-type content
200Returns severity.application/json ReportSeverity

Remove Custom Report Severity

Remove custom severity for report with report_id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)/severity

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists CREATE

Request

POST <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports
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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(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 caller.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists DELETE

Request

DELETE <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_id)

Responses

code description content-type content
204Report deleted*/* None
404report id not found*/* None

Get Ignore Status for Provided Report IDs

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)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/(report_ids)/ignore/bulk

Responses

code description content-type content
200Return list of ignored statesapplication/json {"results": [ReportIOCIgnore]}

Bulk Ignore Report and IOCs

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)
threathunter.watchlists UPDATE

Request

PUT <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/reports/ignore/bulk
Report IOC Ignore List
content-type content
application/json ReportIOCIgnoreList

Responses

code description content-type content
200Returns ignore status arrayapplication/json ReportIOCIgnoreList

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.watchlists READ

Request

GET <psc-hostname>/threathunter/watchlistmgr/v3/orgs/(org_key)/watchlists/(watchlist_ids)/telemetry

Responses

code description content-type content
200Returns array of telemetry objects for provided intervalsapplication/json WatchlistTelemetryList

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
}

ReportIOCIgnore

{
 "ignore": bool*,
 "report_id": str*,
 "ioc_id": str
}

ReportIOCIgnoreList

{
 "ignores": [ReportIOCIgnore]*
}

WatchlistTelemetry

{
 "watchlist_id": str*,
 "interval": int*,
 "hits": int*,
 "executions": int*
}

WatchlistTelemetryList

{
 "telemetry": [WatchlistTelemetry]*
}

Examples

IOCs

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.

  • An equality IOC will hit when the field value is exactly equal to any of the values.
  • A regex IOC will hit if the field value matches on the regular expression provided in the values array.
  • A query IOC will hit if the query in the values array matches on a particular document. These IOCs are equivalent to running searches on the Investigate page. Query IOCs are useful when you need query language to determine if the process is important enough to generate a hit.

Equality IOC_V2

{
    "id": "1af4e5ff584a",
    "match_type": "equality",
    "field": "process_sha256",
    "values": ["68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728"],
    "link": "https://carbonblack.com"
}

Regular Expression IOC_V2

This regular expression looks for double file extensions.

{
    "id": "1af4e5ff584a",
    "match_type": "regex",
    "field": "process_name",
    "values": ["/\\\\..{3}\\\\..{3}/"],
    "link": "https://carbonblack.com"
}

Query IOC_V2

{
    "id": "1af4e5ff584a",
    "match_type": "query",
    "values": ["process_name:malware.exe"],
    "link": "https://carbonblack.com"
}
Last modified on May 5, 2020