Process Search V1 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

Service Category has changed.

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

Getting Started

Enterprise EDR’s process searches are asynchronous. This means that in order to get results for some search, you must start a search by calling POST /start and then get results by calling POST /results with query_id as a parameter.

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/api_id.
  2. Content-Type: application/json
  3. accept: application/json

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

  • <cbc-hostname> should be replaced with 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 API Access page.
  • /api/investigate/v1 is the Service Category
  • /threathunter/ is the former Service Category, and can still be used through December 31st, 2020

API calls

Start Asynchronous Aggregation Search on Enriched Events

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Starts an aggregation job that will aggregate enriched events based on the given aggregation field.

RBAC Permissions Required

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

Request

POST <cbc-hostname>/api/investigate/v1/orgs/{org_key}/enriched_events/aggregation_jobs/{aggregation_field}

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>"
    }
}

Request Schema

Field Description Default Required
aggregation_field Solr field to aggregate on (currently, can only be device_id or process_sha256) N/A Yes

Response

Code Description Content-Type Content
200 Successfully submitted search for event aggregation 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/enriched_events/aggregation_jobs/device_id

Body 

{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "terms": {
    "fields": [
      "process_username"
    ],
    "rows": 100
  },
  "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": "dd30f255-88f0-4bb5-95d7-29dba1cd7980"
}

Retrieve Results for an Enriched Event Aggregation Job

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Retrieves the aggregated enriched events search results for a given query 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/v1/orgs/{org_key}/enriched_events/aggregation_jobs/{jobID}/results

Request Schema

Field Description Default Required
jobID Job id to retrieve results of enriched event N/A Yes

Response

Code Description Content-Type Content
200 Successfully submitted search for Aggregations 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

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/enriched_events/aggregation_jobs/QWER1234/results

Response 

{
    "results": [
        {
            "backend_timestamp": "2020-01-19T04:36:08.377Z",
            "device_id": "43407",
            "device_name": "win7x64",
            "device_os": "WINDOWS",
            "device_policy": "sm-restrictive",
            "device_policy_id": 11200,
            "device_timestamp": "2020-01-19T04:28:40.190Z",
            "enriched": true,
            "enriched_event_type": "NETWORK",
            "event_description": "The application \"<share><link hash=\"93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8\">C:\\Windows\\System32\\svchost.exe -k LocalServiceNetworkRestricted</link></share>\" established a <accent>UDP/67</accent> connection to <share><accent>10.210.8.10</accent></share><accent>:67</accent> (<share><accent>ENGLAB-DC-01.CBENGLAB.COM</accent></share>) from <share><accent>10.210.33.17</accent></share><accent>:68</accent>. The device was off the corporate network using the public address <accent>144.121.3.50</accent> (<accent>Win7x64.cbenglab.com</accent>, located in United States). The operation was successful.",
            "event_id": "422af3fc3a7411ea8da649e797467dc0",
            "event_type": "netconn",
            "index_class": "default",
            "legacy": true,
            "num_devices": 1,
            "num_events": 808,
            "org_id": "ABCD1234",
            "parent_guid": "ABCD1234-0000a98f-000001fc-00000000-1d5cb7ef06c99d9",
            "parent_pid": 508,
            "partition_id": 0,
            "process_effective_reputation": "TRUSTED_WHITE_LIST",
            "process_guid": "ABCD1234-0000a98f-00000314-00000000-1d5cb7ef3c327db",
            "process_hash": [
                "c78655bc80301d76ed4fef1c1ea40a7d",
                "93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8"
            ],
            "process_name": "c:\\windows\\system32\\svchost.exe",
            "process_pid": [
                788
            ],
            "process_username": [
                "NT AUTHORITY\\LOCAL SERVICE"
            ]
        }
    ],
    "num_found": 6,
    "num_available": 1,
    "contacted": 6,
    "completed": 6
}

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/enriched_events/search_jobs` API is deactivated. Please use the Enriched Events Search API instead.

Creates an enriched events search job. The results for the search job may be requested using the query ID returned.

RBAC Permissions Required

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

Request

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

Body 

{
    "search_params": "<object>"
}

Response

Code Description Content-Type Content
200 Successfully created enriched events search 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/enriched_events/search_jobs

Body 

{
    "search_params": {
        "q": "*:*",
        "cb.process_guid": "ABCD1234-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d"
    }
}

Response 

{
    "query_id": "66e63a57-94c7-466c-93b1-9a18f87a975e",
    "query": {
        "cb.event_docs": true,
        "cb.max_backend_timestamp": 1580318430072,
        "cb.min_backend_timestamp": 0,
        "cb.min_device_timestamp": 0,
        "cb.process_guid": "ABCD1234-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d",
        "fq": "{!collapse field=event_id sort=\"device_timestamp desc\"}",
        "q": "*:*",
        "rows": 500,
        "start": 0
    }
}

Get Enriched Events Results for Query ID

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/enriched_events/search_jobs/{query_id}/results` API is deactivated. Please use the Enriched Events Search API instead.

