Processes Search API

Overview

This API lets you search through all the data that is reported by your organization’s sensors to find one or more processes based on specific criteria you set.

With visibility across your fleet of monitored endpoints, you can identify applications that are acting abnormally and over time, cull the outliers from the total observed process activity, and retroactively identify the origination point for attacks that previously escaped notice. You can also:

  • Test out a variety of approaches to querying your organization’s historical data before adding that query to a Watchlist
  • Get deep visibility into the security context of Windows processes including elevation, mandatory access control integrity level and privileges
  • Search across all Enterprise EDR Watchlist-hitting activity in your organization to hone in on patterns and outlier behavior

Use cases

  • Find the process that was identified in an Alert with a Process Search
  • Find processes that match targeted behavioral characteristics identified in Carbon Black or third-party threat intelligence reports with Get Report Hits
  • Find more details about processes that were potentially involved in malicious activity identified elsewhere with a Details Search on Processes
  • To get filtering terms or prevalent values, call /facet_jobs followed by /results on the /facet_jobs/ call with job_id in the request URI

Alternative solutions:

Requirements

  • Endpoint Standard or Enterprise EDR product
  • All API calls require an API key with appropriate permissions, see Authentication for details

Guides and Resources

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.
  • Processes: {cbc-hostname}/api/investigate/v1/orgs/{org_key}/processes/
  • Events: {cbc-hostname}/api/investigate/v1/orgs/{org_key}/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, UPDATE, DELETE

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.
  • Processes: {cbc-hostname}/api/investigate/v1/orgs/{org_key}/processes/
  • Events: {cbc-hostname}/api/investigate/v1/orgs/{org_key}/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, UPDATE, DELETE

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

Many Platform Search functions are asynchronous and require a sequence of calls to start the process, check the status and retrieve the results. The following is an example of typical use:

  1. Start a search. The request follows the structure POST /api/investigate/v2/orgs/{org_key}/processes/{job_type} where job_type is 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/v2/orgs/{org_key}/processes/{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 'search_jobs', 'facet_jobs', 'detail_jobs' or 'summary_jobs'.

Process Search Pagination

Process searches aggregate events to construct the process models. The ‘approximate_unaggregated’ and ‘num_aggregated’ properties in the response provide greater insight into the processes that matched your search.

approximate_unaggregated indicates the number of matching events used to construct the processes which will be equivalent to num_found while the search finishes aggregating otherwise num_found may equal num_aggregated.

num_aggregated represents the processes that were constructed from the events which will be equal or greater than num_available. To retrieve more of the num_aggregated results adjust your criteria and/or time range, additionally if you set collapse to true in the process search creation then this will compress redundant events allowing for more results to be retrieved.

Note: If you create a broad or large time range search then Process Search Jobs can be cancelled using Cancel a Process Search.

API calls

This API has three types of calls:

  • Calls for Processes - searches process data
  • Calls for Events - searches event data
  • Calls for Enterprise EDR - scans for hits against watchlists and reports
Note: Some calls use 'v1' in the path, and others use 'v2'. Using the wrong path will result in an error.

Calls for Processes

The following calls search on and return processes.

Process Search Suggestions (v2)

Returns suggestions for a process search selected from fields and values as reported in the organization’s system. Will return values for the specified field if at least one character follows the colon. Returns null if no characters follow the colon.

Note: This v2 endpoint replaced the previous v1 endpoint in April 2023.

Documentation for the deprecated API is here.

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}/processes/search_suggestions

Query Schema

Field Definition Data Type Values
suggest.q REQUIRED Query to generate suggestions for String N/A
suggest.count Number of suggestions to return Integer Default: 50

Response

Code Description Content-Type Content
200 Successfully suggested process search fields 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/processes/search_suggestions?suggest.q=process_cmd&suggest.count=1

Response 

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

Process Search Validation (v2)

Validates a given process query and potentially gives suggestions on how to fix invalid queries.

