Enriched Events Search API

This API will be deactivated on July 31, 2024.

The Enriched Events Search API has been deprecated and replaced by the platform Observations Search API here.

More information on Observations and how to migrate to the Observations Search API can be found here.

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).

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/api/investigate/v1/orgs/{org_key}/enriched_events/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Search > Events > org.search.events, allow permission to CREATE, READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/api/investigate/v1/orgs/{org_key}/enriched_events/

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Search:org.Events, allow permission to CREATE, READ

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


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. Get the results and status. The request uses the following pattern: GET /api/investigate/{version}/orgs/{org_key}/enriched_events/{job_type}/{job_id}/results. Results may be available immediately but will be incomplete until the job finishes. The job may take longer depending on the complexity and search space.
  4. To efficiently check for the completion of a search job fetch the results with the following query ?start=0&rows=0 otherwise use the results endpoint as described for your job type below. Please add a time.sleep(0.5) or exponential backoff between each status check.
  5. The job will be complete when contacted == completed in the response however during high usage a searcher may fail leaving a difference of 1. To prevent an infinite loop, ensure you add a timeout of 3 mins as a job’s maximum active time is limited to 3 mins.
  6. The results will contain a num_found and num_available field indicating how many results were found and how many of those are able to be paginated. A search matching more results than will be returned through pagination will report num_found greater than num_available; note that this limitation occurs to prevent performance degradation with searches matching a large number of events or processes. In order to return more of the matching results, you can apply a smaller time range to your search request, or use additional or more specific criteria, then make as many additional of these subset searches as needed to fetch the entire num_found from your original search.
Note: `job_type` is one of `aggregation_jobs`, `search_jobs`, `facet_jobs` or `detail_jobs`

Guides & Resources

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.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:create N/A - included in permission name Prod UK and AWS GovCloud (US)

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 UTC timestamp

end: ISO 8601 UTC 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”.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/api/investigate/v1/orgs/{org_key}/enriched_events/aggregation_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
Max: 10k

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?rows=10000

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.

An alternative to execute searches and get the results in a zipped csv file is the Event Export functionality with api_resource = ENRICHED_EVENTS which leverages the Job Service API.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:create N/A - included in permission name Prod UK and AWS GovCloud (US)

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 UTC timestamp

end: ISO 8601 UTC 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)

Job ID endpoint no longer supported.


The jobs status is available in the result by comparing contacted to completed.

Use the following query ?start=0&rows=0 to efficiently check for completion. See example below:

GET {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/search_jobs/{job_id}/results?start=0&rows=0

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”.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:read N/A - included in permission name Prod UK and AWS GovCloud (US)

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
Max: 10k

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=10000

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.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:create N/A - included in permission name Prod UK and AWS GovCloud (US)

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 UTC timestamps or numbers. Bucket size for ISO 8601 UTC 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 UTC timestamp

end: ISO 8601 UTC 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”.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:read N/A - included in permission name Prod UK and AWS GovCloud (US)

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)

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.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:create N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

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

Body 

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

{
  "alert_id": "<string>"
}

Body Schema

Note: Either event_ids or alert_id is required however only one can be specified.
Field Definition Data Type Values
event_ids A list of event ids to fetch Array 
[ "08ba6aedd75811ea920d3d9192a785d1", "68dcef34d74b11ea920d3d9192a785d1" ]


Max: 100 event_ids
alert_id An alert id to fetch associated enriched events String N/A

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)

Job ID endpoint no longer supported.


The jobs status is available in the result by comparing contacted to completed.

Use the following request to check for completion:

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

Retrieve Results for an Enriched Event Detail Search (v2)

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

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events:create N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

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

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

Why am I not getting more than 10 results?

  • Ensure you specified rows as a query parameter when getting the results. The maximum rows that can be returned for enriched events is 10k.
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.

Give Feedback

New survey coming soon!


Last modified on July 24, 2023