Feed Manager 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: v2

Introduction

The Feed Manager API enables you to manage third-party threat intelligence Watchlists (here called “Feeds”), including the ability to convert Carbon Black EDR queries for use in Carbon Black Cloud Enterprise EDR.

What is a Feed?

On the Carbon Black Cloud, a Feed is a collection of actionable threat intelligence, organized into Reports which are collections of one or more Indicators of Compromise (IOCs).

Feeds can be published to all organizations in an environment (public) or to a selection of managed organizations in an environment (reserved). It is also possible to publish a Feed to only one organization (private), but in practice this is unnecessary overhead for most organizations:

Public Feeds can only be created or edited by VMware Carbon Black; more information about the current public Feeds can be found on the Carbon Black User Community here.
Reserved Feeds can be created in another organization only by MSSPs.
Private Feeds can be created in anyone with sufficient privileges in the target organization.

In the Carbon Black Cloud console, Feeds are those Watchlists whose Type is “F” (Feed Subscription).

What is a Watchlist?

On the Carbon Black Cloud, a Watchlist is a specific set of subscribed Reports and their IOCs that are evaluated against incoming sensor data to enrich your search results with “hits” where the Watchlists found a match in your endpoint fleet’s events data.

Watchlists can be subscribed from a Feed, or can be created directly from a selection of existing Reports. Once created, a Watchlist can be edited in one of three ways:

New Reports can be added
Existing Reports in that Watchlist can be disabled or enabled
The Watchlist as a whole can be unsubscribed or disabled

What are the functional differences between Feeds and Watchlists?

Watchlists generate Hits and Alerts in your organization; Feeds do not
Watchlists are specific to one organization; Feeds can be published to one, some or all organizations
Watchlists can be unsubscribed; Feeds cannot be/do not need to be unsubscribed

Feeds are in effect “potentially-subscribable Watchlists”. A Feed has no effect on your organization until you have subscribed to it - at which point a related Watchlist is enabled in the organization. Once subscribed (and until it’s disabled or unsubscribed), a Watchlist will generate Hits (and Alerts if you have enabled them) for any matches against any of the IOCs in any of that Watchlist’s enabled Reports.

Want to make this easier? Check out the support for feeds, 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.

