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

Healthcheck

Successful response indicates service reachability.

RBAC Permissions Required

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

Request

GET <psc-hostname>/threathunter/feedmgr/healthcheck

Responses

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)
threathunter.feeds READ

Request

GET <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds

Responses

Code Description Content-Type Content
200 Array of Feeds application/json {“results”: [Feed]}

Get Specific Feed

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

RBAC Permissions Required

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

Request

GET <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}

Responses

Code Description Content-Type Content
200 Feed application/json Feed

Create a New Private Feed

Create new private feed. Unique feed ID will be assigned by the service. All IOCs will be converted to IOC_V2. 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)
threathunter.feeds CREATE

Request

POST <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds
Content-Type Content
application/json Feed

Responses

Code Description Content-Type Content
200 Feed created application/json FeedInfo
400 Invalid Feed Request *:* None

Create a New Public Feed

Create public feed. Unique feed ID will be assigned by the service. All IOCs will be converted to IOC_V2. This feed will be owned by the caller. The feed will be available to all organizations.

RBAC Permissions Required

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

Request

POST <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/public
Content-Type Content
application/json Feed

Responses

Code Description Content-Type Content
200 Feed created application/json FeedInfo
400 Invalid Feed Request *:* None

Delete Feed

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

RBAC Permissions Required

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

Request

DELETE <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}

Responses

Code Description Content-Type Content
204 Feed Deleted *:* None
400 Unknown feed *:* None

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)
threathunter.feeds READ

Request

GET <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/feedinfo

Responses

Code Description Content-Type Content
200 Feed Info application/json FeedInfo

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)
threathunter.feeds UPDATE

Request

PUT <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/feedinfo
Content-Type Content
application/json FeedInfo

Responses

Code Description Content-Type Content
200 Feed Info Updated application/json FeedInfo
400 Invalid Feed Request *:* None

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)
threathunter.feeds READ

Request

GET <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports

Responses

Code Description Content-Type Content
200 Reports array application/json {“results”: [Report]}

Replace Reports

Replace reports for feed ID. All IOCs will be converted to IOC_V2. 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)
threathunter.feeds CREATE

Request

POST <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports
Content-Type Content
application/json {“reports”: [Report]}

Responses

Code Description Content-Type Content
200 Success application/json {“success”: boolean*}

Get Report

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

RBAC Permissions Required

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

Request

GET <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}

Responses

Code Description Content-Type Content
200 Report application/json [Report]

Update Report

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

RBAC Permissions Required

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

Request

PUT <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}
Content-Type Content
application/json [Report]

Responses

Code Description Content-Type Content
200 Report application/json Report

Delete report

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

RBAC Permissions Required

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

Request

DELETE <psc-hostname>/threathunter/feedmgr/v2/orgs/{org_key}/feeds/{feed_id}/reports/{report_id}

Responses

Code Description Content-Type Content
204 report deleted *:* None

Convert Legacy Query

Convert CB Reponse query to ThreatHunter query. This will adjust field names and other syntax to match ThreatHunter Solr requirements.

RBAC Permissions Required

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

Request

POST <psc-hostname>/threathunter/feedmgr/v2/query/translate

Legacy query
content-type content
application/json {"query": str*}
Responses

Code Description Content-Type Content
200 Translated query application/json {“query”: str*}
400 Unable to convert query due to incompatible fields *:* None

Definitions

NOTE: fields with ‘*’ are required

FeedInfo

{
 "name": str*,
 "owner": str*,
 "provider_url": str*,
 "summary": str*,
 "category": str*,
 "source_label": str,
 "access": str,
 "id": str
}

QueryIOC

{
 "index_type": str,
 "search_query": str*
}

IOCs

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

IOC_V2

{
 "id": str*,
 "match_type": str*,
 "values": [str]*,
 "field": str,
 "link": str
}

Report

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

Feed

{
 "feedinfo": FeedInfo*,
 "reports": [Report]*
}

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 IOC_V2

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

Regular Expression IOC_V2

This regular expression looks for double file extensions.

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

Query IOC_V2

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