Enriched Events Search API

Overview

This API lets you search through all the data that is reported by your organization’s Endpoint Standard-enabled sensors to find one or more specific enriched events that match the consumer’s search criteria. You can:

  • See tactics, techniques and procedures (TTPs) and the MITRE CVEs associated with potentially malicious activity
  • Get visibility into the cyber kill chain stage at which attacks were stopped
  • Identify the family and name of malware observed and stopped on your organization’s endpoints

Use cases

  • Isolate the events associated with a specific CB Analytics Alert, find all events that led up to or were initiated after malicious or unwanted actions occurred, or find the events that the sensor initiated that specifically denied or terminated unwanted behavior with an Enriched Events Search
  • Look for patterns and prevalence of unusual activity across all the organization’s endpoints with a Facet Search on Enriched Events

Alternative solutions for Endpoint Standard and Enterprise EDR customers:

Requirements

  • Endpoint Standard
  • All API calls require an API key with appropriate permissions (see Authentication below).

Common Headers

Most API calls require all three headers:

  1. X-Auth-Token: (required) your authentication token is: API Secret Key/API ID
    • Example: If Adam from Company Q has the API Secret Key ABCDEFGHIJKLMNOPQRSTUVWX and the API ID of 12345678, his corresponding X-Auth-Token HTTP header is ABCDEFGHIJKLMNOPQRSTUVWX/12345678
  2. Content-Type: application/json
  3. accept: application/json

Quick Start Instructions

Asynchronous Quick Start Instructions

All Enriched Event searches follow the pattern:

  1. Start a search. The request follows the structure POST /api/investigate/{version}/orgs/{org_key}/enriched_events/{job_type} where version and job_type are specified in the request
  2. The job_id is returned in the response and used to retrieve results and status of the search
  3. Check the status of the search using Get the Status of a Process Search. (This is not intuitive, but will work.)
  4. Get the results. The request uses the following pattern: GET /api/investigate/{version}/orgs/{org_key}/enriched_events/{job_type}/{job_id}

Note: job_type is one of aggregation_jobs, search_jobs, facet_jobs or detail_jobs

Guides & Resources

Authentication

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
    • for the category Search > Events > "org.search.events", allow permission to CREATE, READ, UPDATE, DELETE (or see each call below for individual requirements)
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)
  • API Route: exampleurl/v1/orgs/{org_key}/configs

Note: when you insert your org_key, you must also remove the { } brackets.

API calls

Note: Some calls use “v1” in the path, and others use “v2”. Using the wrong path will result in an error.

Start Aggregation Search on Enriched Events (v1)

Starts a search that groups results by the field supplied in the aggregation_field element of the path.

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

Path Schema

Field Definition Data Type Values
aggregation_field REQUIRED Field to aggregate on String device_id or process_sha256

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
exclusions Exclusions is a map that represents values that must not be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
fields A list of fields to include in the results, specify * to return all the default fields and add additional fields that are not returned by default Array
[ "*", "process_start_time" ]
Default: ["*"]
query Query in lucene syntax and/or including value searches. Either query or criteria/exclusion must be included. String N/A
rows Number of rows to request, can be paginated Long Default: 500
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "device_timestamp",
  "order": "asc"
}]
order supports asc or desc
start First row to use for pagination Long Default: 0
time_range Describes a time window to restrict the search to match using device_timestamp as the reference. Window will take priority over start and end if provided. Object
{
  "end": "2020-01-21T18:34:04Z",
  "start": "2020-01-18T18:34:04Z",
  "window": "-2w"
}
window: “-2w” where y=year, w=week, d=day, h=hour, m=minute, s=second

start: ISO 8601 timestamp

end: ISO 8601 timestamp

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",
  "sort": [
    {
      "field": "device_timestamp",
      "order": "asc"
    }
  ],
  "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 Search (v1)

Retrieves the aggregated enriched events search results for a given job_id. Results will be sorted based on the sort parameter used when starting the search. Confirm the search has completed by verifying that “contacted” equals “completed”.

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/{job_id}/results

Response

