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
  • Search Feeds: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/reports/_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
  • org.watchlists, 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
  • Search Feeds: {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/reports/_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.Custom.Detections:org.Watchlists, 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.

API Calls

Search across all feed and watchlist reports.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.feeds, org.watchlists READ Majority of environments
VMware Cloud Services Platform _API.Custom.Detections:org.Feeds:read, _API.Custom.Detections:org.Watchlists: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

Field Definition Data Type Values
query REQUIRED Query to run (syntax).

Note: Ensure you urlencode the query as lucene query strings may contain characters such as : and () which must be encoded.		 String Supported fields: id, title, severity, feed_id, feed_name, description, feed_provider_url, feed_summary, source_label
facet.field Comma separated list of fields to compute facets String Supported Fields: severity, tags, feed_id, feed_category, source_label
iocs A toggle to enable or disable the inclusion of the iocs within the returned report Boolean Default: true
rows Number of records to retrieve Integer Default: 10
sort Comma separated list of sort fields with optional asc/desc after each String Example: severity desc

Supported fields: id, title, severity, feed_id, feed_name, description, feed_provider_url, feed_summary, source_label
start Offset of first record Integer Default: 0

Examples

Request 
GET https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/search?query=%28feed_name%3A%22Carbon%20Black%22%29%20AND%20id%3A4A3e4myPTc2gB2qZpyI2Nw-568480&facet.field=severity%2Cfeed_id&iocs=true&start=0&rows=20
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "took": 77,
    "timed_out": false,
    "hits": {
        "total": 1,
        "max_score": null,
        "hits": [
            {
                "_index": "report_index-2018.11.17-1",
                "_type": "_doc",
                "_id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                "_score": null,
                "_source": {
                    "severity": 10,
                    "access": "public",
                    "iocs": [
                        {
                            "field": null,
                            "values": [
                                "((process_name:wininit.exe -process_name:system32\/wininit.exe -process_name:windows\\\\winsxs\\\\*wininit.exe*)) -enriched:true"
                            ],
                            "link": null,
                            "match_type": "query",
                            "id": "568480-0"
                        }
                    ],
                    "link": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf",
                    "description": "",
                    "title": "SANS: Unusual wininit.exe path",
                    "tags": [
                        "sans",
                        "wininit",
                        "unusualpath",
                        "attackframework",
                        "attack",
                        "evasion",
                        "t1036",
                        "windows"
                    ],
                    "source_label": "Carbon Black",
                    "id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                    "timestamp": 1636643103,
                    "feed": {
                        "feed_category": "Partner",
                        "feed_summary": "Know Abnormal...Find Evil. It's often impossible to know malicious behavior before you see it, but we do know what common behaviors are normal or benign. Spotting the difference between normal and abnormal is often the difference between success and failure. Use this watchlist as a reference to quickly identify behavior in Windows that falls outside the scope of 'normal', so you can cut through the noise and instantly investigate and disrupt potential threats. This watchlist is a great starting point for users looking to hone their threat hunting skills.",
                        "feed_id": "4A3e4myPTc2gB2qZpyI2Nw",
                        "feed_name": "Carbon Black SANS",
                        "feed_provider_url": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf"
                    },
                    "telemetry": {
                        "global_hit_rate_1d": 0,
                        "global_hit_rate_1w": 0
                    }
                },
                "sort": [
                    "4A3e4myPTc2gB2qZpyI2Nw-568480"
                ]
            }
        ]
    },
    "facets": {
        "severity": {
            "10": 1
        },
        "feed_id": {
            "4A3e4myPTc2gB2qZpyI2Nw": 1
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/search?query=%28feed_name%3A%22Carbon%20Black%22%29%20AND%20id%3A4A3e4myPTc2gB2qZpyI2Nw-568480&facet.field=severity%2Cfeed_id&iocs=true&start=0&rows=20 \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
    "took": 77,
    "timed_out": false,
    "hits": {
        "total": 1,
        "max_score": null,
        "hits": [
            {
                "_index": "report_index-2018.11.17-1",
                "_type": "_doc",
                "_id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                "_score": null,
                "_source": {
                    "severity": 10,
                    "access": "public",
                    "iocs": [
                        {
                            "field": null,
                            "values": [
                                "((process_name:wininit.exe -process_name:system32\/wininit.exe -process_name:windows\\\\winsxs\\\\*wininit.exe*)) -enriched:true"
                            ],
                            "link": null,
                            "match_type": "query",
                            "id": "568480-0"
                        }
                    ],
                    "link": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf",
                    "description": "",
                    "title": "SANS: Unusual wininit.exe path",
                    "tags": [
                        "sans",
                        "wininit",
                        "unusualpath",
                        "attackframework",
                        "attack",
                        "evasion",
                        "t1036",
                        "windows"
                    ],
                    "source_label": "Carbon Black",
                    "id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                    "timestamp": 1636643103,
                    "feed": {
                        "feed_category": "Partner",
                        "feed_summary": "Know Abnormal...Find Evil. It's often impossible to know malicious behavior before you see it, but we do know what common behaviors are normal or benign. Spotting the difference between normal and abnormal is often the difference between success and failure. Use this watchlist as a reference to quickly identify behavior in Windows that falls outside the scope of 'normal', so you can cut through the noise and instantly investigate and disrupt potential threats. This watchlist is a great starting point for users looking to hone their threat hunting skills.",
                        "feed_id": "4A3e4myPTc2gB2qZpyI2Nw",
                        "feed_name": "Carbon Black SANS",
                        "feed_provider_url": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf"
                    },
                    "telemetry": {
                        "global_hit_rate_1d": 0,
                        "global_hit_rate_1w": 0
                    }
                },
                "sort": [
                    "4A3e4myPTc2gB2qZpyI2Nw-568480"
                ]
            }
        ]
    },
    "facets": {
        "severity": {
            "10": 1
        },
        "feed_id": {
            "4A3e4myPTc2gB2qZpyI2Nw": 1
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Feed Search - POST

Search across all feed and watchlist reports.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.feeds, org.watchlists READ Majority of environments
VMware Cloud Services Platform _API.Custom.Detections:org.Feeds:read, _API.Custom.Detections:org.Watchlists:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/threathunter/feedsearch/v1/orgs/{org_key}/reports/_search

Request Body - application/json 

{
  "query": "<string>",
  "facet.field": "<string>",
  "iocs": <boolean>,
  "rows": <integer>,
  "start": <integer>,
  "sort": "<string>"
}


Body Schema

Field Definition Data Type Values
query REQUIRED Query to run (syntax).

Note: Ensure you escape the query as lucene query strings may contain characters such as " which must be escaped for JSON requests.		 String Supported fields: id, title, severity, feed_id, feed_name, description, feed_provider_url, feed_summary, source_label
facet.field Comma separated list of fields to compute facets String Supported Fields: severity, tags, feed_id, feed_category, source_label
iocs A toggle to enable or disable the inclusion of the iocs within the returned report Boolean Default: true
rows Number of records to retrieve Integer Default: 10
sort Comma separated list of sort fields with optional asc/desc after each String Example: severity desc

Supported fields: id, title, severity, feed_id, feed_name, description, feed_provider_url, feed_summary, source_label
start Offset of first record Integer Default: 0

Examples

Request 
POST https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/reports/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query":"(feed_name:\"Carbon Black\") AND id:4A3e4myPTc2gB2qZpyI2Nw-568480",
    "facet.field":"severity,tags,feed_id,feed_category,source_label",
    "rows":2,
    "start":0,
    "iocs":true
}
Response Body 
{
    "took": 77,
    "timed_out": false,
    "hits": {
        "total": 1,
        "max_score": null,
        "hits": [
            {
                "_index": "report_index-2018.11.17-1",
                "_type": "_doc",
                "_id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                "_score": null,
                "_source": {
                    "severity": 10,
                    "access": "public",
                    "iocs": [
                        {
                            "field": null,
                            "values": [
                                "((process_name:wininit.exe -process_name:system32\/wininit.exe -process_name:windows\\\\winsxs\\\\*wininit.exe*)) -enriched:true"
                            ],
                            "link": null,
                            "match_type": "query",
                            "id": "568480-0"
                        }
                    ],
                    "link": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf",
                    "description": "",
                    "title": "SANS: Unusual wininit.exe path",
                    "tags": [
                        "sans",
                        "wininit",
                        "unusualpath",
                        "attackframework",
                        "attack",
                        "evasion",
                        "t1036",
                        "windows"
                    ],
                    "source_label": "Carbon Black",
                    "id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                    "timestamp": 1636643103,
                    "feed": {
                        "feed_category": "Partner",
                        "feed_summary": "Know Abnormal...Find Evil. It's often impossible to know malicious behavior before you see it, but we do know what common behaviors are normal or benign. Spotting the difference between normal and abnormal is often the difference between success and failure. Use this watchlist as a reference to quickly identify behavior in Windows that falls outside the scope of 'normal', so you can cut through the noise and instantly investigate and disrupt potential threats. This watchlist is a great starting point for users looking to hone their threat hunting skills.",
                        "feed_id": "4A3e4myPTc2gB2qZpyI2Nw",
                        "feed_name": "Carbon Black SANS",
                        "feed_provider_url": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf"
                    },
                    "telemetry": {
                        "global_hit_rate_1d": 0,
                        "global_hit_rate_1w": 0
                    }
                },
                "sort": [
                    "4A3e4myPTc2gB2qZpyI2Nw-568480"
                ]
            }
        ]
    },
    "facets": {
        "severity": {
            "10": 1
        },
        "feed_id": {
            "4A3e4myPTc2gB2qZpyI2Nw": 1
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/reports/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data '{
    "query":"(feed_name:\"Carbon Black\") AND id:4A3e4myPTc2gB2qZpyI2Nw-568480",
    "facet.field":"severity,tags,feed_id,feed_category,source_label",
    "rows":2,
    "start":0,
    "iocs":true,
    "sort": "severity desc"
}'
Response Body 
{
    "took": 77,
    "timed_out": false,
    "hits": {
        "total": 1,
        "max_score": null,
        "hits": [
            {
                "_index": "report_index-2018.11.17-1",
                "_type": "_doc",
                "_id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                "_score": null,
                "_source": {
                    "severity": 10,
                    "access": "public",
                    "iocs": [
                        {
                            "field": null,
                            "values": [
                                "((process_name:wininit.exe -process_name:system32\/wininit.exe -process_name:windows\\\\winsxs\\\\*wininit.exe*)) -enriched:true"
                            ],
                            "link": null,
                            "match_type": "query",
                            "id": "568480-0"
                        }
                    ],
                    "link": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf",
                    "description": "",
                    "title": "SANS: Unusual wininit.exe path",
                    "tags": [
                        "sans",
                        "wininit",
                        "unusualpath",
                        "attackframework",
                        "attack",
                        "evasion",
                        "t1036",
                        "windows"
                    ],
                    "source_label": "Carbon Black",
                    "id": "4A3e4myPTc2gB2qZpyI2Nw-568480",
                    "timestamp": 1636643103,
                    "feed": {
                        "feed_category": "Partner",
                        "feed_summary": "Know Abnormal...Find Evil. It's often impossible to know malicious behavior before you see it, but we do know what common behaviors are normal or benign. Spotting the difference between normal and abnormal is often the difference between success and failure. Use this watchlist as a reference to quickly identify behavior in Windows that falls outside the scope of 'normal', so you can cut through the noise and instantly investigate and disrupt potential threats. This watchlist is a great starting point for users looking to hone their threat hunting skills.",
                        "feed_id": "4A3e4myPTc2gB2qZpyI2Nw",
                        "feed_name": "Carbon Black SANS",
                        "feed_provider_url": "https://digital-forensics.sans.org/media/poster_2014_find_evil.pdf"
                    },
                    "telemetry": {
                        "global_hit_rate_1d": 0,
                        "global_hit_rate_1w": 0
                    }
                },
                "sort": [
                    "4A3e4myPTc2gB2qZpyI2Nw-568480"
                ]
            }
        ]
    },
    "facets": {
        "severity": {
            "10": 1
        },
        "feed_id": {
            "4A3e4myPTc2gB2qZpyI2Nw": 1
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

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

Field Definition Data Type Values
suggest.query REQUIRED A substring of any field name String
suggest.count The max number of suggestions to return String

Examples

Request 
GET https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/suggest?suggest.query=test
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "suggest": [
        { "term": "severity", "weight": 97 },
        { "term": "feed_provider_url", "weight": 89 }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/threathunter/feedsearch/v1/orgs/ABCD1234/suggest?suggest.query=test \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
    "suggest": [
        { "term": "severity", "weight": 97 },
        { "term": "feed_provider_url", "weight": 89 }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Last modified on June 7, 2023