Latest Updates: CbAPI 1.4.0 Released

Watchlist API for PSC ThreatHunter

API Paths

Watchlist API Definition
Version: 1.0.0

Healthcheck

Successful response indicates service reachability.

Request

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

Responses

Code Description content-type Content
204Report deleted*/* None
404report 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": <a href="#iocs">IOCs</a>,
 "iocs_v2": [<a href="#ioc_v2">IOC_V2</a>],
 "visibility": str}

IOCs

{"md5": [str],
 "ipv4": [str],
 "ipv6": [str],
 "dns": [str],
 "query": [<a href="#queryioc">QueryIOC</a>]}

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": <a href="#classifierwatchlist">ClassifierWatchlist</a>,
 "report": <a href="#reportwatchlist">ReportWatchlist</a>}

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": <a href="#classifierkeyvalue">ClassifierKeyValue</a>}
Last modified on December 13, 2018