Retrieves the enriched events search results for a given query 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/v1/orgs/{org_key}/enriched_events/search_jobs/{query_id}/results

Request Schema

Field Description Default Required
query_id The query id representing the result set to get N/A Yes
rows The number of rows to return, used for pagination 10 No
start The index of the row to start pagination 0 No
query_condition SQL condition for filtering results. Available only for cb.output_format=parquet N/A No
query_group SQL group statement for grouping results. Available only for cb.output_format=parquet N/A No
query_sort Sort column and direction for results. Available only for cb.output_format=parquet N/A No
query_columns List of selected columns to output in results. It can include aliases and SQL-style operators. Available only for cb.output_format=parquet N/A No
facet.limit The number of facets to return per category 100 No

Response

Code Description Content-Type Content
200 Successfully created enriched events search 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

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/enriched_events/search_jobs/66e63a57-94c7-466c-93b1-9a18f87a975e/results?rows=10&start=1&facet.limit=1

Response 

{
    "query_id": "66e63a57-94c7-466c-93b1-9a18f87a975e",
    "response_header": {
        "num_found": 55950,
        "num_available": 3968,
        "searchers_meta": {
            "contacted": 31,
            "completed": 31
        },
        "start_time": 0,
        "end_time": 1580318430072
     },
    "data": [
        {
            "alert_id": [
                "null/4R6HSJPE"
            ],
            "backend_timestamp": "2019-09-27T18:10:44.559Z",
            "childproc_count": 0,
            "crossproc_count": 0,
            "device_id": 21212,
            "device_name": "win-ia9nq1gn8oi",
            "device_policy_id": 11200,
            "device_timestamp": "2019-09-27T18:09:33.023Z",
            "enriched": true,
            "enriched_event_type": "SYSTEM_API_CALL",
            "event_description": "The application \"<share><link hash=\"03d43ee1f2f4f152840f7b5d8dd3386a1c659de7f4f7c951cbb40324c97e4c18\">C:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe</link></share>\" attempted to create a viewable window, by calling the function \"CreateWindowExW\". The operation was successful.",
            "event_id": "090d8680e15211e9b5b01fdf23d4a711",
            "event_type": "crossproc",
            "filemod_count": 0,
            "index_class": "longTerm",
            "legacy": true,
            "modload_count": 0,
            "netconn_count": 0,
            "org_id": "ABCD1234",
            "parent_guid": "ABCD1234-000052dc-00000680-00000000-1d51fb586bbfb9f",
            "parent_pid": 1664,
            "partition_id": 0,
            "process_guid": "ABCD1234-000052dc-000000f4-00000000-1d5755eb6ad1d49",
            "process_hash": [
                "2d1f6f8a32f88f3d0726ade0373f0317",
                "03d43ee1f2f4f152840f7b5d8dd3386a1c659de7f4f7c951cbb40324c97e4c18"
            ],
            "process_name": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
            "process_pid": [
                244
            ],
            "process_terminated": false,
            "process_username": [
                "WIN-IA9NQ1GN8OI\\bit9rad"
            ],
            "regmod_count": 0,
            "scriptload_count": 0
        },
        ...
      ],
      "facets": {
      "facet_fields": {},
      "facet_queries": {},
      "facet_ranges": {},
      "facet_intervals": {},
      "num_found": 0
    }
}

