Watchlist API Definition
Note: <psc-hostname> is the parent URL for your PSC 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 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.

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
200	Watchlist created.	application/json	WatchlistV2
400	invalid watchlist request.	application/json	None

Get All Watchlists

Retrieve all watchlists owned by the caller.

Request

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

Responses

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

Get Watchlist

Retrieve watchlist with watchlist_id.

Request

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

Responses

code	description	content-type	content
200	Return watchlist	application/json	WatchlistV2
400	Unknown 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.

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
200	Return watchlist	application/json	WatchlistV2
400	Unknown watchlist or malformed request.	*/*	None

Delete Watchlist

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

Request

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

Responses

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

Get Watchlist Alert Status

Retrieve alert status for watchlist with watchlist_id.

Request

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

Request

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

Request

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

Responses

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

Get Watchlist Tag Status

Request

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

Request

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

Request

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

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

Request

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

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

Request

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

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/v3/orgs/(org_key)/reports/(report_id)/severity

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/v3/orgs/(org_key)/reports/(report_id)/severity

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/v3/orgs/(org_key)/reports

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/v3/orgs/(org_key)/reports/(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 caller.

Request

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

Responses

code	description	content-type	content
204	Report deleted	*/*	None
404	report 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.

Request

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

Responses

code	description	content-type	content
200	Return list of ignored states	application/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).

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
200	Returns ignore status array	application/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.

Request

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

Responses

code	description	content-type	content
200	Returns array of telemetry objects for provided intervals	application/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]*}