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

Introduction

The Watchlist API enables you to manage Watchlists for your organization throughout their lifecycle - creation, update and removal - as well as associated Reports and IOCs.

It allows you to manage both Watchlists subscribed from third party threat intelligence feeds (aka “classifier” watchlists) and those custom built for your organization’s specific needs from new and/or existing Reports (aka “report” watchlists).

With visibility across your fleet of monitored endpoints, you can identify processes that are acting abnormally and over time, focus your watchlists to generate hits and alerts only for unexpected or unwanted activity. This includes:

  • Creating new report Watchlists from scratch and add/remove/disable/enable new or existing Reports to that custom Watchlist
  • Configuring or disabling existing Watchlists including enabling “tagging” aka generating “hits” and/or “alerting” aka generating Watchlist Alerts
  • Configuring or deleting Reports and their included IOCs
  • Disabling (ignore) individual Reports and IOCs to stop generating tagged events aka hits in otherwise-tagging-enabled Watchlists

The information model for Carbon Black Cloud Watchlists is comprised of three units of information:

  • IOCs are the smallest unit of information - a single indicator of compromise, to be searched across your organization’s Enterprise EDR data
  • Reports collect one or more IOCs together as a unit of control - all collected IOCs can be enabled or disabled from generating hits and alerts in a single action
  • Watchlists collect one or more Reports together as another unit of control - all Reports in one Watchlist can be enabled or disabled for Alerting or reporting in your organization in a single action

Requirements

  • Enterprise EDR product
  • All API calls require an API key with appropriate permissions

Healthcheck

Successful response indicates service reachability.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/healthcheck

Response

Code Description Content-Type Content
204 Service is available application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Create New Watchlist

Create a new report or classifier watchlist. Unique watchlist ID will be generated by the service. Request must only specify report_ids (for report watchlist) or classifier (for classifier watchlist), but not both.

RBAC Permissions Required

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

Request

POST {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists

Request Body

{
 "name": "<string>",
 "description": "<string>",
 "tags_enabled": "<boolean>",
 "alerts_enabled": "<boolean>",
 "report_ids": ["<string>"],
 "classifier": ClassifierKeyValue
}

Body Schema

Field Definition Data Type Values
name REQUIRED Watchlist name String N/A
description Watchlist description String N/A
tags_enabled Whether tags should be enabled for this watchlist Boolean true, false
alerts_enabled Whether alerts should be enabled for this watchlist Boolean true, false
report_ids Report ID’s to attach to this watchlist [String] N/A
classifier Watchlist classifier key and value ClassifierKeyValue N/A

Response

Code Description Content-Type Content
200 Watchlist successfully created application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists

Request Body 

{
 "name": "My Watchlist",
 "description": "Watchlist subscribed to a Feed",
 "tags_enabled": true,
 "alerts_enabled": false,
 "classifier": {
   "key": "feed_id",
   "value": "ABCDEFGHIJKLMNOPQRSTU"
 }
}

Response 

{
    "name": "My Watchlist",
    "description": "Watchlist subscribed to a Feed",
    "id": "MEjVbdeyS1uJtQ8auEq3A",
    "tags_enabled": true,
    "alerts_enabled": false,
    "create_timestamp": 1604693936,
    "last_update_timestamp": 1604693936,
    "report_ids": null,
    "classifier": {
      "key": "feed_id",
      "value": "ABCDEFGHIJKLMNOPQRSTU"
  }
}

Get All Watchlists

Retrieve all watchlists owned by the caller.

Note that classifier watchlists will include a null-value report object, and report watchlists will include a null-value classifier object.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists

Response

Code Description Content-Type Content
200 Successfully retrieved watchlists application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists

Response 

{
    "results": [
        {
            "name": "My Watchlist",
            "description": "Watchlist subscribed to Reports",
            "id": "5LKpHr2SHiaE2QprfPhQ",
            "tags_enabled": true,
            "alerts_enabled": true,
            "create_timestamp": 1553542270,
            "last_update_timestamp": 1553542270,
            "report_ids": [
              "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
              "MLRtPcpQGKFh5OE4BT3tQ-e31ff772-6ca3-48ee-94ad-08de7dcea717"
            ],
            "classifier": null
        },
        {
            "name": "My Other Watchlist",
            "description": "Watchlist subscribed to a Feed",
            "id": "R4cMgFIhRaakgk749MRr6Q",
            "tags_enabled": true,
            "alerts_enabled": true,
            "create_timestamp": 1578078507,
            "last_update_timestamp": 1599574461,
            "report_ids": null,
            "classifier": {
              "key": "feed_id",
              "value": "ABCDEFGHIJKLMNOPQRSTU"
            }
        }
    ]
}

Get Watchlist

Retrieve watchlist with watchlist_id.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}