Get Events Associated with a Given Process

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/events/_search` API is deactivated. Please use the Process Search API instead.

Fetch the events associated with a given process, cb.process_guid. These events are often more complete than the enriched event documents but, unlike the enriched event searches, must be focused on a single process.

If the cb.process_guid value does not match a valid process_guid then a 400 Bad Request will be returned. Additionally if process_guid is included in the q property then it must match the guid included in cb.process_guid.

RBAC Permissions Required

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

Request

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

Body 

{
    "search_params": "<object>"
}

Request Body Schema

Field Description Default Required
q Keeping this parameter as *:* allows you to query everything N/A Yes
cb.process_guid This is a process GUID, obtained from Enterprise EDR N/A Yes

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
401 Unauthorized 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/events/_search

Body 

{
    "search_params": {
        "q": "*:*",
        "cb.process_guid": "WNEXFKQ7-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d"
    }
}

Response 

{
    "response_header": {
        "num_found": 11457,
        "num_available": 1940,
        "total_segments": 2,
        "processed_segments": 2
    },
    "docs": [
        {
          "backend_timestamp": "2020-01-06T18:32:24.046Z",
          "created_timestamp": "2020-01-13T20:19:17.459Z",
          "crossproc_action": [
              "ACTION_API_CALL"
          ],
          "crossproc_api": "MiniDumpWriteDump",
          "crossproc_effective_reputation": "REP_WHITE",
          "crossproc_name": "c:\\program files (x86)\\google\\chrome\\application\\chrome.exe",
          "crossproc_process_guid": "WNEXFKQ7-0000a98f-00001100-00000000-1d5c26077595d4c",
          "crossproc_sha256": "c5be020db6f1803f28e37427975c59379bff1b084fa48bc98c19af07d9a78397",
          "crossproc_target": false,
          ...,
          ...
        }
    ],
    "facet_counts": {
        "facet_fields": {},
        "facet_queries": {},
        "facet_ranges": {},
        "facet_intervals": {},
        "num_found": 0
    }
}

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

If value_search_query is true in the response, this indicates the query included one or more strings that lack a field. For example, q=event_type:netconn would return "value_search_query": false, whereas q=event_type would return "value_search_query": true. In the latter case, the API assumes the request is looking for “event_type” in any field’s values.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/events/search_validation?q==<string>&cb.min_backend_timestamp=<integer>&cb.max_backend_timestamp=<integer>"

Request Schema

Field Description Default Required
q Keeping this parameter as *:* allows you to query everything N/A Yes
cb.min_backend_timestamp Start time for the query N/A No
cb.max_backend_timestamp End time for the query N/A No

Response

Code Description Content-Type Content
200 Successfully got event validated 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
401 Unauthorized 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

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/events/search_validation?q="alert_id:ALBPZQR3"

Response 

{
  "invalid_message": "string",
  "invalid_trigger_offset": 0,
  "valid": true
}

Get Suggestions for Event Searching

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns suggestions for an event search based on fields in the organization’s system. Will return field names if the “suggest.q” parameter does not yet contain a colon and will return no suggestion otherwise. This route does not support value suggestions.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/events/search_suggestions?suggest.q=<string>&suggest.count=50

Request Schema

Field Description Default Required
suggest.q Query to generate suggestions for N/A Yes
suggest.count Number of suggestions to return 50 No

Response

Code Description Content-Type Content
200 Successfully got event validated 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

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/events/search_suggestions?suggest.q=pro&suggest.count=1

Response

{
    "suggestions": [
        {
            "term": "process_guid",
            "weight": 1450,
            "required_skus_all": [],
            "required_skus_some": [
                "threathunter",
                "defense"
            ]
        }
    ]
}

Get Time Limits for Available Data

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns the time range for available data for a given organization.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/limits

Response

Code Description Content-Type Content
200 Successfully got the upper and lower time limits 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/limits

Response 

{
    "time_bounds": {
        "lower": 1564686473166,
        "upper": 1579023412990
    }
}

Get a List of All Available Process Result Sets

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns a list of all available process result sets in the form of query IDs. Callers can use query IDs to fetch results for previously create search jobs.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/search_jobs

Response

Code Description Content-Type Content
200 Successfully got the upper and lower time limits 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs

Response 

{
    "query_ids": [
      "ABCD1234/005397cf-e334-4929-9977-d219047d9b96",
      "ABCD1234/00b1df2f-4de0-4915-89e1-a9c19a25628e",
      "ABCD1234/0108ad72-d13d-4f75-9bc5-de60750eb2f9",
      "ABCD1234/014b9a78-f439-47fe-80ab-968a24431245",
      "ABCD1234/023985e4-28dd-455c-b98a-28bb7e1ea276",
      ...
    ]
}

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/processes/search_jobs` API is deactivated. Please use the Process Search API instead.