Note: This v2 POST endpoint replaced the previous v1 GET endpoint in April 2023. This resolves issues encountered due to the length limit for the GET call.

Documentation for the deprecated API is here.

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

POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/processes/search_validation


Request Body - application/json 

{
  "query": "<string>"
}

Body Schema

Field Definition Data Type Values
query The process search query to be validated String N/A

Response

Code Description Content-Type Content
200 Successfully validated 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/v2/orgs/ABCD1234/processes/search_validation

Response 

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

Get Time Limits for Available Data (v1)

Returns the minimum and maximum times at which events were reported by any sensor in your organization.

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}/processes/limits

Response

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

Example

Request

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/limits

Response

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

Get a List of All Available Process Result Sets (v1)

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 created search jobs. query_id is the previous name for the newer job_id.

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}/processes/search_jobs

Response

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

Example

Request

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/search_jobs

Response 

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

Start a Process Search (v2)

Creates a process 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 = PROCESSES 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}/processes/search_jobs

Body 

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

Body Schema

Field Definition Data Type Values
collapse Set to false if you want to prevent search engine from attempting to collapse redundant results together during initial phase of search. Useful for obtaining exact and consistent counts of unaggregated results. boolean Default: false
collapse_field The field(s) to collapse the results by when searching. The search will only return one result per value for the specified field. Array 
["device_id"]


Supported: device_id
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. If additional fields are required, consider using the Details Job which is more performant. If needed by the use case, additional fields can be named in this list. 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 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/v2/orgs/ABCD1234/processes/search_jobs

Body 

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

Response 

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

Get the Status of a Process Search (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}/processes/search_jobs/{job_id}/results?start=0&rows=0

Retrieve Results for a Process Search (v2)

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

Note: Use 'num_aggregated' instead of 'num_found' to determine if there are more processes which need a refined search or time range to fetch. 'approximate_unaggregated' and 'num_found' represent the number of matching events which are being aggregated into processes.

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}/processes/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: 100

Response

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

Example

Request

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

Response 

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

Cancel a Process Search (v1)

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

API Permissions Required

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

Request

DELETE {cbc-hostname}/api/investigate/v1/orgs/{org_key}/processes/search_jobs/{job_id}

Response

Code Description Content-Type Content
204 Successfully deleted a process search N/A No Content
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

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

Response

No content

Start a Facet Search on Processes (v2)

Initiates a process facet search which generates statistics indicating the relative weighting of values for the specified terms. The results for the search may be requested using the job_id returned.

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}/processes/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 process 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 process facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/processes/facet_jobs

Body 

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

Response 

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

Retrieve Results for a Process Facets Search (v2)

Retrieves the process 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}/processes/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 processes facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

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

Response 

{
    "ranges": [
        {
            "start": 0,
            "end": 10,
            "bucket_size": 5,
            "field": "netconn_count",
            "values": [
               {
                   "total": 10128,
                   "name": "0"
               },
               {
                   "total": 5,
                   "name": "5"
               }
            ]
        }
    ],
    "terms": [
        {
            "values": [
                {
                    "total": 10701,
                    "id": "NT AUTHORITY\\NETWORK SERVICE",
                    "name": "NT AUTHORITY\\NETWORK SERVICE"
                }
            ],
            "field": "process_username"
        }
    ],
    "num_found": 20818,
    "contacted": 6,
    "completed": 6
}

Request Details of Processes (v2)

Creates a process detail job. The details will include all available information about the given process including information that’s not returnable from the standard Process Search call. These fields are annotated with DETAILS on Platform Search Fields. The results for the details search job may be requested using the job_id returned.

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}/processes/detail_jobs

Body 

{
  "process_guids": [
    "<string>"
  ],
  "limited": boolean
}

Body Schema