Code Description Content-Type Content
200 Successfully fetched aggregated event 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
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/dd30f255-88f0-4bb5-95d7-29dba1cd7980/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>12.34.5.6</accent></share><accent>:67</accent> (<share><accent>EXAMPLE.COM</accent></share>) from <share><accent>34.56.78.90</accent></share><accent>:68</accent>. The device was off the corporate network using the public address <accent>12.34.56.78</accent> (<accent>Win7x64.example.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
}

Start an Enriched Events Search (v2)

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

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

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
exclusions Exclusions is a map that represents values that must not be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
fields A list of fields to include in the results, specify * to return all the default fields and add additional fields that are not returned by default String
[ "*", "process_start_time" ]
Default: ["*"]
query Query in lucene syntax and/or including value searches. Either query or criteria/exclusion must be included. String N/A
rows Number of rows to request, can be paginated Long Default: 500
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "device_timestamp",
  "order": "asc"
}]
order supports asc or desc
start First row to use for pagination Long Default: 0
time_range Describes a time window to restrict the search to match using device_timestamp as the reference. Window will take priority over start and end if provided. Object
{
  "end": "2020-01-21T18:34:04Z",
  "start": "2020-01-18T18:34:04Z",
  "window": "-2w"
}
window: “-2w” where y=year, w=week, d=day, h=hour, m=minute, s=second

start: ISO 8601 timestamp

end: ISO 8601 timestamp

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-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/enriched_events/search_jobs

Body

{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "fields": ["*", "process_start_time"],
  "sort": [
    {
      "field": "device_timestamp",
      "order": "asc"
    }
  ],
  "rows": 10000,
  "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 the Enriched Events Search Status (v1)

Retrieves the status for an enriched events search request for a given job_id. Confirm the search has completed by verifying that “contacted” equals “completed”.

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/{job_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request 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/enriched_events/search_jobs/442f48e8-a4ce-4574-986f-5695b9e52dcc

Response

{
  "completed": 5,
  "contacted": 30
}

Retrieve Results for an Enriched Events Search (v2)

Retrieves the results of an enriched event search specified by a job_id. Results will be sorted based on the sort parameter used when starting the search. Confirm the job has completed by verifying that “contacted” equals “completed”.

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

Query Schema

Field Definition Data Type Values
start First row to use for pagination Integer Default: 0
rows Number of requested rows to fetch, used for paginating requested rows Integer Default: 10

Response

Code Description Content-Type Content
200 Successfully fetched 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

GET https://defense-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/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.example.com</accent>, located in United States). The operation was successful.",
            "event_id": "4c17fc3d3a2611ea8010ff74bcfa02b4",
            "event_type": "netconn",
            "index_class": "default",
            "legacy": true,
            "org_id": "ABCD1234",
            "parent_guid": "ABCD1234-0000a98f-000001fc-00000000-1d5cb7ef06c99d9",
            "parent_pid": 508,
            "partition_id": 0,
            "process_guid": "ABCD1234-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
}

Start a Facet Search on Enriched Events (v2)

Creates an enriched events facet search. A facet search provides statistics indicating the relative weighting of values for the specified terms.

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>"
        }
    ],
    "terms": {
        "fields": [
            "<string>"
        ],
        "rows": "<long>"
    },
    "time_range": {
        "end": "<string>",
        "start": "<string>",
        "window": "<string>"
    }
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
exclusions Exclusions is a map that represents values that must not be in the results. Either query or criteria/exclusion must be included. Object
{
  "process_name": [
    "chrome.exe"
  ]
}
Additional fields at Platform Search Fields
query Query in lucene syntax and/or including value searches. Either query or criteria/exclusion must be included. String N/A
ranges Allows grouping for properties that are ISO 8601 timestamps or numbers. Bucket size for ISO 8601 timestamps uses SOLR DateMathParser Array
[{
  "bucket_size": 100,
  "end": 100,
  "field": "process_duration",
  "start": 0
}]
or
[{
  "bucket_size": "+1DAY",
  "end": "2020-01-21T18:34:04Z",
  "field": "process_start_time",
  "start": "2020-01-18T18:34:04Z"
}]
terms The enriched events fields to facet and how many of the top entries to return. Object
{
  "fields": [
    "process_name"
  ],
  "rows": 100
}
Default: 100
time_range Describes a time window to restrict the search to match using device_timestamp as the reference. Window will take priority over start and end if provided. Object
{
  "end": "2020-01-21T18:34:04Z",
  "start": "2020-01-18T18:34:04Z",
  "window": "-2w"
}
window: “-2w” where y=year, w=week, d=day, h=hour, m=minute, s=second