Creates a search job. The results for the search job may be requested using the query ID returned.

RBAC Permissions Required

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

Request

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

Request Schema

Field Description Default Required
q Keeping this parameter as *:* allows you to query everything N/A Yes

Response

Code Description Content-Type Content
200 Successfully started asynchronous process search 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs

Body 

{
    "search_params": {
    	"q": "*.*"
    }
}

Response 

{
    "query_id": "45694120-8b28-4905-a9aa-c84b04e77d78",
    "query": {
        "cb.max_backend_timestamp": 1579025578116,
        "cb.min_backend_timestamp": 0,
        "cb.min_device_timestamp": 0,
        "q": "*.*",
        "rows": 500,
        "start": 0
    }
}

Get Process Results

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/processes/search_jobs/{{query_id}}/results` API is deactivated. Please use the Processes Search API instead.

Retrieves the search results for a given query 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/v1/orgs/{org_key}/processes/search_jobs/{{query_id}}/results

Request Schema

Field Description Default Required
rows The number of rows to return, used for pagination 10 No
start The index of the row to start pagination at 0 No
query_condition SQL condition for filtering results. Available only for cb.output_format=parquet N/A No
query_group SQL group statement for grouping results. Available only for cb.output_format=parquet N/A No
query_sort Sort column and direction for results. Available only for cb.output_format=parquet N/A No
query_columns List of selected columns to output in results. It can include aliases and SQL-style operators Available only for cb.output_format=parquet N/A No
facet.limit The number of facets to return per category 100 No

Response

Code Description Content-Type Content
200 Successfully got process results 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs/45694120-8b28-4905-a9aa-c84b04e77d78/results?rows=10&start=0&facet.limit=10

Response 

{
    "query_id": "45694120-8b28-4905-a9aa-c84b04e77d78",
    "response_header": {
        "num_found": 0,
        "num_available": 0,
        "searchers_meta": {
            "contacted": 0,
            "completed": 0
        },
        "start_time": 0,
        "end_time": 1579025578116
    },
    "data": [],
    "facets": {
        "facet_fields": {},
        "facet_queries": {},
        "facet_ranges": {},
        "facet_intervals": {},
        "num_found": 0
    }
}

Get the Status of a Query

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns the status of a search job. A job is finished when “completed” is equal to the “contacted”. This route should be used when polling for search job completion as it is more efficient than fetching results each time.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/search_jobs/{query_id}

Response

Code Description Content-Type Content
200 Successfully retrieved status of process search N/A 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs/45694120-8b28-4905-a9aa-c84b04e77d78

Response 

{
    "contacted": 0,
    "completed": 0,
    "query": {
        "cb.max_backend_timestamp": 1579025578116,
        "cb.min_backend_timestamp": 0,
        "cb.min_device_timestamp": 0,
        "q": "*.*",
        "rows": 500,
        "start": 0
    },
    "search_initiated_time": 1579025578206,
    "connector_id": "TZV468322A"
}

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Cancels the search with the given query ID so no new search results will appear.

RBAC Permissions Required

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

Request

DELETE <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/search_jobs/{query_id}

Response

Code Description Content-Type Content
204 Successfully deleted a process search N/A No Content
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

DELETE https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs/45694120-8b28-4905-a9aa-c84b04e77d78

Response

No Responses

Process Search Suggestions

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns suggestions for a process search based on fields and values in the organization’s system. Will return field names if the “suggest.q” parameter does not yet contain a colon and will return values otherwise.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/search_suggestions?suggest.q=<string>&suggest.count=10

Request Schema

Field Description Default Required
suggest.q Query to generate suggestions for N/A Yes
suggest.count Number of suggestions to return 50 No

Response

Code Description Content-Type Content
200 Successfully got process search suggestions 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_suggestions?suggest.q=pro&suggest.count=1

Response 

{
    "suggestions": [
        {
            "term": "process_name",
            "weight": 2800,
            "required_skus_all": [],
            "required_skus_some": [
                "threathunter",
                "defense"
            ]
        }
    ]
}

Process Search Validation

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Returns the validation status of a given process query and potentially gives suggestions on how to fix invalid queries.

If value_search_query is true in the response, this indicates the query included one or more strings that lack a field. For example, q=process_name:chrome.exe would return "value_search_query": false, whereas q=process_name would return "value_search_query": true. In the latter case, the API assumes the request is looking for “process_name” in any field’s values.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/search_validation?q=<string>&cb.min_backend_timestamp=<integer>&cb.max_backend_timestamp=<integer>

Request Schema

Field Description Default Required
q Keeping this parameter as *:* allows you to query everything N/A Yes
cb.min_backend_timestamp Start time for the query N/A No
cb.max_backend_timestamp End time for the query N/A No

Response

Code Description Content-Type Content
200 Successfully got process search validations 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_validation?q=process

Response 

{
    "valid": true,
    "value_search_query": true
}

Process Summary

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/processes/summary` API is deactivated. Please use the Processes Search API instead.