Field Definition Data Type Values
process_guids REQUIRED A list of process guids to fetch Array 
[ "ABCD1234-0000a98f-0000051c-00000000-1d5cb7ed061e7ef", "ABCD1234-0000a98f-000001fc-00000000-1d5cb7eca37b799" ]
Max: 100 process_guids
limited If set to true, the request will only populate process metadata fields that don’t change over time (parent_cmdline, for example). Fields that can change over the life of the process may be incomplete. Users should see a significant improvement in the timing of these API calls when set to true. Defaults to false. Boolean true, false

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

POST https://defense-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/processes/detail_jobs

Body 

{
  "process_guids": [
    "ABCD1234-0002b226-00001615-00000000-1d6225bbba75e5e"
  ],
  "limited": false
}

Response

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

Get the Status of a Process Detail Search (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}/processes/detail_jobs/{job_id}/results

Retrieve Results for a Process Detail Search (v2)

Retrieves the process 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 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}/processes/detail_jobs/{job_id}/results

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/processes/detail_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e/results

Response

{
  "results": [
    {
      "backend_timestamp": "2023-05-31T08:33:30.791Z",
      "childproc_count": 0,
      "crossproc_count": 12752,
      "device_external_ip": "66.170.99.2",
      "device_group_id": 0,
      "device_id": 18458384,
      "device_installed_by": "Administrator",
      "device_internal_ip": "10.193.3.105",
      "device_location": "UNKNOWN",
      "device_name": "test",
      "device_os": "WINDOWS",
      "device_os_version": "Windows Server 2016 x64",
      "device_policy": "standard",
      "device_policy_id": 19888416,
      "device_sensor_version": "3.9.0.2347",
      "device_target_priority": "MEDIUM",
      "device_timestamp": "2023-05-31T08:30:40.131Z",
      "document_guid": "anjYgA7zTJmuqX69yv7HkQ",
      "filemod_count": 0,
      "ingress_time": 1685521983027,
      "modload_count": 0,
      "netconn_count": 3,
      "org_id": "ABCD1234",
      "parent_cmdline": "C:\\Windows\\system32\\services.exe",
      "parent_cmdline_length": 32,
      "parent_effective_reputation": "LOCAL_WHITE",
      "parent_effective_reputation_source": "IGNORE",
      "parent_guid": "DJ4TYR8E9P-0119a710-0000027c-00000000-1d9735eabf24829",
      "parent_hash": [
        "48d5695e7610e7a742e403b2c37664d961e466c10e4ffae07c8ab6b5be5f7bf8",
        "9a3b47cd17283b299311013ad3d21d26"
      ],
      "parent_issuer": [
        "Microsoft Windows Production PCA 2011"
      ],
      "parent_name": "c:\\windows\\system32\\services.exe",
      "parent_pid": 636,
      "parent_publisher": [
        "Microsoft Windows Publisher"
      ],
      "parent_publisher_state": [
        "FILE_SIGNATURE_STATE_OS",
        "FILE_SIGNATURE_STATE_SIGNED",
        "FILE_SIGNATURE_STATE_TRUSTED",
        "FILE_SIGNATURE_STATE_VERIFIED"
      ],
      "parent_reputation": "NOT_LISTED",
      "process_cmdline": [
        "C:\\Windows\\system32\\svchost.exe -k RPCSS"
      ],
      "process_cmdline_length": [
        40
      ],
      "process_company_name": "Microsoft Corporation",
      "process_effective_reputation": "TRUSTED_WHITE_LIST",
      "process_effective_reputation_source": "IGNORE",
      "process_elevated": true,
      "process_file_description": "Host Process for Windows Services",
      "process_guid": "DJ4TYR8E9P-0119a710-00000328-00000000-1d9735eac88ef38",
      "process_hash": [
        "36f670d89040709013f6a460176767ec",
        "438b6ccd84f4dd32d9684ed7d58fd7d1e5a75fe3f3d12ab6c788e6bb0ffad5e7"
      ],
      "process_integrity_level": "SYSTEM",
      "process_internal_name": "svchost.exe",
      "process_issuer": [
        "Microsoft Windows Production PCA 2011"
      ],
      "process_name": "c:\\windows\\system32\\svchost.exe",
      "process_original_filename": "svchost.exe",
      "process_pid": [
        808
      ],
      "process_privileges": [
        "SeChangeNotifyPrivilege",
        "SeCreateGlobalPrivilege",
        "SeImpersonatePrivilege"
      ],
      "process_product_name": "Microsoft® Windows® Operating System",
      "process_product_version": "10.0.14393.0",
      "process_publisher": [
        "Microsoft Windows Publisher"
      ],
      "process_publisher_state": [
        "FILE_SIGNATURE_STATE_OS",
        "FILE_SIGNATURE_STATE_SIGNED",
        "FILE_SIGNATURE_STATE_TRUSTED",
        "FILE_SIGNATURE_STATE_VERIFIED"
      ],
      "process_reputation": "TRUSTED_WHITE_LIST",
      "process_service_name": [
        "rpcss"
      ],
      "process_sha256": "438b6ccd84f4dd32d9684ed7d58fd7d1e5a75fe3f3d12ab6c788e6bb0ffad5e7",
      "process_start_time": "2023-04-20T08:04:04.291Z",
      "process_username": [
        "NT AUTHORITY\\NETWORK SERVICE"
      ],
      "regmod_count": 0,
      "scriptload_count": 0
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "approximate_unaggregated": 1574,
  "num_aggregated": 1574,
  "contacted": 7,
  "completed": 7
}

Start a Process Summary Search (v2)

Creates a process summary job. The summary will include information about the given process including its children, parents, and siblings. The results for the search job may be requested using the job_id returned.

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}/processes/summary_jobs

Body 

{
  "parent_guid": "<string>",
  "process_guid": "<string>",
  "time_range": {
      "end": "<string>",
      "start": "<string>",
      "window": "<string>"
  }
}

Body Schema

Field Definition Data Type Values
process_guid REQUIRED The global unique identifier for a process String N/A
parent_guid The global unique identifier for the parent of the specified process_guid String N/A
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 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

POST https://defense-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/processes/summary_jobs

Body

{
  "parent_guid": "ABCD1234-0000a98f-000001fc-00000000-1d5cb7eca37b799",
  "process_guid": "ABCD1234-0000a98f-0000051c-00000000-1d5cb7ed061e7ef",
  "time_range": {
    "window": "-2w"
  }
}

Response

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

Get the Status of Process Summary Search (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}/processes/summary_jobs/{job_id}/results

Retrieve Results for a Process Summary or Tree Search (v2)

Retrieves the process summary results for a given job_id in summary or tree format. Most callers will prefer the summary format, but you may request the tree format for convenience of building user interfaces. 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}/processes/summary_jobs/{job_id}/results

