WARNING: This is a legacy document, please view the latest version
here.
API Paths
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 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*}
|
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
|
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}