Threat Hunt API


Overview

Use this API to get descriptive information about a threat hunt - targeted investigation - conducted by the MDR team.

Requirements

  • Enterprise EDR
  • Managed Threat Hunting

Key Features

  • If an alert has the threat_hunt_id populated, use this API get information about the Threat Hunt that generated the alert.
  • The threat_hunt_id and threat_hunt_name can also be used to search for alerts that were found in that threat hunt.

Resources


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.
  • {cbc-hostname}/mdr/threathuntingview/v1/orgs/{org_key}/threathunts/{id}

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Alerts > ThreatHunt > org.mdr.threathunts, 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.


API Calls


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.mdr.threathunts READ Majority of environments

Get Threat Hunt by ID

Get Threat Hunt by ID



Request 
GET {cbc-hostname}/mdr/threathuntingview/v1/orgs/{org_key}/threathunts/{id}


Response Codes

Code Description Content-Type Content
200 OK application/json Example response below
400 Bad Request application/json N/A
403 Forbidden application/json N/A
429 Too Many Requests application/json N/A
500 Internal Server Error application/json N/A

Examples

Request 
GET https://defense.conferdeploy.net/mdr/threathuntingview/v1/orgs/ABCD1234/threathunts/aa11-bb22-cc33-dd44
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "aa11-bb22-cc33-dd44",
    "name": "GroutLoader Test",
    "description": "GroutLoader was discovered by security researches today; it leverages a previously undiscovered 0-day in Microsoft Excel to download & remotely execute malicious powershell. While details of the threat are still emerging, actors appear to be establishing persistence on assets through scheduled tasks.",
    "threat_hunt_status": "COMPLETED",
    "created_timestamp": "2023-09-20T03:03:13.540Z",
    "time_range": {
        "start": "2023-08-20T00:00:00Z",
        "end": "2023-09-20T03:03:13.540Z",
        "range": "-1M"
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Last modified on October 25, 2023