Response

Code Description Content-Type Content
200 Successfully retrieved watchlist application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q

Response 

{
  "name": "My Other Watchlist",
  "description": "Watchlist subscribed to a Feed",
  "id": "R4cMgFIhRaakgk749MRr6Q",
  "tags_enabled": true,
  "alerts_enabled": true,
  "create_timestamp": 1578078507,
  "last_update_timestamp": 1599574461,
  "report_ids": null,
  "classifier": {
    "key": "feed_id",
    "value": "ABCDEFGHIJKLMNOPQRSTU"
  }
}

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

Alerting is not supported on the following feeds due to the volume of hits:

  • ATT&CK Framework
  • Carbon Black Early Access Indicators
  • Carbon Black Endpoint Visibility
  • Carbon Black Suspicious Indicators

Attempting to enable an alert on any of these feeds will result in a 400 error.

Further information is available here.

RBAC Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}

Request Body

{
 "name": "<string>",
 "description": "<string>",
 "tags_enabled": "<boolean>",
 "alerts_enabled": "<boolean>",
 "report_ids": ["<string>"],
 "classifier": ClassifierKeyValue
}

Body Schema

Field Definition Data Type Values
name Watchlist name String N/A
description Watchlist description String N/A
tags_enabled Whether tags should be enabled for this watchlist Boolean true, false
alerts_enabled Whether alerts should be enabled for this watchlist Boolean true, false
report_ids Report ID’s to attach to this watchlist [String] N/A
classifier Watchlist classifier key and value ClassifierKeyValue N/A

Response

Code Description Content-Type Content
200 Watchlist successfully updated application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q

Request Body 

{
  "name": "New Name for My Watchlist",
  "description": "Updated Watchlist subscribed to a Feed",
  "tags_enabled": false,
  "alerts_enabled": false,
  "classifier": {
    "key": "feed_id",
    "value": "FGHIJKLMNOPQRSTUVWXYZ"
  }
}

Response 

{
    "name": "New Name for My Watchlist",
    "description": "Updated Watchlist subscribed to a Feed",
    "id": "R4cMgFIhRaakgk749MRr6Q",
    "tags_enabled": false,
    "alerts_enabled": false,
    "create_timestamp": 1604693936,
    "last_update_timestamp": 1604694841,
    "report_ids": null,
    "classifier": {
        "key": "feed_id",
        "value": "FGHIJKLMNOPQRSTUVWXYZ"
    }
}

Delete Watchlist

Remove watchlist with watchlist_id. Existing hits for this watchlist will remain in the Carbon Black Cloud for the data retention period.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}

Response

Code Description Content-Type Content
204 Successfully deleted watchlist application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q

Response 

204 No Content

Delete All Watchlists

Remove all of an organization’s watchlists. Existing hits for watchlists will remain in the system.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists

Response

Code Description Content-Type Content
204 Successfully deleted all watchlists application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists

Response 

204 No Content

Get Watchlist Alert Status

Retrieve alert status for watchlist with watchlist_id i.e. whether the watchlist will generate alerts or not.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert

Response

Code Description Content-Type Content
200 Successfully retrieved watchlist alert status application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q

Response 

{
  "alert": true
}

Enable Watchlist Alerts

Turn on alerts for watchlist with watchlist_id. This is not retroactive for existing watchlist hits; alerts will not be generated for previous watchlist hits. Future hits will trigger alerts.

Alerting is not supported on the following feeds due to the volume of hits:

  • ATT&CK Framework
  • Carbon Black Early Access Indicators
  • Carbon Black Endpoint Visibility
  • Carbon Black Suspicious Indicators

Attempting to enable an alert on any of these feeds will result in a 400 error.

