Observations API

Overview

This API lets you search through all Observations, which are noteworthy activity reported by your organization’s sensors, to find one or more specific Observations that match the 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 Observation Search Job
  • Look for patterns and prevalence of unusual activity across all the organization’s endpoints with a Observation Facet Job

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.
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_suggestions
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_validation
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/group_results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/detail_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/detail_jobs/{job_id}/results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results

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/v2/orgs/{org_key}/observations/search_suggestions
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_validation
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/group_results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/detail_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/detail_jobs/{job_id}/results
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs
  • {cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results

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

All Observations searches follow the pattern:

1. Start a search

The request follows the structure below where job_type is specified in the request. The job_id is returned in the response from the request and used to retrieve results and status of the search.

Note: job_type is one of search_jobs, facet_jobs or detail_jobs

Request
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/{job_type}
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
2. Get the 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.

Request
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/{job_type}/{job_id}/results
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
3. Effiently getting the results

To efficiently check for the completion of a search job fetch the results with the following query ?start=0&rows=0. Please add a time.sleep(0.5) or exponential backoff between each status check.

4. Job completion

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.

5. Additional details

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.

To download or review the Carbon Black Cloud Postman collection, click here.

API Calls


Search Suggestions for Observations

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


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/search_suggestions?suggest.q=<string>&suggest.count=<integer>


Query Parameters

Parameter Required Description
suggest.q Yes The query to generate suggestions for
suggest.count No The number of suggestions to return


Response Codes

Code Description Content-Type Content
200 Successfully got event suggestions application/json See sample response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_suggestions?suggest.q=device_id&suggest.count=2
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "suggestions": [
        {
            "required_skus_all": [],
            "required_skus_some": [
                "threathunter",
                "defense"
            ],
            "term": "device_id",
            "weight": 100
        },
        {
            "required_skus_all": [
                "xdr"
            ],
            "required_skus_some": [],
            "term": "netconn_remote_device_id",
            "weight": 70
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

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


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/search_validation?q=<string>&cb.min_backend_timestamp=<integer>&cb.max_backend_timestamp=<integer>


Query Parameters

Parameter Required Description
q Yes The query to validate
cb.min_backend_timestamp No The start time for the query - unix timestamp in milliseconds
cb.max_backend_timestamp No The end time for the query - unix timestamp in milliseconds


Response Codes

Code Description Content-Type Content
200 Successfully got search validation application/json See sample response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_validation?q=*:*&cb.min_backend_timestamp=1641469642000&cb.max_backend_timestamp=1678103242000
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "valid": true,
  "value_search_query": false
}
To download or review the Carbon Black Cloud Postman collection, click here.

Observation Search Job


Create Search Job

Creates an observations search job. The results for the search job may be requested using the query ID returned. This route will not request facets.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/search_jobs


Request Body - application/json 

{
    "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 Codes

Code Description Content-Type Content
200 Successfully submitted search for observations application/json See example response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request 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 Body 
{
    "job_id": "442f48e8-a4ce-4574-986f-5695b9e52dcc"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Results

Retrieves the observations search results for a given query ID. Results will be sorted based on the sort parameter used when starting the search.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/search_jobs/{job_id}/results


Query Parameters

Parameter Required Description
job_id Yes The search job ID to get results for
start No Starting rows of events, used for pagination
rows No Number of events to get, used for pagination


Response Codes

Code Description Content-Type Content
200 Successfully got observations search results application/json See below sample response
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "approximate_unaggregated": 1,
    "completed": 4,
    "contacted": 4,
    "num_aggregated": 1,
    "num_available": 1,
    "num_found": 1,
    "results": [
        {
            "alert_category": ["OBSERVED"],
            "alert_id": ["be6ff259-88e3-6286-789f-74defa192d2e"],
            "backend_timestamp": "2023-02-08T03:22:59.196Z",
            "device_group_id": 0,
            "device_id": 17482451,
            "device_name": "dev01-39x-1",
            "device_policy_id": 20792247,
            "device_timestamp": "2023-02-08T03:20:33.751Z",
            "enriched": true,
            "enriched_event_type": ["NETWORK"],
            "event_description": "The script",
            "event_id": "8fbccc2da75f11ed937ae3cb089984c6",
            "event_network_inbound": false,
            "event_network_local_ipv4": "10.203.105.21",
            "event_network_location": "Santa Clara,CA,United States",
            "event_network_protocol": "TCP",
            "event_network_remote_ipv4": "23.44.229.234",
            "event_network_remote_port": 80,
            "event_type": ["netconn"],
            "ingress_time": 1675826462036,
            "legacy": true,
            "observation_description": "The application firefox.exe invoked ",
            "observation_id": "8fbccc2da75f11ed937ae3cb089984c6:be6ff259-88e3-6286-789f-74defa192d2e",
            "observation_type": "CB_ANALYTICS",
            "org_id": "ABCD123456",
            "parent_guid": "ABCD123456-010ac2d3-00001c68-00000000-1d93b6c4d1f20ad",
            "parent_pid": 7272,
            "process_guid": "ABCD123456-010ac2d3-00001cf8-00000000-1d93b6c4d2b16a4",
            "process_hash": ["9df1ec5e25919660a1b0b85d3965d55797b9aac81e028008428106c4dcda7b29"],
            "process_name": "c:\\programdata\\mozilla-1de4eec8-1241-4177-a864-e594e8d1fb38\\updates\\308046b0af4a39cb\\backgroundupdate.moz_log",
            "process_pid": [7416],
            "process_username": ["DEV01-39X-1\\bit9qa"]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Grouped Results

Retrieves the observations search group results for a given query ID. Results will be grouped based on the fields provided and/or by timestamp field duration.
There are 2 different methods of grouping available when timestamp field is specified:

  • interval (default) groups the documents when the timestamp difference between two consecutive sorted documents is less than the duration requested.
    • e.g. input {doc1 = 10:00:00, doc2 = 10:07:00, doc3 = 10:13:00, doc4 = 10:27:00, duration = 10m}, doc1, doc2 and doc3 will be grouped into one since the time difference between sorted consecutive documents is less than duration.
  • bucket which groups the documents in buckets of duration length meaning the max time difference between the min and max within a group can be up to the duration.
    • e.g. input {doc1 = 10:00:00, doc2 = 10:07:00, doc3 = 10:13:00, doc4 = 10:21:00, duration = 10m}, doc1 and doc2 will be grouped into first group since the time difference between them is less than duration, doc3 will not be added to the first group it exceeds max capacity of bucket.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/search_jobs/{job_id}/group_results


Query Parameters

Parameter Required Description
job_id Yes The search job ID to get results for


Request Body - application/json 

{
  "fields": ["string"],
  "max_events_per_group": integer,
  "range": {
    "duration": "string",
    "field": "string",
    "method": "string"
  },
  "rows": integer,
  "start": integer
}

Body Schema

Field Definition Data Type Values
fields Fields to group the results Array Valid fields observation_type, device_name, process_username, attack_tactic
max_events_per_group Maximum number of events in a group, if not provided, all events will be returned Integer
range Describes a time window to restrict the search Object 
{
  "method": "<string>",
  "field": "<string>",
  "duration": "<string>"
}
method: Method of grouping either interval or bucket
field: Timestamp field is used to group the range of results e.g. device_timestamp
duration: Duration for grouping in hours, minutes or seconds like 3h, 5m, 100s
rows Number of rows to request, can be paginated Long If not provided, no records will be returned.
Max: 10k
start First row to use for pagination Long Default: 0


Response Codes

Code Description Content-Type Content
200 Successfully got observations search group results application/json See sample response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/group_results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "fields": [
        "device_name"
    ],
    "rows": 50,
    "range": {
        "duration": "10h",
        "field": "device_timestamp",
        "method": "interval"
    }
}
Response Body 
{
  "approximate_unaggregated": 442,
  "completed": 7,
  "contacted": 7,
  "group_results": [
    {
        "group_end_timestamp": "2023-02-16T13:10:10.249Z",
        "group_key": "device_name,device_timestamp:10h",
        "group_start_timestamp": "2023-02-16T13:10:10.249Z",
        "group_value": "device-name-1",
        "results": [
            {
                "backend_timestamp": "2023-02-16T20:10:00.913Z",
                "childproc_count": 0,
                "crossproc_count": 1,
                "device_group_id": 0,
                "device_id": 123456,
                "device_name": "device-name-1",
                "device_policy_id": 123456,
                "device_timestamp": "2023-02-16T13:10:10.249Z",
                "filemod_count": 0,
                "ingress_time": 1676578177580,
                "modload_count": 37,
                "netconn_count": 58,
                "observation_description": "HTTP traffic from ",
                "observation_id": "9BC8401D-AE6F-11ED-A7AB-005056A5B601:9bc8401c-ae6f-11ed-a7ab-1234566",
                "observation_type": "INTRUSION_DETECTION_SYSTEM",
                "org_id": "VZMTP3M2P6",
                "parent_guid": "VZMTP3M2P6-0243c0e7-000002b8-00000000-1d93a21111111",
                "parent_pid": 111,
                "process_guid": "VZMTP3M2P6-0243c0e7-000015b0-00000000-1111111",
                "process_hash": [
                    "f586835082f632dc8d9404d83bc16316",
                    "643ec58e82e0272c97c2a59f6020970d881af19c0ad5029db9c958c13b6511111"
                ],
                "process_name": "c:\\windows\\system32\\svchost.exe",
                "process_pid": [
                    5552
                ],
                "process_username": [
                    "NT AUTHORITY\\SYSTEM"
                ],
                "regmod_count": 1,
                "scriptload_count": 0
            }
        ],
        "total_events": 1
    }
  ],
  "groups_num_available": 0,
  "num_aggregated": 0,
  "num_available": 1,
  "num_found": 1
}
To download or review the Carbon Black Cloud Postman collection, click here.

Observation Detail Job


Create Detail Job

Creates an Observations details job. The details will include information about the given event that’s not normally accessible during a search. 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 READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/detail_jobs


Request Body - application/json 

{
  "alert_id": "string",
  "observation_ids": ["string"]
}

Body Schema

Note: Either observation_ids or alert_id is required however only one can be specified.

Field Definition Data Type Values
alert_id An alert id to fetch associated observations String N/A
observation_ids A list of observation ids to fetch Array 
["string"]


Response Codes

Code Description Content-Type Content
200 Successfully submitted detail_job application/json See example response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/detail_jobs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "alert_id": "038894832709076d63111e99466f73575fcf3ca"
}
Response Body 
{
    "job_id": "3a74e29f-5bad-4d0f-a489-f62a37f7b927"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Results

Retrieves the observations detail results for a given job ID.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/detail_jobs/{job_id}/results

Query Parameters

Parameter Required Description
job_id Yes The search job ID to get results for
start No Starting rows of events, used for pagination
rows No Number of events to get, used for pagination


Response Codes

Code Description Content-Type Content
200 Successfully got results application/json See example response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/detail_jobs/{job_id}/results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
        "approximate_unaggregated": 2,
        "completed": 4,
        "contacted": 4,
        "num_aggregated": 1,
        "num_available": 1,
        "num_found": 1,
        "results": [
                {
                        "alert_category": [
                                "OBSERVED"
                        ],
                        "alert_id": [
                                "be6ff259-88e3-6286-789f-74defa192fff"
                        ],
                        "backend_timestamp": "2023-02-08T03:22:21.570Z",
                        "device_external_ip": "127.0.0.1",
                        "device_group_id": 0,
                        "device_id": 17482451,
                        "device_installed_by": "bit9qa",
                        "device_internal_ip": "127.0.0.1",
                        "device_location": "ONSITE",
                        "device_name": "dev01-39x-1",
                        "device_os": "WINDOWS",
                        "device_os_version": "Windows 10 x64",
                        "device_policy": "lonergan policy",
                        "device_policy_id": 12345,
                        "device_target_priority": "MEDIUM",
                        "device_timestamp": "2023-02-08T03:20:33.751Z",
                        "document_guid": "KBrOYUNlTYe116ADgNvGw",
                        "enriched": true,
                        "enriched_event_type": "NETWORK",
                        "event_description": "The script...",
                        "event_id": "8fbccc2da75f11ed937ae3cb089984c6",
                        "event_network_inbound": false,
                        "event_network_local_ipv4": "127.0.0.1",
                        "event_network_location": "Santa Clara,CA,United States",
                        "event_network_protocol": "TCP",
                        "event_network_remote_ipv4": "127.0.0.1",
                        "event_network_remote_port": 80,
                        "event_report_code": "SUB_RPT_NONE",
                        "event_threat_score": [
                                3
                        ],
                        "event_type": "netconn",
                        "ingress_time": 1675826462036,
                        "legacy": true,
                        "netconn_actions": [
                                "ACTION_CONNECTION_ESTABLISHED"
                        ],
                        "netconn_domain": "a1887..dscq..akamai..net",
                        "netconn_inbound": false,
                        "netconn_ipv4": 388818410,
                        "netconn_local_ipv4": 11111,
                        "netconn_local_port": 11,
                        "netconn_location": "Santa Clara,CA,United States",
                        "netconn_port": 80,
                        "netconn_protocol": "PROTO_TCP",
                        "observation_description": "The application firefox.exe invoked ",
                        "observation_id": "8fbccc2da75f11ed937ae3cb089984c6:be6ff259-88e3-6286-789f-74defa192d2e",
                        "observation_type": "CB_ANALYTICS",
                        "org_id": "ABCD123456",
                        "parent_effective_reputation": "ADAPTIVE_WHITE_LIST",
                        "parent_effective_reputation_source": "CLOUD",
                        "parent_guid": "TEST-010ac2d3-00001c68-00000000-1d93b6c4d1f20ad",
                        "parent_hash": [
                                "69c8bd1c1dc6103df6bfa9882b5717c0dc4acb8c0c85d8f5c9900db860b6c29b"
                        ],
                        "parent_name": "c:\\program files\\mozilla firefox\\firefox.exe",
                        "parent_pid": 7272,
                        "parent_reputation": "NOT_LISTED",
                        "process_cmdline": [
                                "C:\\Program Files\\Mozilla "
                        ],
                        "process_cmdline_length": [
                                268
                        ],
                        "process_effective_reputation": "NOT_LISTED",
                        "process_effective_reputation_source": "AV",
                        "process_guid": "ABCD123456-010ac2d3-00001cf8-00000000-1d93b6c4d2b16a4",
                        "process_hash": [
                                "9df1ec5e25919660a1b0b85d3965d55797b9aac81e028008428106c4dc"
                        ],
                        "process_name": "c:\\programdata\\mozilla-1de4eec8-1241-4177-a864-e594e8d1fb38\\updates\\308046b0af4a39cb\\backgroundupdate.moz_log",
                        "process_pid": [
                                7416
                        ],
                        "process_reputation": "NOT_LISTED",
                        "process_sha256": "9df1ec5e25919660a1b0b85d3965d55797b9aac81e028008428106c4dc",
                        "process_start_time": "2023-02-08T03:20:32.131Z",
                        "process_username": [
                                "DEV01-39X-1\\bit9qa"
                        ],
                        "ttp": [
                                "INTERNATIONAL_SITE",
                                "ACTIVE_CLIENT",
                                "NETWORK_ACCESS",
                                "UNKNOWN_APP"
                        ]
                }
        ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Observation Facet Job


Start Facet Job

Creates an observations facet job. The results for the facet job may be requested using the query ID returned. This route will not request processes.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.search.events READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Search:org.Events.READ, _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}/observations/facet_jobs


Request Body - application/json 

{
    "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 Codes

Code Description Content-Type Content
200 Successfully submitted facet_job application/json See example response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/facet_jobs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request 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 Body 
{
    "job_id": "505bf994-a335-426e-bd8c-b2e388f977f2"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Facet Results

Retrieves the observations facet results for a given query ID.


API Permissions Required

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


Request 
GET {cbc-hostname}{cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results


Query Parameters

Parameter Required Description
job_id Yes The search job ID to get results for
limit No Maximum number of facets per category (i.e Any Process Search Fields listed in terms.fields)


Response Codes

Code Description Content-Type Content
200 Successfully got observations facets application/json See example response below
400 Bad Request application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
403 Forbidden application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
429 Too Many Requests application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}
500 Server Error application/json 
{
  "message": "string",
  "translation_format_values": [
    {}
  ],
  "translation_key": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "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
}
To download or review the Carbon Black Cloud Postman collection, click here.

Last modified on March 20, 2023