start: ISO 8601 timestamp

end: ISO 8601 timestamp

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-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/enriched_events/facet_jobs

Body

{
  "criteria": {
  	"device_name": ["Win7x64"]
  },
  "query": "process_name:svchost.exe",
  "ranges": [
      {
          "bucket_size": "+12HOUR",
          "end": "2020-08-05T08:01:32.077Z",
          "field": "device_timestamp",
          "start": "2020-08-04T08:01:32.077Z"
      }
  ],
  "terms": {
    "fields": [
      "process_username"
    ],
    "rows": 100
  },
  "time_range": {
    "end": "2020-08-05T08:01:32.077Z",
    "start": "2020-08-04T08:01:32.077Z"
  }
}

Response

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

Retrieve Results for an Enriched Events Facet Search (v2)

Retrieves the enriched events facet results for a given job_id. Confirm the search has completed by verifying that “contacted” equals “completed”.

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

Query Schema

Field Definition Data Type Values
limit Maximum number of facets per category (i.e Any Process Search Fields listed in terms.fields) Integer Default: 100

Response

Code Description Content-Type Content
200 Successfully fetched 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-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/enriched_events/facet_jobs/505bf994-a335-426e-bd8c-b2e388f977f2/results?limit=100

Response

{
    "ranges": [
        {
            "start": "2020-08-04T08:01:32.077Z",
            "end": "2020-08-05T08:01:32.077Z",
            "bucket_size": "+1HOUR",
            "field": "device_timestamp",
            "values": [
                {
                    "total": 456,
                    "name": "2020-08-04T08:01:32.077Z"
                },
                {
                    "total": 374,
                    "name": "2020-08-04T20:01:32.077Z"
                }
            ]
        }
    ],
    "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
}

Request Details for Enriched Events (v2)

Note: This call is for preview only and may be subject to unannounced updates.

Initiates a request to retrieve detail fields for enriched events. The fields returned include all available information about the given event and information not returnable from the standard enriched events search. In the Platform Search Fields guide, these fields are marked with ENRICHED_EVENTS DETAILS . Fields marked with DETAILS can be returned on a Details Search on Processes. Use the returned job_id to request results for a details search.

RBAC Permissions Required

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

Request

POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/detail_jobs

Body

{
  "event_ids": [
    "<string>"
  ]
}

Body Schema

Field Definition Data Type Values
event_ids REQUIRED A list of event ids to fetch Array
[ "08ba6aedd75811ea920d3d9192a785d1", "68dcef34d74b11ea920d3d9192a785d1" ]


Max: 100 event_ids

Response

Code Description Content-Type Content
200 Successfully created details search job application/json View example response below
400 Invalid request 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/v2/orgs/ABCD1234/enriched_events/detail_jobs

Body

{
  "event_ids": [
    "1dac44ffe96111ea9759353269fbac39"
  ]
}

Response

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

Get the Enriched Events Detail Search Status (v2)

Note: This call is for preview only and may be subject to unannounced updates.

