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

Carbon Black Cloud

API Reference

Page Contents

Feed Manager API for Enterprise EDR

Version: v2

Healthcheck

Get All Feeds

Get Specific Feed

Create a New Private Feed

Create a New Public Feed

Delete Feed

Get Feed Info

Update Feed Info

Get Reports

Replace Reports

Get Report

Update Report

Delete report

Convert Legacy Query

Definitions

FeedInfo

QueryIOC

IOCs

IOC_V2

Report

Feed

Examples

IOCs

Equality IOC_V2

Regular Expression IOC_V2

Query IOC_V2