Watchlist API for Enterprise EDR

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 Report 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

Want to make this easier? Check out the support for watchlists, reports, and IOCs in the Carbon Black Cloud Python SDK.

Warning: Do not exceed 1k IOCs per report or 10k reports per feed or watchlist. Exceeding the limit will prevent editing or searching IOCs and Reports. Consider breaking up the Threat Intelligence into multiple feeds or combining IOCs or reports.

Requirements

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

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.

CBC Managed Identity

Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

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

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:

org.watchlists, allow permission to CREATE, READ, UPDATE, DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.

CSP Managed Identity

Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

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

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:

_API.Custom.Detections:org.Watchlists, allow permission to CREATE, READ, UPDATE, DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

Watchlist

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 Custom Report Watchlist) or classifier (for Subscribed Feed Watchlist), but not both.

Warning: A watchlist with tags_enabled: false and alerts_enabled: true is not supported and will result in a 400 Bad Request.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

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

Body Schema

Field	Definition	Data Type	Values
`name` REQUIRED	Watchlist name	String
`description`	Watchlist description	String
`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`
`alert_classification_enabled`	Whether Anomaly Classification should be enabled for this watchlist. This can only be enabled on Carbon Black managed feeds which support alert classification	Boolean	`true`, `false`
`report_ids`	Report ID’s to attach to this watchlist	[String]
`classifier`	Watchlist classifier key and value	ClassifierKeyValue

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
403	Forbidden
500	Internal Server Error

Example

Request

POST https://defense.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,
 "alert_classification_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,
    "alert_classification_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: classifier watchlists (Subscribed Feed Watchlists) will include a null-value for report_ids, and report watchlists (Custom Report Watchlists) will include a null-value for the classifier object.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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,
            "alert_classification_enabled": false,
            "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,
            "alert_classification_enabled": false,
            "create_timestamp": 1578078507,
            "last_update_timestamp": 1599574461,
            "report_ids": null,
            "classifier": {
              "key": "feed_id",
              "value": "ABCDEFGHIJKLMNOPQRSTU"
            }
        }
    ]
}

Get Watchlist

Retrieve watchlist with watchlist_id.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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,
  "alert_classification_enabled": false,
  "create_timestamp": 1578078507,
  "last_update_timestamp": 1599574461,
  "report_ids": null,
  "classifier": {
    "key": "feed_id",
    "value": "ABCDEFGHIJKLMNOPQRSTU"
  }
}

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

{
    "watchlist_ids": ["<string>"],
    "intervals": [<integer>]
}

Response

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

Examples

HTTP

Request

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

Request Headers

X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"

Request Body

{
    "watchlist_ids": [
        "UZDbBhFPTamJbZGQcwUHEw"
    ],
    "intervals": [
        1440,
        10080,
        43200
    ]
}

Response Body

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

To download or review the Carbon Black Cloud Postman collection, click here.

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.

Warning: A watchlist with tags_enabled: false and alerts_enabled: true is not supported and will result in a 400 Bad Request.

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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>",
 "alert_classification_enabled": "<boolean>",
 "report_ids": ["<string>"],
 "classifier": ClassifierKeyValue
}

Body Schema

Field	Definition	Data Type	Values
`name`	Watchlist name	String
`description`	Watchlist description	String
`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`
`alert_classification_enabled`	Whether Anomaly Classification should be enabled for this watchlist. This can only be enabled on Carbon Black managed feeds which support alert classification	Boolean	`true`, `false`
`report_ids`	Report ID’s to attach to this watchlist	[String]
`classifier`	Watchlist classifier key and value	ClassifierKeyValue

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
403	Forbidden
500	Internal Server Error

Example

Request

PUT https://defense.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,
  "alert_classification_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,
    "alert_classification_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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

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

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.

Warning: A watchlist with tags_enabled: false and alerts_enabled: true is not supported and will result in a 400 Bad Request.

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
403	Forbidden
500	Internal Server Error

Example

Request

PUT https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Response

Code	Description	Content-Type
204	Successfully turned off alerting for the watchlist	No Content
400	The JSON body was malformed, or some part of the JSON body included an invalid value
403	Forbidden
500	Internal Server Error

Example

Request

DELETE https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Response

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

Example

Request

GET https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

PUT https://defense.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.

Warning: A watchlist with tags_enabled: false and alerts_enabled: true is not supported and will result in a 400 Bad Request.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

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

Response

204 No Content

Reports

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.

Warning: If the link is not null or more than one query IOC is added to the report then the report will NOT be editable in the Carbon Black Cloud console.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
`description` REQUIRED	Report description	String
`timestamp` REQUIRED	UNIX Epoch timestamp to associate with the report	Integer
`severity` REQUIRED	Report severity	Integer	Between 1 and 10, inclusive
`link`	A URL to associate with the report	String
`tags`	Report tags	[String]
`iocs`	IOCs to associate with the report	IOCs	IOC
`iocs_v2`	IOCv2’s to associate with the report. Preferred over IOCs.	Array	IOCv2
`visibility`	Report visibility	String

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
403	Forbidden
500	Internal Server Error

Example

Request

POST https://defense.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 removed from the report. All IOCs will be converted to IOCv2. The report must be owned by the caller.