Query Schema

Field Definition Data Type Values
format The format for the summary to be returned String Default: summary
Options: summary or tree

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/processes/summary_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e/results?format=summary

Response

{
  "completed": 30,
  "contacted": 30,
  "exception": "string",
  "summary": {
    "children": [],
    "parent": {
        "_process_filename": "systemd",
        "backend_timestamp": "2020-08-28T19:12:07.989Z",
        "childproc_count": 0,
        "crossproc_count": 0,
        "device_external_ip": "34.56.78.90",
        "device_group_id": 0,
        "device_id": 176678,
        "device_name": "devr-dev",
        "device_os": "LINUX",
        "device_policy": "sm-restrictive",
        "device_policy_id": 11200,
        "device_timestamp": "2020-08-28T19:10:02.123Z",
        "filemod_count": 0,
        "has_children": true,
        "hits": false,
        "ingress_time": 1598641901273,
        "modload_count": 0,
        "netconn_count": 0,
        "org_id": "ABCD1234",
        "process_effective_reputation": "NOT_LISTED",
        "process_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba75e43",
        "process_hash": [
            "e4b9902024ac32b3ca37f6b4c9b841e8",
            "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85"
        ],
        "process_name": "/usr/lib/systemd/systemd",
        "process_pid": [
            1
        ],
        "process_reputation": "NOT_LISTED",
        "process_start_time": "2020-05-04T21:34:03.968Z",
        "regmod_count": 0,
        "scriptload_count": 0
    },
    "process": {
      "_process_filename": "bash",
      "backend_timestamp": "2020-08-28T19:16:11.959Z",
      "childproc_count": 333580,
      "crossproc_count": 0,
      "device_external_ip": "34.56.78.90",
      "device_group_id": 0,
      "device_id": 176678,
      "device_name": "devr-dev",
      "device_os": "LINUX",
      "device_policy": "sm-restrictive",
      "device_policy_id": 11200,
      "device_timestamp": "2020-08-28T19:14:41.231Z",
      "filemod_count": 0,
      "ingress_time": 1598642141411,
      "modload_count": 0,
      "netconn_count": 0,
      "org_id": "ABCD1234",
      "parent_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba75e43",
      "parent_hash": [
          "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85",
          "e4b9902024ac32b3ca37f6b4c9b841e8"
      ],
      "parent_name": "/usr/lib/systemd/systemd",
      "parent_pid": 1,
      "process_cmdline": [
          "/bin/bash /usr/sbin/ksmtuned"
      ],
      "process_effective_reputation": "NOT_LISTED",
      "process_guid": "ABCD1234-0002b226-00001615-00000000-1d6225bbba75e5e",
      "process_hash": [
          "285044ad8f8b9322d0cc5e929e2cc18c",
          "5975d972eea6b1c53ef9a69452797439ed5bf63fae72e1780761ea1c2cb6976a"
      ],
      "process_name": "/usr/bin/bash",
      "process_pid": [
          5653,
          16139
      ],
      "process_reputation": "NOT_LISTED",
      "process_start_time": "2020-05-04T21:34:03.968Z",
      "process_username": [
          "root"
      ],
      "regmod_count": 0,
      "scriptload_count": 0
    },
    "siblings": [
      {
        "_process_filename": "nm-dispatcher",
        "backend_timestamp": "2020-08-19T20:55:33.446Z",
        "childproc_count": 1,
        "crossproc_count": 0,
        "device_external_ip": "34.56.78.90",
        "device_group_id": 0,
        "device_id": 176678,
        "device_name": "devr-dev",
        "device_os": "LINUX",
        "device_policy": "sm-restrictive",
        "device_policy_id": 11200,
        "device_timestamp": "2020-08-19T20:54:44.980Z",
        "filemod_count": 0,
        "has_children": true,
        "hits": false,
        "ingress_time": 1597870506825,
        "modload_count": 0,
        "netconn_count": 0,
        "org_id": "ABCD1234",
        "parent_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba75e43",
        "parent_hash": [
            "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85",
            "e4b9902024ac32b3ca37f6b4c9b841e8"
        ],
        "parent_name": "/usr/lib/systemd/systemd",
        "parent_pid": 1,
        "process_cmdline": [
            "/usr/libexec/nm-dispatcher"
        ],
        "process_effective_reputation": "NOT_LISTED",
        "process_guid": "ABCD1234-0002b226-00005742-00000000-1d6766af7bedb39",
        "process_hash": [
            "04b2450579a663c964f3960cd0cf93a8",
            "2206d95e0a435aadad6c84b5bce370d076137efecf6adbbf6feddbe0515fb17e"
        ],
        "process_name": "/usr/libexec/nm-dispatcher",
        "process_pid": [
            22338
        ],
        "process_reputation": "NOT_LISTED",
        "process_start_time": "2020-08-19T20:54:44.909Z",
        "process_username": [
            "root"
        ],
        "regmod_count": 0,
        "scriptload_count": 0
      }
    ]
  }
}

