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

Health Check

This endpoint does a simple health check.

RBAC Permissions Required

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

Request

GET <psc-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

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

Request

GET <psc-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

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

Request

GET <psc-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 April 21, 2021