Warning: If the link is not null or more than one query IOC is added to the report then the report will NOT be editable in the Carbon Black Cloud console.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
`description`	Report description	String
`timestamp`	UNIX Epoch timestamp to associate with the report	Integer
`severity`	Report severity	Integer	Between 1 and 10, inclusive
`link`	A URL to associate with the report	String
`tags`	Report tags	[String]
`iocs`	IOCs to associate with the report	IOCs	IOC
`iocs_v2`	IOCv2’s to associate with the report. Preferred over IOCs.	Array	IOCv2
`visibility`	Report visibility	String

Response

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

Example

Request

PUT https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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"
      }
  ]
}

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

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

Request Body

{
  "ignore": true
}

Response

{
  "ignore": true
}

Bulk Get Report Ignore Status

Get current ignore status for reports and iocs

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

{
  "report_ids": [ "<string>", "<string>" ]
}

Body Schema

Field	Definition	Data Type	Values
`report_ids` REQUIRED	List of report ids to get ignore status	Array

Response

Code	Description	Content-Type	Content
200	Successfully returned ignore status	application/json	View example response below
403	Forbidden
500	Internal Server Error

Example

Request

POST https://defense.conferdeploy.net/threathunter/watchlistmgr/v3/orgs/ABCD1234/reports/ignore/bulk

Request Body

{
  "report_ids": ["MLRtPcpQGKFh5OE4BT3tQ-dbba26e0-d2a2-4de2-9691-a44392dedf38"]
}

Response

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

Bulk Ignore Reports 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).

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
`ioc_id`	ID of the IOC to modify ignore status. Defaults to all IOCs if not specified.	String

Response

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

Example

Request

PUT https://defense.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"
  }
  ]
}

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 occurred while the report was ignored.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

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

Response

204 No Content

Get Custom Report Severities

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

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
404	Not Found	text/plain	`404: No custom severity exists for report: {report_id}`
500	Internal Server Error

Example

Request

GET https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

{
    "report_id": "<string>",
    "severity": "<integer>"
}

Body Schema

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

Response

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

Example

Request

PUT https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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	No Content	None
403	Forbidden
500	Internal Server Error

Example

Request

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

Response

204 No Content

IOCs

Add IOC

Add iocs to report report_id. The report must be owned by the org_key

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`CREATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:create`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Request Body

{
  "iocs": [
    {
      "field": "<string>",
      "id": "<string>",
      "link": "<string>",
      "match_type": "<string>",
      "values": [
        "<string>"
      ]
    }
  ]
}

Body Schema

Field	Definition	Data Type	Values
`iocs` REQUIRED	List of IOCv2 to add.	Array

Response

Code	Description	Content-Type	Content
204	Successfully added iocs to report	application/json	View example response below
403	Forbidden
500	Internal Server Error

Example

Request

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

Request Body

{
  "iocs": [
    {
      "id": "1wscvoxlghzd",
      "match_type": "equality",
      "values": [
          "6c89c8c657be4c21ae5ef088a14f2ac7"
      ],
      "field": "process_hash",
      "link": null
    }
  ]
}

Response

204 No Content

Delete IOC

Remove report iocs with report_id and ioc_ids. ioc_ids can be a single id or comma seperated list. The report must be owned by the org_key

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Response

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

Example

Request

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

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

GET https://defense.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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`UPDATE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:update`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

PUT https://defense.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 occurred while the IOC was ignored.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.watchlists`	`DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Custom.Detections:org.Watchlists:delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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
500	Internal Server Error

Example

Request

DELETE https://defense.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

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": IOC,
 "iocs_v2": [IOCv2],
 "visibility": str
}

IOC

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

IOCv2s

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.
Note: The leading & trailing `/` characters are not used by Watchlists regex IOCs, whereas Search APIs require those characters to know when to interpret a query as regex notation.

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

Give Feedback

New survey coming soon!

Last modified on December 18, 2023

Carbon Black Cloud

Page Contents

Watchlist API for Enterprise EDR

Introduction

Requirements

Authentication

Watchlist

Create New Watchlist

Get All Watchlists

Get Watchlist

Get Watchlist Telemetry

Update Watchlist

Delete Watchlist

Delete All Watchlists

Get Watchlist Alert Status

Enable Watchlist Alerts

Disable Watchlist Alerts

Disable All Watchlist Alerts

Get Watchlist Tag Status

Enable Watchlist Tags

Disable Watchlist Tags

Disable All Watchlist Tags

Reports

Create New Report

Update a Report

Get Report

Remove Report

Get Ignore Status for Provided Report IDs

Get Report Ignore Status

Ignore Report

Bulk Get Report Ignore Status

Bulk Ignore Reports and IOCs

Re-activate Report

Get Custom Report Severities

Get Custom Severity for Report

Set Custom Report Severity

Remove Custom Report Severity

IOCs

Add IOC

Delete IOC

Get IOC Ignore Status

Ignore IOC

Re-activate IOC

Definitions

Report

IOC

IOCv2

QueryIOC

ReportSeverity

ClassifierWatchlist

ReportWatchlist

Watchlist

ClassifierKeyValue

WatchlistV2

ReportIOCIgnore

ReportIOCIgnoreList

WatchlistTelemetry

WatchlistTelemetryList

Examples

IOCv2s

Equality IOCv2

Regular Expression IOCv2

Query IOCv2

Give Feedback