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
- Search Fields - Investigate APIs
- Carbon Black Cloud User Guide - Investigate - Observations
- Tech Zone - Identity Intelligence - Auth Event Breakdown
- Carbon Black Cloud Python SDK - Observations extensions coming soon
- Postman Collection - Observations extensions coming soon
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:
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
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/{job_type}
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
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.
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/{job_type}/{job_id}/results
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
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.
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
.
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.
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 |
|
403 | Forbidden | application/json |
|
500 | Server Error | application/json |
|
Examples
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_suggestions?suggest.q=device_id&suggest.count=2
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"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
}
]
}
Validate Observation Search
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 |
|
403 | Forbidden | application/json |
|
500 | Server Error | application/json |
|
Examples
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
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"valid": true,
"value_search_query": false
}
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 |
|
exclusions |
Exclusions is a map that represents values that must not be in the results. Either query or criteria /exclusion must be included. |
Object |
|
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 |
["*"] |
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 |
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 |
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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"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"
}
}
{
"job_id": "442f48e8-a4ce-4574-986f-5695b9e52dcc"
}
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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/results
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"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"]
}
]
}
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 : 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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/search_jobs/{job_id}/group_results
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"fields": [
"device_name"
],
"rows": 50,
"range": {
"duration": "10h",
"field": "device_timestamp",
"method": "interval"
}
}
{
"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
}
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 |
|
Response Codes
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully submitted detail_job | application/json | See example response below |
400 | Bad Request | application/json |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/detail_jobs
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"alert_id": "038894832709076d63111e99466f73575fcf3ca"
}
{
"job_id": "3a74e29f-5bad-4d0f-a489-f62a37f7b927"
}
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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/detail_jobs/{job_id}/results
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"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"
]
}
]
}
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 |
|
exclusions |
Exclusions is a map that represents values that must not be in the results. Either query or criteria /exclusion must be included. |
Object |
|
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 |
|
terms |
The enriched events fields to facet and how many of the top entries to return. | Object |
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 |
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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
POST https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/facet_jobs
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"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"
}
}
{
"job_id": "505bf994-a335-426e-bd8c-b2e388f977f2"
}
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 |
|
403 | Forbidden | application/json |
|
429 | Too Many Requests | application/json |
|
500 | Server Error | application/json |
|
Examples
GET https://defense.conferdeploy.net/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"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
}