Further information is available here.

RBAC Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert

Request Body

{
  "alert": "<boolean>"
}

Body Schema

Field Definition Data Type Values
alert Whether alerts should be enabled or disabled Boolean true

Response

Code Description Content-Type Content
200 Successfully updated alerting for the watchlist application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/alert

Request Body 

{
  "alert": true
}

Response 

{
  "alert": true
}

Disable Watchlist Alerts

Turn off alerts for watchlist with watchlist_id. This is not retroactive for existing watchlist alerts, as watchlist alerts previously generated will not be removed. Future hits will not trigger alerts.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/alert

Response

Code Description Content-Type Content
204 Successfully turned off alerting for the watchlist application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/alert

Response 

No Content

Disable All Watchlist Alerts

Turn off alerts for all watchlists. This is not retroactive for existing watchlist alerts. Future hits will not trigger alerts.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/alert

Response

Code Description Content-Type Content
204 Successfully turned off alerts for all watchlists application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/alert

Response 

204 No Content

Get Watchlist Tag Status

Determine whether tagging (aka generating “watchlist hits” from IOC matches) is enabled for watchlist with watchlist_id.

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag

RBAC Permissions Required

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

Response

Code Description Content-Type Content
200 Successfully retrieved tag status for this watchlist application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag

Response 

{
  "tag": true
}

Enable Watchlist Tags

Turn on tagging (aka generating “watchlist hits”) 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)
org.watchlists UPDATE

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag

Request Body

{
    "tag": "<boolean>"
}

Body Schema

Field Definition Data Type Values
tag REQUIRED Whether to turn on tagging for this watchlist Boolean true

Response

Code Description Content-Type Content
200 Successfully updated watchlist tag status application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag

Request Body 

{
  "tag": true
}

Response 

{
  "tag": true
}

Disable Watchlist Tags

Turn off tagging (aka stop generating “watchlist hits”) for watchlist with watchlist_id. This is not retroactive for existing watchlist tags/hits. Future matches will not generate tagged events.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/{watchlist_id}/tag

Response

Code Description Content-Type Content
204 Successfully turned off tagging for this watchlist application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/R4cMgFIhRaakgk749MRr6Q/tag

Response 

204 No Content

Disable All Watchlist Tags

Turn off tagging (aka stop generating “watchlist hits”) for all watchlists. This is not retroactive for existing watchlist tags. Future matches will not generate tagged events.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/tag

Response

Code Description Content-Type Content
204 Successfully turned off tagging for all watchlists application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/watchlists/tag

Response 

204 No Content

Get Report Ignore Status

Get current ignore status for report with report_id i.e. whether that report has been disabled such that any watchlist that includes the report will not generate hits for any IOCs in that report. ignore: true indicates the report is disabled.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore

Response

Code Description Content-Type Content
200 Successfully retrieved ignore status for this report application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore

Response 

{
    "ignored": false
}

Ignore Report

Report with report_id and all contained IOCs will not match future events for any watchlist i.e. that report will be disabled such that any watchlist that includes the report will not generate hits for any IOCs in that report.

RBAC Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore

Request Body 

{
  "ignore": "<boolean>"
}

Body Schema

Field Definition Data Type Values
ignore REQUIRED Whether to ignore this report Boolean true

Response

Code Description Content-Type Content
200 Successfully updated ignore status for this report application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore

Request Body 

{
  "ignore": true
}

Response 

{
  "ignore": true
}

Re-activate Report

Report with report_id and all contained IOCs will match future events for all watchlists i.e. if that report has been disabled (ignored), it will be re-enabled such that any watchlist that includes the report will start generating hits for any IOCs in that report. This is not retroactive for events that occured while the report was ignored.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/ignore

Response

Code Description Content-Type Content
204 Successfully reactivated this report application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/ignore

Response 

204 No Content

Get IOC Ignore Status

Get current ignore status for IOC ioc_id in report report_id i.e. whether that IOC has been disabled such that the watchlist report that includes the IOC will not generate hits for that IOC.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore

Response

Code Description Content-Type Content
200 Successfully retrieved ignore status for this IOC application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore

Response 

{
    "ignored": false
}

Ignore IOC