Returns a flat representation of the process. This returns the same view of a process as the process tree route, just flattened so it’s easier to grok.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/summary?process_guid=<string>&parent_guid=<string>

Request Schema

Field Description Default Required
process_guid Process GUID that should represent the main node of the tree N/A Yes
parent_guid Parent process for the main node process N/A No

Response

Code Description Content-Type Content
200 Successfully got process search validations 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/summary?process_guid=WNEXFKQ7-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d

Response 

{
    "incomplete_results": false,
    "process": {
        "_s3_location": "ASDFGakM4TRq1234yARhCQ:16f7c2122ee:0:8af:longTerm:3",
        "backend_timestamp": "2020-01-06T18:32:24.046Z",
        "childproc_count": 0,
        "crossproc_count": 0,
        "device_external_ip": "",
        "device_id": 43407,
        "device_internal_ip": "144.121.3.50",
        "device_name": "win7x64",
        "device_os": "WINDOWS",
        ...
      },
    "siblings": [
        {
        "_s3_location": "ASDFGKT9212345F2RqUA:16f6c38dfdb:2991:1569c:default:3",
            "backend_timestamp": "2020-01-03T16:24:29.859Z",
            "childproc_count": 0,
            "crossproc_count": 9,
            "device_external_ip": "144.121.3.50",
            "device_group": "",
            "device_id": 43407,
            "device_internal_ip": "",
            "device_name": "win7x64",
            "device_os": "WINDOWS",
            ...
          }
      ],
    "parent": {
        "_s3_location": "ASDFGHMT9-K85WsSiu6-Q:11234ae1c7d:2933:df2:default:3",
        "backend_timestamp": "2020-01-04T22:30:30.183Z",
        "childproc_count": 21,
        "crossproc_count": 70,
        "device_external_ip": "144.121.3.50",
        "device_group": "",
        "device_id": 43407,
        "device_internal_ip": "",
        "device_name": "win7x64",
        "device_os": "WINDOWS",
        ...
      },
    "children": [
      {
        "_s3_location": "ASDFG4TRqOlG1234hCQ:16f7c2122ee:8af:82b:longTerm:3",
            "backend_timestamp": "2020-01-06T18:32:24.046Z",
            "childproc_count": 0,
            "crossproc_count": 0,
            "device_external_ip": "",
            "device_id": 43407,
            "device_internal_ip": "144.121.3.50",
            "device_name": "win7x64",
            "device_os": "WINDOWS",
            ...
      }
    ]
}
__

Process Tree

This API is being deactivated.

You may continue to access the documentation below until the `api/investigate/v1/orgs/{org_key}/processes/tree` API is deactivated. Please use the Processes Search API instead.

Returns the process tree representation of a process. The graph will have the parent, if any exist, as the root node in the tree. All subsequent nodes exist under a “children” key.

RBAC Permissions Required

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

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/tree?process_guid=<string>&parent_guid=<string>

Request Schema

Field Description Default Required
process_guid Process GUID that should represent the main node of the tree N/A Yes
parent_guid Parent process for the main node process N/A No

Response

Code Description Content-Type Content
200 Successfully got process tree 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/tree?process_guid=WNEXFKQ7-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d

Response 

