Feed Search 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: v1
Introduction
The Feed Search API enables you to search across all reports available to your organization, both those published by Carbon Black Cloud in threat intelligence feeds as well as all custom reports generated within your organization.
This allows you to create custom watchlists that can hit and/or alert on a targeted set of events across your organization’s fleet.
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.
- Search Feeds: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/search
- Suggest Fields: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/suggest
Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
- org.feeds, allow permission to
READ
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.
- Search Feeds: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/search
- Suggest Fields: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/suggest
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
READ
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.
Health Check
This endpoint does a simple health check.
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/feedsearch/v1/health_check
Responses
Code | Description | Content Type | Content |
---|---|---|---|
200 | OK | *:* |
None |
Feed Search
Search across all feed and watchlist reports.
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/feedsearch/v1/orgs/{org_key}/search
Query Parameters
Parameter | Required | Default | Description |
---|---|---|---|
query | Yes | N/A | Query to run (syntax) |
start | No | 0 | Offset of first record |
rows | No | 10 | Number of records to retrieve |
sort | No | N/A | Comma separated list of sort fields with optional asc/desc after each |
facet.field | No | N/A | Comma separated list of fields to compute facets for |
iocs | No | true | A toggle to enable or disable the inclusion of the iocs within the returned report |
Example Response
This is an example response for a successful /search
request.
{
"facets": {},
"hits": {
"total" : 1,
"hits": [
{
"_id": "someid",
"_source": {
"access": "public",
"description": "Report description.",
"feed": {
"feed_category": "Partner",
"feed_id": "somefeedid",
"feed_name": "Carbon Black Feed",
"feed_provider_url": "https://somefeedlink.com",
"feed_summary": "This is a feed summary."
},
"iocs": [
{
"field": "netconn_domain",
"id": "someiocid",
"match_type": "equality",
"link": "https://someioclink.com",
"values": [
"something.com",
"something.else.com"
]
}
],
"link": "https://somereportlink.com",
"severity": 4,
"telemetry": {
"global_hit_rate_1d": 0.1,
"global_hit_rate_1w": 0.2
},
"timestamp": 1541217832,
"title": "This is the report title."
}
}
]
}
}
Feed Field Suggest
Search field names with partial substrings to find most prevalent field names.
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/feedsearch/v1/orgs/{org_key}/suggest?suggest.query=test
Query Parameters
Parameter | Required | Default | Description |
---|---|---|---|
suggest.query | Yes | N/A | A substring of any field name |
suggest.count | No | N/A | The max number of suggestions to return |
Example Response
This is an example response for a successful /suggest
request.
{
"suggest": [
{ "term": "severity", "weight": 97 },
{ "term": "feed_provider_url", "weight": 89 }
]
}