IOC ioc_id for report report_id will not match future events for any watchlist i.e. this IOC will be disabled such that the watchlist report that includes the IOC will not generate hits for that IOC.

RBAC Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore

Request Body 

{
  "ignore": true
}

Body Schema

Field Definition Data Type Values
ignore REQUIRED Whether to ignore this IOC Boolean true

Response

Code Description Content-Type Content
200 Successfully updated ignore status for this IOC application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore

Request Body 

{
  "ignore": true
}

Response 

{
  "ignore": true
}

Re-activate IOC

IOC ioc_id for report report_id and will match future events for all watchlists i.e. this IOC has been disabled and will be re-enabled such that the watchlist report that includes the IOC will start generating hits for this IOC. This is not retroactive for events that occured while the IOC was ignored.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/iocs/{ioc_id}/ignore

Response

Code Description Content-Type Content
204 Successfully reactivated this IOC application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/iocs/dbba26e0-d2a2-4de2-9691-a44392dedf38-0/ignore

Response 

204 No Content

Get Custom Report Severities

Return all custom report severities. Custom report severities effect all watchlists.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/severity

Response

Code Description Content-Type Content
200 Successfully retrieved custom report severities application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/severity

Response 

{
    "results": [
      {
        "report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-12345678910",
        "severity": 9
      },
      {
        "report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-01987654321",
        "severity": 4
      },
    ]
}

Get Custom Severity for Report

RBAC Permissions Required

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

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity

Response

Code Description Content-Type Content
200 Successfully retrieved custom report severity application/json View example response below
403 Forbidden N/A N/A
404 Not Found application/json 
 404: No custom severity exists for report: {report_id}
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity

Response 

{
    "report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
    "severity": 4
}

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity

Request Body { “report_id”: “”, “severity”: “” }

Body Schema

Field Definition Data Type Values
report_id REQUIRED ID of the report to modify String N/A
severity REQUIRED Custom severity level Integer N/A

Response

Code Description Content-Type Content
200 Successfully updated custom report severity application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity

Request Body 

{
    "report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
    "severity": 4
}

Response 

{
    "report_id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
    "severity": 4
}

Remove Custom Report Severity

Remove custom severity for report with report_id.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}/severity

Response

Code Description Content-Type Content
204 Successfully deleted custom severity for this report application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38/severity

Response 

204 No Content

Create New Report

Adds a new watchlist report. This endpoint will return a unique report id - the ‘id’ field is not required nor accepted as input for this request. This report will be private to the caller - i.e. only available in the requesting organization. IOCs will be converted to IOC_V2.

RBAC Permissions Required

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

Request