{
    "incomplete_results": false,
    "nodes": {
        "_s3_location": "j1uOUr64RtikdhgZ5ZMACw:169c0594afd:20638:1c0b",
        "backend_timestamp": "2019-03-27T18:11:11.228Z",
        "childproc_count": 16,
        "children": [{
                "_s3_location": "j1uOUr64RtikdhgZ5ZMACw:169bc34d38e:12d68a:168ba",
                "backend_timestamp": "2019-03-26T22:52:52.493Z",
                "childproc_count": 1,
                "crossproc_count": 5,
                "device_external_ip": "98.122.36.116",
                "device_id": 18275,
                "device_internal_ip": "",
                "device_name": "jalapeno-win10-pepper",
                "device_os": "WINDOWS",
                "device_timestamp": "2019-03-26T22:50:42.381Z",
                "filemod_count": 43,
                "kinesis_partition_id": "BOSTON7:0",
                "modload_count": 46,
                "netconn_count": 0,
                "org_id": "BOSTON7",
                "org_size_perc": 1,
                "parent_guid": "BOSTON7-00004763-00000e9c-00000000-1d4e426506df1de",
                "parent_hash": [
                    "850b6af15c5a918bb9fa89cc30c24bdd72024332885114a86d8decaab0477fda",
                    "93417f0672ebc2b0f3fb8539e7cd1938"
                ],
                "parent_name": "c:\\windows\\explorer.exe",
                "parent_pid": 3740,
                "partition_id": 0,
                "process_cmdline": [
                    "\"C:\\Windows\\System32\\ie4uinit.exe\" -UserConfig"
                ],
                "process_effective_reputation": "LOCAL_WHITE",
                "process_guid": "BOSTON7-00004763-00000eb0-00000000-1d4e42655dc64ef",
                "process_hash": [
                    "cd5bb2bd300cc5bb9973c968b43fbefb",
                    "4ee7bf27fa8fc8f8ef16a2555403eefca227d6f173f0e6566a91e433e72df4e4"
                ],
                "process_name": "c:\\windows\\system32\\ie4uinit.exe",
                "process_pid": [
                    3760
                ],
                "process_reputation": "TRUSTED_WHITE_LIST",
                "process_terminated": true,
                "process_username": [
                    "jalapeno-WIN10-\\bit9se"
                ],
                "regmod_count": 207,
                "scriptload_count": 0
            },
            {
                "_s3_location": "j1uOUr64RtikdhgZ5ZMACw:169c0594afd:1e94d:1204",
                "backend_timestamp": "2019-03-27T18:11:11.228Z",
                "childproc_count": 91,
                "children": [{
                    "_s3_location": "j1uOUr64RtikdhgZ5ZMACw:169bc39878f:2252f5:6804",
                    "backend_timestamp": "2019-03-26T22:58:00.719Z",
                    "childproc_count": 0,
                    "crossproc_count": 6,
                    "device_external_ip": "98.122.36.116",
                    "device_id": 18275,
                    "device_internal_ip": "",
                    "device_name": "jalapeno-win10-pepper",
                    "device_os": "WINDOWS",
                    "device_timestamp": "2019-03-26T22:52:02.328Z",
                    "filemod_count": 0,
                    "kinesis_partition_id": "BOSTON7:0",
                    "modload_count": 42,
                    "netconn_count": 0,
                    "org_id": "BOSTON7",
                    "org_size_perc": 1,
                    "parent_guid": "BOSTON7-00004763-000016d0-00000000-1d4e4267b947f6d",
                    "parent_hash": [
                        "5fc079f87ed93c7680e531efc4801ea6",
                        "fbabdb68ba095638602aeabf903599db281452040e2bbd3a1ba6491e23dae2ad"
                    ],
                    "parent_name": "c:\\program files (x86)\\google\\chrome\\application\\chrome.exe",
                    "parent_pid": 5840,
                    "partition_id": 0,
                    "process_cmdline": [
                        "\"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe\" --type=gpu-process --field-trial-handle=1540,7846969548857954607,7659868123879754097,131072 --disable-gpu-sandbox --use-gl=disabled --gpu-preferences=KAAAAAAAAACAAwAAAQAAAAAAAAAAAGAAAAAAAAEAAAAIAAAAAAAAACgAAAAEAAAAIAAAAAAAAAAoAAAAAAAAADAAAAAAAAAAOAAAAAAAAAAQAAAAAAAAAAAAAAAFAAAAEAAAAAAAAAAAAAAABgAAABAAAAAAAAAAAQAAAAUAAAAQAAAAAAAAAAEAAAAGAAAA --service-request-channel-token=1531183726095469925 --mojo-platform-channel-handle=4716 /prefetch:2"
                    ],
                    "process_effective_reputation": "TRUSTED_WHITE_LIST",
                    "process_guid": "BOSTON7-00004763-000012ac-00000000-1d4e42686ba0a84",
                    "process_hash": [
                        "5fc079f87ed93c7680e531efc4801ea6",
                        "fbabdb68ba095638602aeabf903599db281452040e2bbd3a1ba6491e23dae2ad"
                    ],
                    "process_name": "c:\\program files (x86)\\google\\chrome\\application\\chrome.exe",
                    "process_pid": [
                        4780
                    ],
                    "process_reputation": "TRUSTED_WHITE_LIST",
                    "process_terminated": true,
                    "process_username": [
                        "jalapeno-WIN10-\\bit9se"
                    ],
                    "regmod_count": 5,
                    "scriptload_count": 0
                }],
                "crossproc_count": 1238,
                "device_external_ip": "98.122.36.116",
                "device_id": 18275,
                "device_internal_ip": "",
                "device_name": "jalapeno-win10-pepper",
                "device_os": "WINDOWS",
                "device_timestamp": "2019-03-27T18:08:37.102Z",
                "filemod_count": 181,
                "kinesis_partition_id": "BOSTON7:0",
                "modload_count": 816,
                "netconn_count": 0,
                "org_id": "BOSTON7",
                "org_size_perc": 1,
                "parent_guid": "BOSTON7-00004763-00000ed4-00000000-1d4e426504f4e5c",
                "parent_hash": [
                    "46b72e05d0b9f489ca60dbd7361039b0",
                    "b5170d0e86b93d83c67636fe2c1207139cfcbc9114bbfd74d127cddcbd8fa114"
                ],
                "parent_name": "c:\\windows\\system32\\userinit.exe",
                "parent_pid": 3796,
                "partition_id": 0,
                "process_cmdline": [
                    "C:\\Windows\\Explorer.EXE"
                ],
                "process_effective_reputation": "TRUSTED_WHITE_LIST",
                "process_guid": "BOSTON7-00004763-00000e9c-00000000-1d4e426506df1de",
                "process_hash": [
                    "93417f0672ebc2b0f3fb8539e7cd1938",
                    "850b6af15c5a918bb9fa89cc30c24bdd72024332885114a86d8decaab0477fda"
                ],
                "process_name": "c:\\windows\\explorer.exe",
                "process_pid": [
                    3740
                ],
                "process_reputation": "TRUSTED_WHITE_LIST",
                "process_terminated": false,
                "process_username": [
                    "jalapeno-WIN10-\\bit9se"
                ],
                "regmod_count": 2492,
                "scriptload_count": 0
            }
        ]
    }
}
__

