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.

RBAC 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.

RBAC 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.

RBAC 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 }
    ]
}
Last modified on September 6, 2022