POST {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports

Request Body 

{
 "title": "<string>",
 "description": "<string>",
 "timestamp": "<integer>",
 "severity": "<integer>",
 "link": "<string>",
 "tags": ["<string>"],
 "iocs": IOCs,
 "iocs_v2": [IOCv2],
 "visibility": "<string>"
}

Body Schema

Field Definition Data Type Values
title REQUIRED Report title String N/A
description REQUIRED Report description String N/A
timestamp REQUIRED UNIX Epoch timestamp to associate with the report Integer N/A
severity REQUIRED Report severity Integer Between 1 and 10, inclusive
link A URL to associate with the report String N/A
tags Report tags [String] N/A
iocs IOCs to associate with the report IOCs IOCs
iocs_v2 IOCv2’s to associate with the report. Preferred over IOCs. Array IOCv2
visibility Report visibility String N/A

Response

Code Description Content-Type Content
200 Successfully created this report application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports

Request Body 

{
  "title": "Persistence - Possible Tibet.c Backdoor Installation",
  "description": "This query identifies files that are known to be associated with the installation of a backdoor in OSX.\n\nThreat:\nThis activity is associated with multiple variants of Tibet.c\n\nFalse Positives:\nWe are currently unaware of any specific conditions that would generate false positives for this query. Any hits would most likely warrant further investigation.\n\nScore:\n100",
  "timestamp": 1603123890,
  "severity": 10,
  "link": "https://community.carbonblack.com/t5/Threat-Research-Docs/Cb-Response-Advanced-Threats-Threat-Intel-Feed/ta-p/38756",
  "tags": [
      "malware",
      "backdoor",
      "tibet",
      "attackframework",
      "attack",
      "t1543",
      "peristence",
      "osx",
      "macos"
  ],
  "iocs": null,
  "iocs_v2": [
      {
          "id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
          "match_type": "query",
          "values": [
              "((filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\" OR filemod_name:\"\/Library\/LaunchAgents\/com.apple.AudioService.plist\" AND device_os:MAC)) -enriched:true"
          ],
          "field": null,
          "link": null
      }
  ],
  "visibility": "visible"
}

Response 

{
  "id": "MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38",
  "timestamp": 1603123890,
  "title": "Persistence - Possible Tibet.c Backdoor Installation",
  "description": "This query identifies files that are known to be associated with the installation of a backdoor in OSX.\n\nThreat:\nThis activity is associated with multiple variants of Tibet.c\n\nFalse Positives:\nWe are currently unaware of any specific conditions that would generate false positives for this query. Any hits would most likely warrant further investigation.\n\nScore:\n100",
  "severity": 10,
  "link": "https://community.carbonblack.com/t5/Threat-Research-Docs/Cb-Response-Advanced-Threats-Threat-Intel-Feed/ta-p/38756",
  "tags": [
      "malware",
      "backdoor",
      "tibet",
      "attackframework",
      "attack",
      "t1543",
      "peristence",
      "osx",
      "macos"
  ],
  "iocs": null,
  "iocs_v2": [
      {
          "id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
          "match_type": "query",
          "values": [
              "((filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\" OR filemod_name:\"\/Library\/LaunchAgents\/com.apple.AudioService.plist\" AND device_os:MAC)) -enriched:true"
          ],
          "field": null,
          "link": null
      }
  ],
  "visibility": "visible"
}

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 IOCv2. The report must be owned by the caller.

RBAC Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}

Request Body 

{
 "title": "<string>",
 "description": "<string>",
 "timestamp": "<integer>",
 "severity": "<integer>",
 "link": "<string>",
 "tags": ["<string>"],
 "iocs": IOCs,
 "iocs_v2": [IOCv2],
 "visibility": "<string>"
}

Body Schema

Field Definition Data Type Values
title Report title String N/A
description Report description String N/A
timestamp UNIX Epoch timestamp to associate with the report Integer N/A
severity Report severity Integer Between 1 and 10, inclusive
link A URL to associate with the report String N/A
tags Report tags [String] N/A
iocs IOCs to associate with the report IOCs IOCs
iocs_v2 IOCv2’s to associate with the report. Preferred over IOCs. Array IOCv2
visibility Report visibility String N/A

Response

Code Description Content-Type Content
200 Successfully updated this report application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw

Request Body 

{
  "title": "My New Title",
  "description": "My New Description",
  "timestamp": 1604702592,
  "severity": 1,
  "tags": [
      "macos"
  ],
  "iocs_v2": [
      {
          "id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
          "match_type": "query",
          "values": [
              "filemod_name:\"\/Library\/Audio\/Plug\\-Ins\/Components\/AudioService\""
          ]
      }
  ],
  "visibility": "visible"
}

Response 

{
    "id": "UZDbBhFPTamJbZGQcwUHEw",
    "timestamp": 1604702592,
    "title": "My New Title",
    "description": "My New Description",
    "severity": 1,
    "link": null,
    "tags": [
        "macos"
    ],
    "iocs": null,
    "iocs_v2": [
        {
            "id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
            "match_type": "query",
            "values": [
                "filemod_name:\"/Library/Audio/Plug\\-Ins/Components/AudioService\""
            ],
            "field": null,
            "link": null
        }
    ],
    "visibility": "visible"
}

Get Report

Retrieve report with report_id. The report must be owned by the caller.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}

Response

Code Description Content-Type Content
200 Successfully retrieved report application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw

Response 

{
    "id": "UZDbBhFPTamJbZGQcwUHEw",
    "timestamp": 1604702592,
    "title": "My New Title",
    "description": "My New Description",
    "severity": 1,
    "link": null,
    "tags": [
        "macos"
    ],
    "iocs": null,
    "iocs_v2": [
        {
            "id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0",
            "match_type": "query",
            "values": [
                "filemod_name:\"/Library/Audio/Plug\\-Ins/Components/AudioService\""
            ],
            "field": null,
            "link": null
        }
    ],
    "visibility": "visible"
}