Retrieves the status for an enriched events detail request for a given job_id. Confirm the search has completed by verifying that “contacted” equals “completed”.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/detail_jobs/{job_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request 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/v2/orgs/ABCD1234/enriched_events/detail_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e

Response

{
  "completed": 5,
  "contacted": 30
}

Retrieve Results for an Enriched Event Detail Search (v2)

Note: This call is for preview only and may be subject to unannounced updates.

Retrieves the enriched event detail results for a given job_id. Confirm the search has completed by verifying that “contacted” equals “completed”.

RBAC Permissions Required

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

Request

GET {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/detail_jobs/{job_id}/results

Query Schema

Field Definition Data Type Values
start First row to use for pagination Integer Default: 0
rows Number of requested rows to fetch, used for paginating requested rows Integer Default: 10

Response

Code Description Content-Type Content
200 Successfully fetched enriched event details application/json View example response below
400 Invalid request 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/v2/orgs/ABCD1234/enriched_events/detail_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e/results

Response

{
  "completed": 30,
  "contacted": 30,
  "num_available": 500,
  "num_found": 1000,
  "results": [
    {
      "backend_timestamp": "2020-08-28T19:03:47.772Z",
      "childproc_cmdline": "pgrep -d   -- ^qemu(-kvm|:.{1,11})$",
      "childproc_cmdline_length": 35,
      "childproc_guid": "ABCD1234-0002b226-00005ca1-00000000-1d67d6dcd9d1760",
      "childproc_hash": [
          "af96a5c7c77082e33b2a10555a46f56bdff12344f8a289d6a7a3118d17a63d95"
      ],
      "childproc_name": "/usr/bin/pgrep",
      "childproc_pid": 23713,
      "childproc_publisher_state": [
          "FILE_SIGNATURE_STATE_NOT_SIGNED"
      ],
      "childproc_reputation": "NOT_LISTED",
      "device_external_ip": "34.56.78.90",
      "device_group_id": 0,
      "device_id": 176678,
      "device_internal_ip": "12.34.56.78",
      "device_location": "UNKNOWN",
      "device_name": "devr-dev",
      "device_os": "LINUX",
      "device_os_version": "CentOS 7.6-1810",
      "device_policy": "sm-restrictive",
      "device_policy_id": 11200,
      "device_target_priority": "MEDIUM",
      "device_timestamp": "2020-08-28T19:02:40.854Z",
      "document_guid": "pU7-5mL1RzGNOhtNl6EJYQ",
      "enriched": true,
      "enriched_event_type": "CREATE_PROCESS",
      "event_description": "The application \"<share><link hash=\"5975d972eea6b1c53ef9a69452797439ed5bf63fae72e1780761ea1c2cb6976a\">/usr/bin/bash</link></share>\" invoked the application \"<share><link hash=\"af96a5c7c77082e33b2a10555a46f56bdff12344f8a289d6a7a3118d17a63d95\">/usr/bin/pgrep</link></share>\". ",
      "event_id": "1dac44ffe96111ea9759353269fbac39",
      "event_type": "childproc",
      "ingress_time": 1598641411416,
      "legacy": true,
      "org_id": "ABCD1234",
      "parent_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba74c00",
      "parent_hash": [
          "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85"
      ],
      "parent_name": "/usr/lib/systemd/systemd",
      "parent_pid": 1,
      "parent_publisher_state": [
          "FILE_SIGNATURE_STATE_NOT_SIGNED"
      ],
      "parent_reputation": "NOT_LISTED",
      "process_cmdline": [
          "/bin/bash /usr/sbin/ksmtuned"
      ],
      "process_cmdline_length": [
          28
      ],
      "process_guid": "ABCD1234-0002b226-00001615-00000000-1d6225bbba74c00",
      "process_hash": [
          "285044ad8f8b9322d0cc5e929e2cc18c",
          "5975d972eea6b1c53ef9a69452797439ed5bf63fae72e1780761ea1c2cb6976a"
      ],
      "process_name": "/usr/bin/bash",
      "process_pid": [
          5653
      ],
      "process_publisher_state": [
          "FILE_SIGNATURE_STATE_NOT_SIGNED"
      ],
      "process_reputation": "NOT_LISTED",
      "process_sha256": "5975d972eea6b1c53ef9a69452797439ed5bf63fae72e1780761ea1c2cb6976a",
      "process_start_time": "2020-05-04T21:34:03.968Z",
      "process_username": [
          "root"
      ],
      "ttp": [
          "RUN_SYSTEM_APP",
          "RUN_UNKNOWN_APP",
          "UNKNOWN_APP"
      ]
    }
  ]
}

Troubleshooting & FAQ

What is a “Value Search”?

  • Platform Search supports either field:value syntax or what is called ‘value searches’ where the field name is not included e.g. where process_name:chrome.exe is a well-specified search query, a search merely for chrome.exe can return all those results as well as results where chrome.exe shows up in other fields that you didn’t have to know to specify.

Why am I getting an error?

  • See the table below for tips on troubleshooting Errors
Error Code Reason For Error Suggested Fix
404 The requested resource could not be found Check that the correct API version is being used. Enriched event calls have a mix of v1 and v2.
Last modified on October 7, 2020