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?

  1. Watchlists generate Hits and Alerts in your organization; Feeds do not
  2. Watchlists are specific to one organization; Feeds can be published to one, some or all organizations
  3. 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.

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.


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.


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.

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.

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.

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.

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

Update the list of organizations that can access a 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 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 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"
    ]
}

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.

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.

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 February 7, 2023