Process Search V2 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: v2

Service Category has changed.

You may continue to access the API from /threathunter/search/ until December 31st, 2020. For more information see here.

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for these APIs see here for Enriched Events and here for Processes.

Getting Started

Enterprise EDR’s process searches are asynchronous. This means that in order to get results for a search query, you must start a search by calling POST /search_jobs and then get results by calling GET /results on the /search_jobs/ route with query_id as a URL parameter. New to the v2 Search API is a separate set of requests for facets to quickly obtain prevalence of many filtering terms - similarly calling POST /facet_jobs followed by GET /results on the /facet_jobs/ route with the respective query_id.

For more information about Process and Event Search Fields.

Common Headers

Most API routes require all three headers, however, there are exceptions.

  1. X-Auth-Token: required. This is your authentication token, it is api_key/connector_id.
  2. Content-Type: application/json
  3. accept: application/json

Note

  • <cbc-hostname> is the parent URL for your Carbon Black Cloud instance.
  • {org_key} or org_key refers to your organization key found in the Carbon Black Cloud’s APIs page.

Start Enriched Events Facet Job

Creates an enriched events facet job. The results for the facet job may be requested using the job ID returned. This route will not request processes.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events CREATE

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/enriched_events/facet_jobs

Body 

{
    "criteria": "<object>",
    "exclusions": "<object>",
    "query": "<string>",
    "ranges": [
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        },
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        }
    ],
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": <long>
    },
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully submitted search for enriched events facet application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/enriched_events/facet_jobs

Body 