Evaluate Processes for a Watchlist

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Instructs the system to run watchlist matching for the given watchlist, report, and IOC on all processes within the time range. Watchlist hits will show up asynchronously and are not guaranteed to be visible directly after calling this route.

RBAC Permissions Required

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

Request

POST <cbc-hostname>/api/investigate/v1/orgs/{org_key}/processes/watchlist_evaluation

Request Body

{
    "watchlist_id": "<string>",
    "report_id": "<string>",
    "cb.max_backend_timestamp": "<double>",
    "cb.min_backend_timestamp": "<double>",
    "ioc_id": "<string>"
}

Request Body Schema

Field Description Default Required
watchlist_id Watchlist ID N/A Yes
report_id Report ID N/A Yes
ioc_id Report ID N/A No
cb.min_backend_timestamp Start time for the query N/A No
cb.max_backend_timestamp End time for the query N/A No

Response

Code Description Content-Type Content
204 Successfully evaluated and tagged 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-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/watchlist_evaluation

Body 

{
    "watchlist_id": "b5LGY1CCTtyogVBUwTWLA",
    "report_id": "1"
}

Response

No Response

Get Report Hits

This API is moving locations.

You may continue to access the documentation here. To see the latest documentation for this API see here.

Fetches report hits associated with a single process. This includes both ingress and query hits that are associated with watchlists.

Request

GET <cbc-hostname>/api/investigate/v1/orgs/{org_key}/report_hits?process_guid=<string>&rows=10

Request Body Schema

Field Description Default Required
process_guid Process GUID for which to get report hits N/A Yes
rows Number of report hits to get. N/A No

Response

Code Description Content-Type Content
200 Successfully got report hits 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-eap01.conferdeploy.net/api/investigate/v1//orgs/ABCD1234/report_hits?process_guid=WNEXFKQ7-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d&rows=1

Response 

{
    "report_hits": {}
}


Last modified on January 18, 2022