Request

GET https://defense-eap01.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/processes/summary_jobs/6b414c3e-c664-45ea-bb69-3aabf4430f7e/results?format=tree

Response

{
  "completed": 30,
  "contacted": 30,
  "exception": "string",
  "tree": {
    "_process_filename": "systemd",
    "backend_timestamp": "2020-08-28T19:12:07.989Z",
    "childproc_count": 1,
    "children": [
      {
        "_process_filename": "bash",
        "backend_timestamp": "2020-08-28T19:16:11.959Z",
        "childproc_count": 333580,
        "crossproc_count": 0,
        "device_external_ip": "34.56.78.90",
        "device_group_id": 0,
        "device_id": 176678,
        "device_name": "devr-dev",
        "device_os": "LINUX",
        "device_policy": "sm-restrictive",
        "device_policy_id": 11200,
        "device_timestamp": "2020-08-28T19:14:41.231Z",
        "filemod_count": 0,
        "ingress_time": 1598642141411,
        "modload_count": 0,
        "netconn_count": 0,
        "org_id": "ABCD1234",
        "parent_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba75e43",
        "parent_hash": [
            "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85",
            "e4b9902024ac32b3ca37f6b4c9b841e8"
        ],
        "parent_name": "/usr/lib/systemd/systemd",
        "parent_pid": 1,
        "process_cmdline": [
            "/bin/bash /usr/sbin/ksmtuned"
        ],
        "process_effective_reputation": "NOT_LISTED",
        "process_guid": "ABCD1234-0002b226-00001615-00000000-1d6225bbba75e5e",
        "process_hash": [
            "285044ad8f8b9322d0cc5e929e2cc18c",
            "5975d972eea6b1c53ef9a69452797439ed5bf63fae72e1780761ea1c2cb6976a"
        ],
        "process_name": "/usr/bin/bash",
        "process_pid": [
            5653,
            16139
        ],
        "process_reputation": "NOT_LISTED",
        "process_start_time": "2020-05-04T21:34:03.968Z",
        "process_username": [
            "root"
        ],
        "regmod_count": 0,
        "scriptload_count": 0
      }
    ],
    "crossproc_count": 0,
    "device_external_ip": "34.56.78.90",
    "device_group_id": 0,
    "device_id": 176678,
    "device_name": "devr-dev",
    "device_os": "LINUX",
    "device_policy": "sm-restrictive",
    "device_policy_id": 11200,
    "device_timestamp": "2020-08-28T19:10:02.123Z",
    "filemod_count": 0,
    "has_children": true,
    "hits": false,
    "ingress_time": 1598641901273,
    "modload_count": 0,
    "netconn_count": 0,
    "org_id": "ABCD1234",
    "process_effective_reputation": "NOT_LISTED",
    "process_guid": "ABCD1234-0002b226-00000001-00000000-1d6225bbba75e43",
    "process_hash": [
        "e4b9902024ac32b3ca37f6b4c9b841e8",
        "81b37dcb0321108e564d528df827580153ab64005be3bcafd5162e9e7e707e85"
    ],
    "process_name": "/usr/lib/systemd/systemd",
    "process_pid": [
        1
    ],
    "process_reputation": "NOT_LISTED",
    "process_start_time": "2020-05-04T21:34:03.968Z",
    "regmod_count": 0,
    "scriptload_count": 0
  }
}

