Process 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

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.

For more information about Process Search Fields.

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

Note

  • <psc-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 Asynchronous Aggregation Search on Enriched Events

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.events READ

Request

POST <psc-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/ASDF1234/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

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)
threathunter.events READ

Request

GET <psc-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/ASDF1234/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": "ASDF1234",
            "parent_guid": "ASDF1234-0000a98f-000001fc-00000000-1d5cb7ef06c99d9",
            "parent_pid": 508,
            "partition_id": 0,
            "process_effective_reputation": "TRUSTED_WHITE_LIST",
            "process_guid": "ASDF1234-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
}

Start an Asynchronous Enriched Events Search

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)
threathunter.events READ

Request

POST <psc-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/ASDF1234/enriched_events/search_jobs

Body

{
    "search_params": {
        "q": "*:*",
        "cb.process_guid": "ASDF1234-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": "ASDF1234-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

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)
threathunter.events READ

Request

GET <psc-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/ASDF1234/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": "ASDF1234",
            "parent_guid": "ASDF1234-000052dc-00000680-00000000-1d51fb586bbfb9f",
            "parent_pid": 1664,
            "partition_id": 0,
            "process_guid": "ASDF1234-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

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)
threathunter.events READ

Request

POST <psc-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/ASDF1234/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
    }
}

Get Validation for Event Search

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.events READ

Request

GET <psc-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/ASDF1234/events/search_validation?q="alert_id:ALBPZQR3"

Response

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

Get Suggestions for Event Searching

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)
threathunter.events READ

Request

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

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.events READ

Request

GET <psc-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/ASDF1234/processes/limits

Response

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

Get a List of All Available Process Result Sets

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)
threathunter.events READ

Request

GET <psc-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/ASDF1234/processes/search_jobs

Response

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

Start an Asynchronous Process Search

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)
threathunter.events CREATE

Request

POST <psc-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/ASDF1234/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

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)
threathunter.events READ

Request

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

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)
threathunter.events READ

Request

GET <psc-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/ASDF1234/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"
}

Cancel Process Search

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.events DELETE

Request

DELETE <psc-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/ASDF1234/processes/search_jobs/45694120-8b28-4905-a9aa-c84b04e77d78

Response

No Responses

Process Search Suggestions

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)
threathunter.events READ

Request

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

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
threathunter.events READ

Request

GET <psc-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/ASDF1234/processes/search_validation?q=process

Response

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

Process Summary

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)
threathunter.events READ

Request

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

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)
threathunter.events READ

Request

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

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)
threathunter.events UPDATE

Request

POST <psc-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/ASDF1234/processes/watchlist_evaluation

Body

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

Response

No Response

Get Report Hits

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

Request

GET <psc-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/ASDF1234/report_hits?process_guid=WNEXFKQ7-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d&rows=1

Response

{
    "report_hits": {}
}

Last modified on May 5, 2020