Feeds: {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds
Convert Legacy Query: {cbc-hostname}/threathunter/feedmgr/v2/query/translate

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

org.feeds, allow permission to CREATE, READ, UPDATE AND 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.

Feeds: {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds
Convert Legacy Query: {cbc-hostname}/threathunter/feedmgr/v2/query/translate

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.Feeds, allow permission to CREATE, READ, UPDATE AND 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.

Healthcheck

Successful response indicates service reachability.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`No permissions required`		Majority of environments
VMware Cloud Services Platform	`No permissions required`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

Request

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

Response

Code	Description	Content-Type	Content
204	service is available	`.`	None

Get All Feeds

Retrieve all feeds owned by the caller. Provide include_public=true parameter to also include public community feeds.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds

Query Schema

Field	Definition	Data Type	Values
`include_public`	Whether to include public community feeds in the response	Boolean	`true`, `false`

Response

Code	Description	Content-Type	Content
200	Array of Feeds	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/feedmgr/v2/orgs/ABCD1234/feeds?include_public=true

Response

{
    "results": [
        {
            "name": "My Feed",
            "owner": "ABCD1234",
            "provider_url": "https://example.com",
            "summary": "Example Feed",
            "category": "None",
            "source_label": null,
            "access": "private",
            "id": "ABCDEFGHIJKLMNOPQRSTUVWX",
            "alertable": true
        },
        {
            "name": "Carbon Black AlienVault",
            "owner": "AlienVault",
            "provider_url": "https://www.alienvault.com/",
            "summary": "This watchlist contains intelligence provided by AlienVault's Open Threat Exchange (OTX). It leverages insights into attacks across the community and will show you hostile scanning hosts, malware hosts, and other targeting and security event information.",
            "category": "Partner",
            "source_label": "AlienVault",
            "access": "public",
            "id": "wuDcrLFVRUOBIn1g3er9tQ",
            "alertable": true
        }
    ]
}

Get Specific Feed

Retrieve feed with feed_id. This feed must be owned by the caller.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}

Response

Code	Description	Content-Type	Content
200	Feed	application/json	View example request below
403	Forbidden	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX

Response

{
    "feedinfo": {
        "name": "My Feed",
        "owner": "ABCD1234",
        "provider_url": "https://example.com",
        "summary": "Example Feed",
        "category": "None",
        "source_label": null,
        "access": "private",
        "id": "ABCDEFGHIJKLMNOPQRSTUVWX"
    },
    "reports": [
        {
            "id": "1",
            "timestamp": 1571083459,
            "title": "yara",
            "description": "microsoft:microsoft",
            "severity": 5,
            "link": null,
            "tags": null,
            "iocs": null,
            "iocs_v2": [
                {
                    "id": "1",
                    "match_type": "equality",
                    "values": [
                        "TQBpAGMAcgBvAHMAbwBmAHQA"
                    ],
                    "field": "$microsoft",
                    "link": null
                }
            ],
            "visibility": null
        }
    ]
}

Create a New Private Feed

Create new private feed. Unique feed ID will be assigned by the service. All IOCs will be converted to IOCv2. This feed will be owned by the caller. The feed will be available to only the org that created it.

API Permissions Required

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

Request

POST {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds

Request Body

{
 "feedinfo": {
    "name": "<string>",
    "provider_url": "<string>",
    "summary": "<string>",
    "category": "<string>",
    "source_label": "<string>",
    "alertable": true
   },
 "reports": [{
    "id": "<string>",
    "timestamp": "<integer>",
    "title": "<string>",
    "description": "<string>",
    "severity": "<integer>",
    "link": "<string>",
    "tags": ["<string>"],
    "iocs": "<IOCv1>",
    "iocs_v2": ["<IOCv2>"],
    "visibility": "<string>"
 }]
}

Body Schema

Field	Definition	Data Type	Values
`name` REQUIRED	Name for the Feed	String	N/A
`provider_url` REQUIRED	URL for where the Feed information will come from	String	N/A
`summary` REQUIRED	Summary for the Feed	String	N/A
`category` REQUIRED	Category for the Feed	String	N/A
`source_label`	Label for where the Feed information will come from	String	N/A
`alertable`	Optional indicator for noisy feeds to prevent alerting when a watchlist is subscribed.	Boolean	Default: `true`
`id` REQUIRED	Report ID	String	N/A
`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`	List of report tags	[String]	N/A
`iocs`	IOCs to associate with the report. IOCs will be converted to IOCv2 format.	IOCv1	IOCv1
`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 the Feed	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/feedmgr/v2/orgs/ABCD1234/feeds

Request Body

{
    "feedinfo": {
        "name": "My Feed",
        "provider_url": "https://example.com",
        "summary": "Summary for my feed",
        "category": "external_threat_intel",
        "source_label": "Label for threat intel source",
        "alertable": true
    },
    "reports": [
        {
            "id": "Report_ID_1",
            "timestamp": 1571083459,
            "title": "YARA",
            "description": "microsoft:microsoft",
            "severity": 1,
            "link": "https://microsoft.com/en-us/",
            "tags": ["safe", "website"],
            "iocs_v2": [
                {
                    "id": "IOC_ID_1",
                    "match_type": "equality",
                    "values": [
                        "SHA256HashOfAProcess"
                    ],
                    "field": "process_sha256",
                    "link": null
                }
            ],
            "visibility": "visible"
        }
    ]
}

Response

{
    "name": "My Feed",
    "owner": "ABCD1234",
    "provider_url": "https://example.com",
    "summary": "Summary for my feed",
    "category": "external_threat_intel",
    "source_label": "Label for threat intel source",
    "access": "private",
    "id": "ABCDEFGHIJKLMNOPQRSTUVWX",
    "alertable": true
}

Create a New Reserved Feed

Create new reserved feed. Unique feed ID will be assigned by the service. This feed will be owned by org_key and available to org_key’s delegates at the time of creation.

API Permissions Required

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

Request

POST {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/reserved

Request Body

{
 "feedinfo": {
    "name": "<string>",
    "provider_url": "<string>",
    "summary": "<string>",
    "category": "<string>",
    "source_label": "<string>",
    "alertable": true
   },
 "reports": [{
    "id": "<string>",
    "timestamp": "<integer>",
    "title": "<string>",
    "description": "<string>",
    "severity": "<integer>",
    "link": "<string>",
    "tags": ["<string>"],
    "iocs": "<IOCv1>",
    "iocs_v2": ["<IOCv2>"],
    "visibility": "<string>"
 }],
 "delegates_auth_token": "ABCDEFGHIJKLMNOPQRSTU/123456789"
}

Body Schema

Field	Definition	Data Type	Values
`name` REQUIRED	Name for the Feed	String	N/A
`provider_url` REQUIRED	URL for where the Feed information will come from	String	N/A
`summary` REQUIRED	Summary for the Feed	String	N/A
`category` REQUIRED	Category for the Feed	String	N/A
`source_label`	Label for where the Feed information will come from	String	N/A
`alertable`	Optional indicator for noisy feeds to prevent alerting when a watchlist is subscribed.	Boolean	Default: `true`
`id` REQUIRED	Report ID	String	N/A
`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`	List of report tags	[String]	N/A
`iocs`	IOCs to associate with the report. IOCs will be converted to IOCv2 format.	IOCv1	IOCv1
`iocs_v2`	IOCv2’s to associate with the report. Preferred over IOCs.	Array	[IOCv2]
`visibility`	Report visibility	String	N/A
`delegates_auth_token`	X-Auth-Token to verify which delegates the caller has access to. Overrides the X-Auth-Token sent with request headers.	String	N/A

Response

Code	Description	Content-Type	Content
200	Successfully created the Feed	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/feedmgr/v2/orgs/ABCD1234/feeds/reserved

Request Body

{
    "feedinfo": {
        "name": "My Reserved Feed",
        "provider_url": "https://example.com",
        "summary": "Summary for my feed",
        "category": "external_threat_intel",
        "source_label": "Label for threat intel source",
        "alertable": true
    },
    "reports": [
        {
            "id": "Report_ID_1",
            "timestamp": 1571083459,
            "title": "YARA",
            "description": "microsoft:microsoft",
            "severity": 1,
            "link": "https://microsoft.com/en-us/",
            "tags": ["safe", "website"],
            "iocs_v2": [
                {
                    "id": "IOC_ID_1",
                    "match_type": "equality",
                    "values": [
                        "SHA256HashOfAProcess"
                    ],
                    "field": "process_sha256",
                    "link": null
                }
            ],
            "visibility": "visible"
        }
    ]
}

Response

{
    "name": "My Reserved Feed",
    "owner": "ABCD1234",
    "provider_url": "https://example.com",
    "summary": "Summary for my feed",
    "category": "external_threat_intel",
    "source_label": "Label for threat intel source",
    "access": "private",
    "id": "ABCDEFGHIJKLMNOPQRSTUVWX",
    "alertable": true
}

Delete Feed

Delete feed with feed_id. This feed must be owned by the caller.

API Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}

Response

Code	Description	Content-Type	Content
204	Successfully deleted Feed	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/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX

Response

204 No Content

Get Feed Info

Retrieve feed info metadata for feed with feed_id. This feed must be owned by the caller.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/feedinfo

Response

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

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/feedinfo

Response

{
    "name": "My Feed",
    "owner": "ABCD1234",
    "provider_url": "https://example.com",
    "summary": "Example Feed",
    "category": "None",
    "source_label": null,
    "access": "private",
    "id": "ABCDEFGHIJKLMNOPQRSTUVWX",
    "alertable": true
}

Update Feed Info

Update feed info metadata for feed with feed_id. This feed must be owned by the caller.

API Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/feedinfo

Request Body

{
    "name": "<string>",
    "provider_url": "<string>",
    "summary": "<string>",
    "category": "<string>",
    "source_label": "<string>",
    "access": "<string>",
    "alertable": true
}

Body Schema

Field	Definition	Data Type	Values
`name`	Name for the Feed	String	N/A
`provider_url`	URL for where the Feed information will come from	String	N/A
`summary`	Summary for the Feed	String	N/A
`category`	Category for the Feed	String	N/A
`source_label`	Label for where the Feed information will come from	String	N/A
`access` REQUIRED	Access level for the Feed	String	`private`
`alertable`	Optional indicator for noisy feeds to prevent alerting when a watchlist is subscribed.	Boolean	Default: `true`

Response

Code	Description	Content-Type	Content
200	Successfully updated the Feed Info	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/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/feedinfo

Request Body

{
    "name": "New Name",
    "provider_url": "https://example.com",
    "summary": "New Summary",
    "category": "New Category",
    "source_label": "New Source",
    "access": "private",
    "alertable": true
}

Response

{
    "name": "New Name",
    "owner": "ABCD1234",
    "provider_url": "https://example.com",
    "summary": "New Summary",
    "category": "New Category",
    "source_label": "New Source",
    "access": "private",
    "id": "ABCDEFGHIJKLMNOPQRSTUVWX",
    "alertable": true
}

Get Reserved Feed Delegates

Retrieve the delegated orgs for a reserved feed. These orgs do not own the feed but have read access to it’s contents. Feed must be owned by the caller.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/reserved/{feed_id}/delegates

Response

Code	Description	Content-Type	Content
200	Successfully retrieved delegates	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/feedmgr/v2/orgs/ABCD1234/feeds/reserved/ABCDEFGHIJKLMNOPQRSTUVWX/delegates

Response

{
    "delegates": [
        "ABCD1234"
    ]
}

Update Reserved Feed Delegates

Append a list of new child organizations that should be given access to the reserved feed.

API Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/feedmgr/v2/orgs/(org_key)/feeds/reserved/(feed_id)/delegates

Request Body

{
  "delegates": [
    "<string>",
    "<string>"
  ],
  "delegates_auth_token": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`delegates` REQUIRED	List of delegates to assign to the feed.	[String]	N/A
`delegates_auth_token`	Overrides the X-Auth-Token sent with request headers to verify which delegates the caller has access to.	String	N/A

Response

Code	Description	Content-Type	Content
200	Successful Request	application/json	View example response below
400	Invalid request	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

Request

PUT {cbc-hostname}/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/reserved/V0nmzJsjSPaZq5XHWEkDQ/delegates

Request Body

{
    "delegates": [
        "ABCD1234",
        "EFGH5678"
    ],
    "delegates_auth_token": "ABCDEFGHIJKLMNOPQRSTUVWX/12345678"
}

Response

{
    "delegates": [
        "ABCD1234",
        "EFGH5678",
        "HIJKPR67"
    ]
}

Get Reports

Retrieve all the reports for feed with feed_id. Feed must be owned by the caller.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports

Response

Code	Description	Content-Type	Content
200	Successfully retrieved reports	application/json	View example response below
400	Invalid request	N/A	N/A
500	Internal Server Error	N/A	N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/reports

Response

{
    "results": [
        {
            "id": "customID",
            "timestamp": 1571083459,
            "title": "yara",
            "description": "microsoft:microsoft",
            "severity": 5,
            "link": "mycustomlink",
            "tags": [
                "mycustomtag"
            ],
            "iocs": null,
            "iocs_v2": [
                {
                    "id": "myCustomID",
                    "match_type": "equality",
                    "values": [
                        "SHA256HashOfAProcess"
                    ],
                    "field": "process_sha256",
                    "link": null
                }
            ],
            "visibility": "visible"
        }
    ]
}

Replace Reports

Replace reports for feed ID. All IOCs will be converted to IOCv2. Any existing reports not in the payload will be deleted. Feed must be owned by the caller.

API Permissions Required

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

Request

POST {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports

Request Body

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

Body Schema

Field	Definition	Data Type	Values
`id` REQUIRED	Report ID	String	N/A
`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`	List of report tags	[String]	N/A
`iocs`	IOCs to associate with the report. IOCs will be converted to IOCv2 format.	IOCv1	IOCv1
`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 replaced reports	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/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/reports

Request Body

{
  "reports": [{
     "id": "Report_ID_1",
     "timestamp": 1604950037,
     "title": "Report Title",
     "description": "Report Description",
     "severity": 2,
     "link": "https://google.com",
     "tags": ["false_positive"],
     "iocs": null,
     "iocs_v2": [
         {
             "id": "IOC_ID_1",
             "match_type": "equality",
             "values": [
                 "SHA256HashOfAProcess"
             ],
             "field": "process_sha256",
             "link": null
         }
     ],
     "visibility": "visible"
  }]
}

Response

{
    "success": true
}

Get Report

Return report with report_id. Feed must be owned by the caller.

API Permissions Required

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

Request

GET {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}

Response

Code	Description	Content-Type	Content
200	Successfully retrieved 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

GET https://defense-eap01.conferdeploy.net/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/reports/Report_ID_1

Response

{
    "report": {
        "id": "Report_ID_1",
        "timestamp": 1604950037,
        "title": "Report Title",
        "description": "Report Description",
        "severity": 2,
        "link": "https://google.com",
        "tags": [
            "false_positive"
        ],
        "iocs": null,
        "iocs_v2": [
            {
                "id": "IOC_ID_1",
                "match_type": "equality",
                "values": [
                    "SHA256HashOfAProcess"
                ],
                "field": "process_sha256",
                "link": null
            }
        ],
        "visibility": "visible"
    }
}

Update Report

Update report with report_id. All IOCs will be converted to IOCv2. Currently, there are three types for IOCv2: query, equality, and regex. Feed must be owned by the caller.

API Permissions Required

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

Request

PUT {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}

Request Body

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

Body Schema

Field	Definition	Data Type	Values
`id` REQUIRED	Report ID	String	N/A
`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	Must be the current UNIX timestamp
`severity` REQUIRED	Report severity	Integer	Between 1 and 10, inclusive
`link`	A URL to associate with the report	String	N/A
`tags`	List of report tags	[String]	N/A
`iocs`	IOCs to associate with the report. IOCs will be converted to IOCv2 format.	IOCv1	IOCv1
`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 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

PUT https://defense-eap01.conferdeploy.net/threathunter/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/reports/Report_ID_1

Request Body

{
   "id": "Report_ID_1",
   "timestamp": 1604950037,
   "title": "New Report Title",
   "description": "Report Description",
   "severity": 2,
   "link": "https://google.com",
   "tags": ["false_positive"],
   "iocs": null,
   "iocs_v2": [
       {
           "id": "New_IOC_ID_1",
           "match_type": "equality",
           "values": [
               "SHA256HashOfAProcess"
           ],
           "field": "process_sha256",
           "link": null
       }
   ],
   "visibility": "visible"
}

Response

{
    "id": "Report_ID_1",
    "timestamp": 1604950476,
    "title": "New Report Title",
    "description": "Report Description",
    "severity": 2,
    "link": "https://google.com",
    "tags": [
        "false_positive"
    ],
    "iocs": null,
    "iocs_v2": [
        {
            "id": "New_IOC_ID_1",
            "match_type": "equality",
            "values": [
                "SHA256HashOfAProcess"
            ],
            "field": "process_sha256",
            "link": null
        }
    ],
    "visibility": "visible"
}

Delete report

Delete report with report_id. Feed must be owned by the caller.

API Permissions Required

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

Request

DELETE {cbc-hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}

Response

Code	Description	Content-Type	Content
204	Successfully deleted 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/feedmgr/v2/orgs/ABCD1234/feeds/ABCDEFGHIJKLMNOPQRSTUVWX/reports/Report_ID_1

Response

204 No Content

Convert Legacy Query

Convert EDR query to Enterprise EDR query. This will adjust field names and other syntax to match Enterprise EDR Solr requirements.

API Permissions Required

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

Request

POST {cbc-hostname}/threathunter/feedmgr/v2/query/translate

Request Body

{
  "query": "<string>"
}

Body Schema

Field	Definition	Data Type	Values
`query`	EDR query to convert to Enterprise EDR syntax	String	N/A

Response

Code	Description	Content-Type	Content
200	Successfully converted query	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/feedmgr/v2/query/translate

Request Body

{
    "query": "path:\"microsoft office\\office15\\powerpnt.exe\""
}

Response

{
    "query": "(process_name:\"microsoft\\ office\\\\office15\\\\powerpnt.exe\") -enriched:true"
}

Fields

Note: Fields with '*' are required.

FeedInfo

Field	Definition	Data Type	Values
`name` REQUIRED	Name for the Feed	String	N/A
`provider_url` REQUIRED	URL for where the Feed information will come from	String	N/A
`summary` REQUIRED	Summary for the Feed	String	N/A
`category` REQUIRED	Category for the Feed	String	N/A
`source_label`	Label for where the Feed information will come from	String	N/A
`owner`	What organization owns the Feed	String	N/A
`access`	Type of access to the Feed. Only `private` Feeds can be created. Carbon Black provides `public` Feeds.	String	`private`, `public`
`id`	ID for the Feed	String	N/A
`alertable`	Optional indicator for noisy feeds to prevent alerting when a watchlist is subscribed.	Boolean	Default: `true`

QueryIOC

Field	Definition	Data Type	Values
`index_type`	What type of data to search for	String	`events`, `processes`
`search_query` REQUIRED	The Enterprise EDR search query	String	N/A

IOCv1

This IOC structure is being deprecated.

You can continue to leverage the documentation below until the IOCs v1 structure is deprecated. The most up to date IOC structure is available directly below in IOCv2, or click here.

Field	Definition	Data Type	Values
`md5`	List of MD5 hashes	[String]	N/A
`ipv4`	List of IPv4 addresses	[String]	N/A
`ipv6`	List of IPv6 addresses	[String]	N/A
`dns`	List of DNS addresses	[String]	N/A
`query`	List of queries	[QueryIOC]	N/A

IOCv2

Field	Definition	Data Type	Values
`id` REQUIRED	IOC ID	String	N/A
`match_type` REQUIRED	IOC match type	String	`equality`, `regex`, `query`
`values` REQUIRED	List of values to match on	[String]	N/A
`field`	Search field to match on	String	N/A
`link`	Link to where the information came from	String	N/A

Report

Field	Definition	Data Type	Values
`id` REQUIRED	Report ID	String	N/A
`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`	List of report tags	[String]	N/A
`iocs`	IOCs to associate with the report. IOCs will be converted to IOCv2 format.	IOCv1	IOCv1
`iocs_v2`	IOCv2’s to associate with the report. Preferred over IOCs.	Array	[IOCv2]
`visibility`	Report visibility	String	N/A

Feed

Field	Definition	Data Type	Values
`feedinfo` REQUIRED	Information about the Feed	FeedInfo	N/A
`reports` REQUIRED	List of Reports in the Feed	[Report]	N/A

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 record. 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.

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 December 12, 2023

Carbon Black Cloud

Page Contents

Feed Manager API for Enterprise EDR

Version: v2

Introduction

What is a Feed?

What is a Watchlist?

What are the functional differences between Feeds and Watchlists?

Requirements

Authentication

Healthcheck

Get All Feeds

Get Specific Feed

Create a New Private Feed

Create a New Reserved Feed

Delete Feed

Get Feed Info

Update Feed Info

Get Reserved Feed Delegates

Update Reserved Feed Delegates

Get Reports

Replace Reports

Get Report

Update Report

Delete report

Convert Legacy Query

Fields

FeedInfo

QueryIOC

IOCv1

IOCv2

Report

Feed

Examples

IOCs

Equality IOCv2

Regular Expression IOCv2

Query IOCv2