Calls for Events

Events search in the Processes Search API gives access to all events reported for a particular process on one endpoint.

Get Suggestions for Event Searching (v1)

Returns suggestions for an event search selected from fields from the Platform Search Fields. Will return field names if the “suggest.q” parameter does not yet contain a colon and will return no suggestion otherwise. This call does not support value suggestions.

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}/events/search_suggestions

Query Schema

Field Definition Data Type Values
suggest.q REQUIRED Query to generate suggestions for String N/A
suggest.count Number of suggestions to return Integer Default: 50

Response

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

Example

Request

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

Response

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

Get Validation for Event Search (v1)

Validates a given event query and potentially gives suggestions on how to fix invalid queries.

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}/events/search_validation

Query Schema

Field Definition Data Type Values
q REQUIRED Keeping this parameter as *:* allows you to query everything String N/A
cb.min_backend_timestamp Start time for the query Integer Epoch timestamp in milliseconds
Default: 0
cb.max_backend_timestamp End time for the query Integer Epoch timestamp in milliseconds

Response

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

Valid Request

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

Response

{
    "valid": true
}

Invalid Request

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

Response 

{
    "invalid_message": "org.apache.solr.common.SolrException: undefined field alertzzzzz_id",
    "valid": false,
    "invalid_trigger_offset": 0
}

