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.

Requirements

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

Healthcheck

Successful response indicates service reachability.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/threathunter/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.

RBAC Permissions Required

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

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

Get Specific Feed

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

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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

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.

RBAC Permissions Required

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

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

Delete Feed

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

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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

Update Feed Info

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

RBAC Permissions Required

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

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

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

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

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

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.feeds CREATE / UPDATE

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.

RBAC Permissions Required

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

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.

RBAC Permissions Required

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

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

Schemas

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

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 August 16, 2021