{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "terms": {
    "fields": [
      "process_username"
    ],
    "rows": 100
  },
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

{
    "job_id": "505bf994-a335-426e-bd8c-b2e388f977f2"
}

Get Enriched Events Facet Results

Retrieves the process facet results for a given job ID.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

GET <cbc-hostname>/api/investigate/v2/orgs/{org_key}/enriched_events/facet_jobs/{job_id}/results

Request Schema

Field Description Default Required
limit Maximum number of facets per category (i.e Any Process Search Fields listed in terms.fields) 100 No

Response

Code Description Content-Type Content
200 Successfully got enriched event facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/enriched_events/facet_jobs/505bf994-a335-426e-bd8c-b2e388f977f2/results?limit=100

Response 

{
    "ranges": [],
    "terms": [
        {
            "values": [
                {
                    "total": 414,
                    "id": "NT AUTHORITY\\SYSTEM",
                    "name": "NT AUTHORITY\\SYSTEM"
                },
                {
                    "total": 323,
                    "id": "NT AUTHORITY\\NETWORK SERVICE",
                    "name": "NT AUTHORITY\\NETWORK SERVICE"
                },
                {
                    "total": 71,
                    "id": "NT AUTHORITY\\LOCAL SERVICE",
                    "name": "NT AUTHORITY\\LOCAL SERVICE"
                }
            ],
            "field": "process_username"
        }
    ],
    "num_found": 808,
    "contacted": 6,
    "completed": 6
}

Start an Enriched Events Search Job

Creates an enriched events search job. The results for the search job may be requested using the job ID returned. This route will not request facets.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events CREATE

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/enriched_events/search_jobs

Body

{
    "criteria": "<object>",
    "exclusions": "<object>",
    "fields": ["<string>", "<string>"],
    "query": "<string>",
    "rows": <long>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": <long>,
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully submitted search for enriched events application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/enriched_events/search_jobs

Body 

  
{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "fields": ["*", "process_start_time"],
  "sort": [
    {
      "field": "device_timestamp",
      "order": "asc"
    }
  ],
  "start": 0,
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

  
{
    "job_id": "442f48e8-a4ce-4574-986f-5695b9e52dcc"
}

Get Enriched Events Search Results

Retrieves the enriched events search results for a given job ID. Results will be sorted based on the sort parameter used when starting the search.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

GET <cbc-hostname>/api/investigate/v2/orgs/{org_key}/enriched_events/search_jobs/{job_id}/results

Request Schema

Field Description Default Required
start Starting rows of events, used for pagination 0 No
rows Number of events to get, used for pagination 10 No

Response

Code Description Content-Type Content
200 Successfully got enriched event application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/enriched_events/search_jobs/442f48e8-a4ce-4574-986f-5695b9e52dcc/results?start=0&rows=1

Response 

  
{
    "results": [
        {
            "backend_timestamp": "2020-01-18T19:12:38.642Z",
            "device_id": 12345,
            "device_name": "win7x64",
            "device_policy_id": 11200,
            "device_timestamp": "2020-01-18T19:10:53.310Z",
            "enriched": true,
            "enriched_event_type": "NETWORK",
            "event_description": "The application \"<share><link hash=\"93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8\">C:\\Windows\\system32\\svchost.exe -k NetworkService</link></share>\" established a <accent>TCP/80</accent> connection to <share><accent>00.12.34.56</accent></share><accent>:80</accent> (<share><accent>crl.verisign.com</accent></share>, located in United States) from <share><accent>00.12.34.56</accent></share><accent>:57146</accent>. The device was off the corporate network using the public address <accent>34.56.78.90</accent> (<accent>Win7x64.cbenglab.com</accent>, located in United States). The operation was successful.",
            "event_id": "4c17fc3d3a2611ea8010ff74bcfa02b4",
            "event_type": "netconn",
            "index_class": "default",
            "legacy": true,
            "org_id": "ASDF1234",
            "parent_guid": "ASDF1234-0000a98f-000001fc-00000000-1d5cb7ef06c99d9",
            "parent_pid": 508,
            "partition_id": 0,
            "process_guid": "ASDF1234-0000a98f-0000034c-00000000-1d5cb7ef5152b42",
            "process_hash": [
                "c78655bc80301d76ed4fef1c1ea40a7d",
                "93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8"
            ],
            "process_name": "c:\\windows\\system32\\svchost.exe",
            "process_pid": [
                844
            ],
            "process_username": [
                "NT AUTHORITY\\NETWORK SERVICE"
            ]
        }
    ],
    "num_found": 808,
    "num_available": 52,
    "contacted": 6,
    "completed": 6
}

Get Events Facet Associated with a Given Process

Get facets for the events associated with a given process. This route will not request events.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/events/{process_guid}/_facet

Body

  
{
    "criteria": "<object>",
    "exclusions": "<object>",
    "query": "<string>",
    "ranges": [
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        },
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        }
    ],
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": <long>
    },
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully got event facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/events/ASDF1234-0000a98f-0000034c-00000000-1d5cb7ef5152b42/_facet

Body 

  
{
  "criteria": {
  	"event_type": ["netconn"]
  },
  "query": "netconn_action:ACTION_CONNECTION_CREATE OR netconn_action:ACTION_CONNECTION_ESTABLISHED",
  "terms": {
    "fields": [
      "event_guid"
    ],
    "rows": 10
  },
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

  
{
    "ranges": [],
    "terms": [],
    "num_found": 0,
    "total_segments": 0,
    "processed_segments": 0
}

Get Events Associated with a Given Process

Fetch the events associated with a given process. These events are often more complete the the enriched event documents but, unlike the enriched event searches, must be focused on a single process. This route will not request facets.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/events/{process_guid}/_search

Body

  
{
    "criteria": "<object>",
    "exclusions": "<object>",
    "fields": ["<string>", "<string>"],
    "query": "<string>",
    "rows": <long>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": <long>,
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully got events application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/events/ASDF1234-0000a98f-0000034c-00000000-1d5cb7ef5152b42/_search

Body 

  
{
  "criteria": {
  	"event_type": ["netconn"]
  },
  "query": "netconn_action:ACTION_CONNECTION_CREATE OR netconn_action:ACTION_CONNECTION_ESTABLISHED",
  "fields": ["*", "process_start_time"],
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

  
{
    "results": [
        {
            "backend_timestamp": "2020-01-23T22:48:14.099Z",
            "created_timestamp": "2020-01-30T21:11:29.490Z",
            "enriched": true,
            "enriched_event_type": "NETWORK",
            "event_description": "The application \"<share><link hash=\"1030ce4102dac701fab043e40444e8f6c96c8c04b5bd512a59e1a4999d22b38c\">C:\\windows\\system32\\svchost.exe</link></share>\" attempted to establish a <accent>TCP/443</accent> connection to <share><accent>20.36.218.63</accent></share><accent>:443</accent> from <share><accent>10.210.33.22</accent></share><accent>:57503</accent>. The device was off the corporate network using the public address <accent>144.121.3.50</accent>. The operation was blocked by the operating system.",
            "event_guid": "U_xc-0FeSu-77aY2CSKgXA",
            "event_hash": "a78709ea459e525d30ab9ddc89b1ce6c",
            "event_timestamp": "2020-01-23T22:45:41.207Z",
            "event_type": "netconn",
            "legacy": true,
            "legacy_description": "The application \"<share><link hash=\"1030ce4102dac701fab043e40444e8f6c96c8c04b5bd512a59e1a4999d22b38c\">C:\\windows\\system32\\svchost.exe</link></share>\" attempted to establish a <accent>TCP/443</accent> connection to <share><accent>20.36.218.63</accent></share><accent>:443</accent> from <share><accent>10.210.33.22</accent></share><accent>:57503</accent>. The device was off the corporate network using the public address <accent>144.121.3.50</accent>. The operation was blocked by the operating system.",
            "netconn_action": "ACTION_CONNECTION_CREATE",
            "netconn_inbound": false,
            "netconn_local_ipv4": 181543190,
            "netconn_local_port": 57503,
            "netconn_protocol": "PROTO_TCP",
            "netconn_remote_ipv4": 337959487,
            "netconn_remote_port": 443,
            "process_guid": "ASDF1234-003d630d-0000041c-0000041c-1d5abbc325c58b4",
            "process_pid": 1052
        },
        ...
      ],
      "num_found": 6,
      "num_available": 6,
      "total_segments": 13,
      "processed_segments": 13
}

Start a Process Facet Job

Creates a process facet job. The results for the facet job may be requested using the job ID returned. This route will not request processes.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events CREATE

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/processes/facet_jobs

Body

  
{
    "criteria": "<object>",
    "exclusions": "<object>",
    "query": "<string>",
    "ranges": [
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        },
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        }
    ],
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": <long>
    },
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully submitted search for process facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/processes/facet_jobs

Body 

  
{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "terms": {
    "fields": [
      "process_username"
    ],
    "rows": 100
  },
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

  
{
    "job_id": "c167cc5b-5741-427e-8412-8b89f0b17f9c"
}

Get Process Facets

Retrieves the process facet results for a given job ID.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

GET <cbc-hostname>/api/investigate/v2/orgs/{org_key}/processes/facet_jobs/{job_id}/results

Request Schema

Field Description Default Required
limit Maximum number of facets per category (i.e Any Process Search Fields listed in terms.fields) 100 No

Response

Code Description Content-Type Content
200 Successfully got processes facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/processes/facet_jobs/c167cc5b-5741-427e-8412-8b89f0b17f9c/results?limit=1

Response 

  
{
    "ranges": [],
    "terms": [
        {
            "values": [
                {
                    "total": 10701,
                    "id": "NT AUTHORITY\\NETWORK SERVICE",
                    "name": "NT AUTHORITY\\NETWORK SERVICE"
                }
            ],
            "field": "process_username"
        }
    ],
    "num_found": 20818,
    "contacted": 6,
    "completed": 6
}

Start a Process Search Job

Creates a process search job. The results for the search job may be requested using the job ID returned. This route will not request facets.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events CREATE

Request

POST <cbc-hostname>/api/investigate/v2/orgs/{org_key}/processes/search_jobs

Body

  
{
    "criteria": "<object>",
    "exclusions": "<object>",
    "fields": ["<string>", "<string>"],
    "query": "<string>",
    "rows": <long>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": <long>,
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Response

Code Description Content-Type Content
200 Successfully submitted search for processes application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/processes/search_jobs

Body 

  
{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "fields": ["*", "process_start_time"],
  "sort": [
    {
      "field": "device_timestamp",
      "order": "asc"
    }
  ],
  "start": 0,
  "time_range": {
    "end": "2020-01-27T18:34:04Z",
    "start": "2020-01-18T18:34:04Z"
  }
}

Response 

  
{
    "job_id": "6b414c3e-c664-45ea-bb69-3aabf4430f7e"
}

Get Process Search Results

Retrieves the process search results for a given job ID. Results will be sorted based on the sort parameter used when starting the search.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.search.events READ

Request

GET <cbc-hostname>/api/investigate/v2/orgs/{org_key}/processes/search_jobs/{job_id}/results

Request Schema

Field Description Default Required
start starting rows of events, used for pagination 0 No
rows number of events to get, used for pagination 10 No

Response

Code Description Content-Type Content
200 Successfully got processes application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap.conferdeploy.net/api/investigate/v2/orgs/ASDF1234/processes/search_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e/results?start=0&rows=1

Response 

  
{
    "results": [
        {
            "backend_timestamp": "2020-01-19T15:25:31.064Z",
            "childproc_count": 0,
            "crossproc_count": 40,
            "device_id": 43407,
            "device_name": "win7x64",
            "device_policy_id": 11200,
            "device_timestamp": "2020-01-18T19:46:22.885Z",
            "filemod_count": 0,
            "index_class": "default",
            "modload_count": 5,
            "netconn_count": 55380,
            "org_id": "ASDF1234",
            "parent_guid": "ASDF1234-0000a98f-000001fc-00000000-1d5cb7eca37b799",
            "parent_pid": 508,
            "partition_id": 0,
            "process_guid": "ASDF1234-0000a98f-0000051c-00000000-1d5cb7ed061e7ef",
            "process_hash": [
                "c78655bc80301d76ed4fef1c1ea40a7d",
                "93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8"
            ],
            "process_name": "c:\\windows\\system32\\svchost.exe",
            "process_pid": [
                1308
            ],
            "process_username": [
                "NT AUTHORITY\\LOCAL SERVICE"
            ],
            "regmod_count": 2,
            "scriptload_count": 0
        }
    ],
    "num_found": 760,
    "num_available": 33,
    "contacted": 6,
    "completed": 6
}


Last modified on January 18, 2022