Get Events Associated with a Given Process (v2)

Fetch the events associated with a given process. These events are often more complete than the enriched events but, unlike the enriched event searches, must be limited to one process at a time.

Note: This call reports its progress as soon as it can and continues to enumerate process events in the background. To receive the full results, you must resubmit the request until 'processed_segments' is equal to 'total_segments'.

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

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

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

Body 

{
    "criteria": "<object>",
    "exclusions": "<object>",
    "fields": ["<string>", "<string>"],
    "query": "<string>",
    "rows": <long>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "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 fetched 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/events/ABCD1234-0000a98f-0000034c-00000000-1d5cb7ef5152b42/_search

Body 

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

Response 

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

Get Events Facet Associated with a Process (v2)

Get facets for the events associated with the specified process. A facet provides statistics indicating the relative weighting of values for the specified terms.

Note: This is an asynchronous request, you must resubmit the request until 'processed_segments' is equal to 'total_segments' in order to receive the full results.

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

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

Body 

{
    "criteria": "<object>",
    "exclusions": "<object>",
    "query": "<string>",
    "ranges": [
        {
            "bucket_size": "<object>",
            "end": "<object>",
            "field": "<string>",
            "start": "<object>"
        }
    ],
    "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 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 fetched event facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

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

Body 

{
  "query": "*:*",
  "ranges": [
      {
          "bucket_size": "+12HOUR",
          "end": "2020-08-31T11:19:37Z",
          "field": "device_timestamp",
          "start": "2020-08-29T00:00:00Z"
      }
  ],
  "terms": {
    "fields": [
      "event_type"
    ],
    "rows": 10
  },
  "time_range": {
    "end": "2020-08-31T11:19:37Z",
    "start": "2020-08-29T00:00:00Z"
  }
}

Response 

{
    "ranges": [
        {
            "start": "2020-08-29T00:00:00Z",
            "end": "2020-08-31T12:00:00Z",
            "bucket_size": "+12HOUR",
            "field": "device_timestamp",
            "values": [
                {
                    "total": 9850,
                    "name": "2020-08-29T00:00:00Z"
                },
                {
                    "total": 9346,
                    "name": "2020-08-29T12:00:00Z"
                },
                {
                    "total": 9910,
                    "name": "2020-08-30T00:00:00Z"
                },
                {
                    "total": 8581,
                    "name": "2020-08-30T12:00:00Z"
                },
                {
                    "total": 8716,
                    "name": "2020-08-31T00:00:00Z"
                }
            ]
        }
    ],
    "terms": [
        {
            "values": [
                {
                    "total": 41517,
                    "id": "netconn",
                    "name": "netconn"
                },
                {
                    "total": 4829,
                    "id": "filemod",
                    "name": "filemod"
                },
                {
                    "total": 31,
                    "id": "crossproc",
                    "name": "crossproc"
                },
                {
                    "total": 26,
                    "id": "childproc",
                    "name": "childproc"
                }
            ],
            "field": "event_type"
        }
    ],
    "num_found": 46403,
    "total_segments": 23385,
    "processed_segments": 23385
}

Calls using Enterprise EDR Watchlist Features

These Process Search API calls are only available to Enterprise EDR customers.

Evaluate Processes for a Watchlist (v1)

Instructs the Carbon Black Cloud to look for “hits” across all processes reported for the organization’s endpoints within the time range for the given watchlist, report and IOC. Watchlist hits will be available in subsequent search results asynchronously and are not guaranteed to be visible directly after this call.

API Permissions Required

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

Request

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

Request Body 

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

Request Body Schema

Field Definition Data Type Values
watchlist_id REQUIRED Watchlist ID String N/A
report_id REQUIRED Report ID String N/A
ioc_id Indicator of compromise ID String N/A
cb.min_backend_timestamp Start time for the query Integer Epoch timestamp in milliseconds
Default: 0
cb.max_backend_timestamp End time for the query Integer Epoch timestamp in milliseconds

Response

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

Example

Request

POST https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/processes/watchlist_evaluation

Body 

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

Response

No content

Get Report Hits (v1)

Fetches report hits associated with a single process. This includes both ingress and query hits that are associated with the organization’s subscribed watchlists.

Request

GET {cbc-hostname}/api/investigate/v1/orgs/{org_key}/report_hits

Query Schema

Field Definition Data Type Values
process_guid REQUIRED Process GUID for which to get report hits String N/A
rows Number of report hits to get. Integer Default: 10

Response

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

Example

Request

GET https://defense-eap01.conferdeploy.net/api/investigate/v1/orgs/ABCD1234/report_hits?process_guid=ABCD1234-0000a98f-000013c8-00000000-1d5c4bc2bf4b39d&rows=1

Response 

{
    "report_hits": {
      "lryC1EGShaTsb4bjxjLTQ-ipv4_iocs": [
        {
          "backend_timestamp": "2020-08-28T08:36:11.745Z",
          "device_timestamp": "2020-08-28T08:34:39.437Z",
          "hit_document_guids": [
              "2ybSlFnGQeCRP5Srn2WfqA"
          ],
          "iocs_field": "netconn_ipv4",
          "iocs_hit": "13.107.4.50",
          "iocs_id": "demo-ipv4",
          "report_id": "lryC1EGShaTsb4bjxjLTQ-ipv4_iocs",
          "report_link": "https://example.com",
          "report_severity": 5,
          "report_timestamp": "2020-08-02T10:56:39.437Z",
          "report_title": "IPV4 IOCs",
          "report_watchlists": [
              {
                  "alert": true,
                  "id": "7hpd1usTWaNG5lHfGmjVg",
                  "name": "Demo"
              }
          ]
        }
      ]
    }
  }
}

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.

What is a “hit”?

  • Enterprise EDR watchlists will report a “hit” on any process that matches on a specific IOC from one of the organization’s watchlists. These hits will be reported as process search results where the watchlist_hit field is included
  • These are separate from Alerts which are optionally reported for any watchlist hit generated by a subscribed Watchlist where “Enable Watchlist Alerts” has been set.

Why don’t I get matches on the Events APIs when I search by alert_id until a few minutes after I find the Alert?

  • The Events stream is not annotated until after the Carbon Black Cloud backend has issued an Alert, so it takes time for the Events service to process the data that identifies Events associated with Alerts. Try using a query filter that ends at least a minute or two in the past to make up for the time difference. If this latency is unacceptable, use the Data Forwarder instead.

Why are backend_timestamp and device_timestamp different? backend_timestamp is typically a few minutes later than device_timestamp due to asynchronous processing. It varies more when communications between sensor and backend are interrupted, and varies wildly if the sensor’s endpoint clock is ahead or behind. device_timestamp is pulled from the time assigned in the batch of events by the sensor before the sensor sends the events to the backend, whereas backend_timestamp is assigned by the backend as soon as it receives the batch of events.

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 processes is 100.

Last modified on April 4, 2024