Remove Report

Remove report with report_id. The report must be owned by the caller.

RBAC Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_id}

Response

Code Description Content-Type Content
204 Successfully deleted this report application/json None
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw

Response 

204 No Content

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/{report_ids}/ignore/bulk

Response

Code Description Content-Type Content
200 Successfully retrieved report and IOC ignore statuses application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw,UZDbBhFPTamJb123456789/ignore/bulk

Response 

{
  "results": [
      {
        "ignore": false,
        "report_id": "UZDbBhFPTamJbZGQcwUHEw",
        "ioc_id": null
      },
      {
        "ignore": true,
        "report_id": "UZDbBhFPTamJb123456789",
        "ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
      }
  ]
}

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

Request

PUT {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/reports/ignore/bulk

Request Body 

{
  "ignores": [
    {
      "ignore": "<boolean>",
      "report_id": "<string>",
      "ioc_id": "<string>",
    },
    {
      "ignore": "<boolean>",
      "report_id": "<string>",
      "ioc_id": "<string>",
    }
  ]
}

Body Schema

Field Definition Data Type Values
ignore REQUIRED Whether to ignore the specified report and it’s IOCs Boolean true, false
report_id REQUIRED ID of the Report to modify ignore status String N/A
ioc_id ID of the IOC to modify ignore status. Defaults to all IOCs if not specified. String N/A

Response

Code Description Content-Type Content
200 Successfully updated report and IOC ignore statuses application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw,UZDbBhFPTamJb123456789/ignore/bulk

Request Body 

{
  "ignores": [
    {
      "ignore": true,
      "report_id": "UZDbBhFPTamJbZGQcwUHEw",
      "ioc_id": null
    },
    {
      "ignore": false,
      "report_id": "UZDbBhFPTamJbZGQcwUHEw",
      "ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
    }
  ]
}

Response 

{
  "results": [
  {
    "ignore": true,
    "report_id": "UZDbBhFPTamJbZGQcwUHEw",
    "ioc_id": null
  },
  {
    "ignore": false,
    "report_id": "UZDbBhFPTamJbZGQcwUHEw",
    "ioc_id": "dbba26e0-d2a2-4de2-9691-a44392dedf38-0"
  }
  ]
}

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

Request

GET {cbc-hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists/(watchlist_ids)/telemetry

Query Schema

Field Definition Data Type Values
intervals Intervals to retrieve telemetry data for, in minutes Comma separated integers N/A

Response

Code Description Content-Type Content
200 Successfully retrieved telemetry application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/UZDbBhFPTamJbZGQcwUHEw/telemetry?intervals=1440,10080,43200

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 unless otherwise noted

Report

{
 "id": str*,
 "timestamp": int*,
 "title": str*,
 "description": str*,
 "severity": int*,
 "link": str,
 "tags": [str],
 "iocs": IOCs,
 "iocs_v2": [IOCv2],
 "visibility": str
}

IOCs

{
 "md5": [str],
 "ipv4": [str],
 "ipv6": [str],
 "dns": [str],
 "query": [QueryIOC]
}

IOCv2

{
 "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

A classifier watchlist is one subscribed from a Carbon Black Cloud-published third party threat intelligence Feed.

{
 "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

A report watchlist is one created for the organization, constructed from new and existing Reports.

{
 "name": str*,
 "report_ids": [str]*,
 "description": str,
 "watchlist_id": str,
 "tags_enabled": bool,
 "alerts_enabled": bool,
 "create_timestamp": int,
 "last_update_timestamp": int
}

Watchlist

A Watchlist object may populate one or other of the "classifier" or "report" objects but not both.

{
 "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.

Which fields can be used in which types of IOCs? Consult the Platform Search Fields documentation for a list of all possible fields to use in Watchlists:

  • query IOCs can use any Platform Search field which is documented as Searchable
  • equality and regex IOCs can use any Platform Search field, except the Aggregation only fields i.e. num_devices, num_events

Equality IOCv2

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

Regular Expression IOCv2

This regular expression looks for double file extensions.

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

Query IOCv2

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