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


Query Parameters

Parameter Required Type Description
suggest.q Yes String The query to generate suggestions for
suggest.count No Integer 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/ABCD1234/observations/search_suggestions?suggest.q=device_id
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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/search_suggestions?suggest.q=device_id \
-X GET \
-H '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.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile='example_profile')
result = Observation.search_suggestions(api, "device_id", 10)

print(result)
Result 
[{'term': 'device_id', 'weight': 300, 'required_skus_all': [], 'required_skus_some': ['threathunter', 'defense']}]
To learn about credentials handling, capabilities, and more about the CBC Python SDK, 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


Query Parameters

Parameter Required Type Description
q Yes string The query to validate
cb.min_backend_timestamp No Integer The start time for the query - unix timestamp in milliseconds
cb.max_backend_timestamp No Integer 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/ABCD1234/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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/search_validation?q=*:*&cb.min_backend_timestamp=1641469642000&cb.max_backend_timestamp=1678103242000 \
-X GET \
-H '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.

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


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 

{
    "collapse_field": [ "<string>" ],
    "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
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 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/ABCD1234/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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/search_jobs \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
  "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.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")
observations = api.select(Observation).where("process_name:svchost.exe")

print(*observations)
Result 
Observation object, bound to https://defense.conferdeploy.net.
 Partially initialized. Use .refresh() to load all attributes
-------------------------------------------------------------------------------

          backend_timestamp: 2023-05-31T17:32:38.959Z
            device_group_id: 0
                  device_id: 17497436
                device_name: cis12r1\win2012r1x64
           device_policy_id: 19888416
           device_timestamp: 2023-05-31T17:29:41.010Z
                   enriched: True
        enriched_event_type: [list:1 item]:
                             [0]: CREATE_PROCESS
          event_description: The application share link hash=1d35014d937...
                   event_id: f1af2716ffd811ed992d5782cf8f8308
                 event_type: childproc
               ingress_time: 1685554288501
                     legacy: True
    observation_description: The application share link hash="1d35014d937...
             observation_id: f1af2716ffd811ed992d5782cf8f8308
           observation_type: CONTEXTUAL_ACTIVITY
                     org_id: ABCD1234
                parent_guid: ABCD1234-010afd5c-00000204-00000000-1d8cdbe70...
                 parent_pid: 516
               process_guid: ABCD1234-010afd5c-0000039c-00000000-1d8cdbe72...
               process_hash: [list:1 item]:
                             [0]: 1d35014d937e02ee090a0cfc903ee6e6b1b65c832694519...
               process_name: c:\windows\system32\svchost.exe
                process_pid: [list:1 item]:
                             [0]: 924
           process_username: [list:1 item]:
                             [0]: NT AUTHORITY\SYSTEM
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Get Results

Retrieves the observations search results for a given job 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 Type Description
start No Integer Starting rows of events, used for pagination
rows No Integer 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/ABCD1234/observations/search_jobs/7484eb31-666c-40b1-8dd7-5d5de0909169-sqs/results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "results": [
    {
      "alert_category": [
        "THREAT"
      ],
      "alert_id": [
        "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
        "5f071f02-4325-9bd0-2df4-5d430957b6da",
        "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
        "fc6dfbf3-c264-3dba-6a06-1d009929308b"
      ],
      "backend_timestamp": "2023-05-31T09:52:57.975Z",
      "childproc_count": 0,
      "crossproc_count": 158,
      "device_external_ip": "10.10.10.10",
      "device_group_id": 0,
      "device_id": 6685063,
      "device_installed_by": "tester",
      "device_internal_ip": "10.243.93.126",
      "device_location": "UNKNOWN",
      "device_name": "desktop",
      "device_os": "WINDOWS",
      "device_os_version": "Windows 10 x64",
      "device_policy": "default",
      "device_policy_id": 6525,
      "device_sensor_version": "3.9.0.2357",
      "device_target_priority": "MEDIUM",
      "device_timestamp": "2023-05-31T09:47:55.264Z",
      "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
      "enriched": true,
      "enriched_event_type": [
        "NETWORK"
      ],
      "event_threat_score": [
        0,
        3
      ],
      "filemod_count": 97,
      "ingress_time": 1685526632142,
      "legacy": true,
      "modload_count": 47,
      "netconn_count": 1244,
      "observation_description": "The application share link hash=1d35014d937",
      "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
      "observation_type": "CONTEXTUAL_ACTIVITY",
      "org_id": "ABCD1234",
      "parent_cmdline": "C:\\Windows\\system32\\services.exe",
      "parent_cmdline_length": 32,
      "parent_effective_reputation": "TRUSTED_WHITE_LIST",
      "parent_effective_reputation_source": "APPROVED_DATABASE",
      "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
      "parent_hash": [
        "d8e577bf078c45954f4531885478d5a9",
        "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
      ],
      "parent_name": "c:\\windows\\system32\\services.exe",
      "parent_pid": 612,
      "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": "TRUSTED_WHITE_LIST",
      "process_cmdline": [
        "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
      ],
      "process_cmdline_length": [
        44
      ],
      "process_company_name": "Microsoft Corporation",
      "process_effective_reputation": "TRUSTED_WHITE_LIST",
      "process_effective_reputation_source": "CLOUD",
      "process_elevated": true,
      "process_file_description": "Host Process for Windows Services",
      "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
      "process_hash": [
        "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
        "b7f884c1b74a263f746ee12a5f7c9f6a"
      ],
      "process_integrity_level": "SYSTEM",
      "process_internal_name": "svchost.exe",
      "process_name": "c:\\windows\\system32\\svchost.exe",
      "process_original_filename": "svchost.exe",
      "process_pid": [
        2600
      ],
      "process_privileges": [
        "SeChangeNotifyPrivilege",
        "SeCreateGlobalPrivilege",
        "SeDebugPrivilege",
        "SeImpersonatePrivilege",
        "SeSystemProfilePrivilege",
        "SeTcbPrivilege"
      ],
      "process_product_name": "Microsoft® Windows® Operating System",
      "process_product_version": "10.0.19041.1806",
      "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": [
        "diagtrack"
      ],
      "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
      "process_start_time": "2023-04-05T05:29:10.450Z",
      "process_username": [
        "NT AUTHORITY\\SYSTEM"
      ],
      "regmod_count": 1417,
      "scriptload_count": 0,
      "sensor_action": [
        "BLOCK",
        "DENY"
      ],
      "ttp": [
        "INTERNATIONAL_SITE",
        "POLICY_DENY"
      ],
      "watchlist_hit": [
        "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
      ]
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "approximate_unaggregated": 13262,
  "num_aggregated": 13262,
  "contacted": 47,
  "completed": 47
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/search_jobs/7484eb31-666c-40b1-8dd7-5d5de0909169-sqs/results \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "results": [
    {
      "alert_category": [
        "THREAT"
      ],
      "alert_id": [
        "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
        "5f071f02-4325-9bd0-2df4-5d430957b6da",
        "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
        "fc6dfbf3-c264-3dba-6a06-1d009929308b"
      ],
      "backend_timestamp": "2023-05-31T09:52:57.975Z",
      "childproc_count": 0,
      "crossproc_count": 158,
      "device_external_ip": "10.10.10.10",
      "device_group_id": 0,
      "device_id": 6685063,
      "device_installed_by": "tester",
      "device_internal_ip": "10.243.93.126",
      "device_location": "UNKNOWN",
      "device_name": "desktop",
      "device_os": "WINDOWS",
      "device_os_version": "Windows 10 x64",
      "device_policy": "default",
      "device_policy_id": 6525,
      "device_sensor_version": "3.9.0.2357",
      "device_target_priority": "MEDIUM",
      "device_timestamp": "2023-05-31T09:47:55.264Z",
      "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
      "enriched": true,
      "enriched_event_type": [
        "NETWORK"
      ],
      "event_threat_score": [
        0,
        3
      ],
      "filemod_count": 97,
      "ingress_time": 1685526632142,
      "legacy": true,
      "modload_count": 47,
      "netconn_count": 1244,
      "observation_description": "The application share link hash=1d35014d937",
      "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
      "observation_type": "CONTEXTUAL_ACTIVITY",
      "org_id": "ABCD1234",
      "parent_cmdline": "C:\\Windows\\system32\\services.exe",
      "parent_cmdline_length": 32,
      "parent_effective_reputation": "TRUSTED_WHITE_LIST",
      "parent_effective_reputation_source": "APPROVED_DATABASE",
      "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
      "parent_hash": [
        "d8e577bf078c45954f4531885478d5a9",
        "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
      ],
      "parent_name": "c:\\windows\\system32\\services.exe",
      "parent_pid": 612,
      "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": "TRUSTED_WHITE_LIST",
      "process_cmdline": [
        "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
      ],
      "process_cmdline_length": [
        44
      ],
      "process_company_name": "Microsoft Corporation",
      "process_effective_reputation": "TRUSTED_WHITE_LIST",
      "process_effective_reputation_source": "CLOUD",
      "process_elevated": true,
      "process_file_description": "Host Process for Windows Services",
      "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
      "process_hash": [
        "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
        "b7f884c1b74a263f746ee12a5f7c9f6a"
      ],
      "process_integrity_level": "SYSTEM",
      "process_internal_name": "svchost.exe",
      "process_name": "c:\\windows\\system32\\svchost.exe",
      "process_original_filename": "svchost.exe",
      "process_pid": [
        2600
      ],
      "process_privileges": [
        "SeChangeNotifyPrivilege",
        "SeCreateGlobalPrivilege",
        "SeDebugPrivilege",
        "SeImpersonatePrivilege",
        "SeSystemProfilePrivilege",
        "SeTcbPrivilege"
      ],
      "process_product_name": "Microsoft® Windows® Operating System",
      "process_product_version": "10.0.19041.1806",
      "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": [
        "diagtrack"
      ],
      "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
      "process_start_time": "2023-04-05T05:29:10.450Z",
      "process_username": [
        "NT AUTHORITY\\SYSTEM"
      ],
      "regmod_count": 1417,
      "scriptload_count": 0,
      "sensor_action": [
        "BLOCK",
        "DENY"
      ],
      "ttp": [
        "INTERNATIONAL_SITE",
        "POLICY_DENY"
      ],
      "watchlist_hit": [
        "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
      ]
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "approximate_unaggregated": 13262,
  "num_aggregated": 13262,
  "contacted": 47,
  "completed": 47
}
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")
observations = api.select(Observation).where("process_name:svchost.exe")

print(*observations)
Result 
Observation object, bound to https://defense.conferdeploy.net.
 Partially initialized. Use .refresh() to load all attributes
-------------------------------------------------------------------------------

          backend_timestamp: 2023-05-31T17:32:38.959Z
            device_group_id: 0
                  device_id: 17497436
                device_name: cis12r1\win2012r1x64
           device_policy_id: 19888416
           device_timestamp: 2023-05-31T17:29:41.010Z
                   enriched: True
        enriched_event_type: [list:1 item]:
                             [0]: CREATE_PROCESS
          event_description: The application share link hash=1d35014d937...
                   event_id: f1af2716ffd811ed992d5782cf8f8308
                 event_type: childproc
               ingress_time: 1685554288501
                     legacy: True
    observation_description: The application share link hash="1d35014d937...
             observation_id: f1af2716ffd811ed992d5782cf8f8308
           observation_type: CONTEXTUAL_ACTIVITY
                     org_id: ABCD1234
                parent_guid: ABCD1234-010afd5c-00000204-00000000-1d8cdbe70...
                 parent_pid: 516
               process_guid: ABCD1234-010afd5c-0000039c-00000000-1d8cdbe72...
               process_hash: [list:1 item]:
                             [0]: 1d35014d937e02ee090a0cfc903ee6e6b1b65c832694519...
               process_name: c:\windows\system32\svchost.exe
                process_pid: [list:1 item]:
                             [0]: 924
           process_username: [list:1 item]:
                             [0]: NT AUTHORITY\SYSTEM
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Get Grouped Results

Retrieves the observations search group results for a given job 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


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/ABCD1234/observations/search_jobs/123456/group_results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "fields": [
        "device_name"
    ],
    "rows": 1
}
Response Body 
{
  "group_results": [
    {
      "group_key": "device_name",
      "group_value": "desktop",
      "group_start_timestamp": "2023-05-31T09:47:55.264Z",
      "group_end_timestamp": "2023-05-31T09:47:55.264Z",
      "results": [
        {
          "alert_category": [
            "THREAT"
          ],
          "alert_id": [
            "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
            "5f071f02-4325-9bd0-2df4-5d430957b6da",
            "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
            "fc6dfbf3-c264-3dba-6a06-1d009929308b"
          ],
          "backend_timestamp": "2023-05-31T09:52:57.975Z",
          "childproc_count": 0,
          "crossproc_count": 158,
          "device_external_ip": "10.10.10.10",
          "device_group_id": 0,
          "device_id": 6685063,
          "device_installed_by": "tester",
          "device_internal_ip": "10.243.93.126",
          "device_location": "UNKNOWN",
          "device_name": "desktop",
          "device_os": "WINDOWS",
          "device_os_version": "Windows 10 x64",
          "device_policy": "default",
          "device_policy_id": 6525,
          "device_sensor_version": "3.9.0.2357",
          "device_target_priority": "MEDIUM",
          "device_timestamp": "2023-05-31T09:47:55.264Z",
          "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
          "enriched": true,
          "enriched_event_type": [
            "NETWORK"
          ],
          "event_threat_score": [
            0,
            3
          ],
          "filemod_count": 97,
          "ingress_time": 1685526632142,
          "legacy": true,
          "modload_count": 47,
          "netconn_count": 1244,
          "observation_description": "The application share link hash=1d35014d937",
          "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
          "observation_type": "CONTEXTUAL_ACTIVITY",
          "org_id": "ABCD1234",
          "parent_cmdline": "C:\\Windows\\system32\\services.exe",
          "parent_cmdline_length": 32,
          "parent_effective_reputation": "TRUSTED_WHITE_LIST",
          "parent_effective_reputation_source": "APPROVED_DATABASE",
          "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
          "parent_hash": [
            "d8e577bf078c45954f4531885478d5a9",
            "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
          ],
          "parent_name": "c:\\windows\\system32\\services.exe",
          "parent_pid": 612,
          "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": "TRUSTED_WHITE_LIST",
          "process_cmdline": [
            "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
          ],
          "process_cmdline_length": [
            44
          ],
          "process_company_name": "Microsoft Corporation",
          "process_effective_reputation": "TRUSTED_WHITE_LIST",
          "process_effective_reputation_source": "CLOUD",
          "process_elevated": true,
          "process_file_description": "Host Process for Windows Services",
          "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
          "process_hash": [
            "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
            "b7f884c1b74a263f746ee12a5f7c9f6a"
          ],
          "process_integrity_level": "SYSTEM",
          "process_internal_name": "svchost.exe",
          "process_name": "c:\\windows\\system32\\svchost.exe",
          "process_original_filename": "svchost.exe",
          "process_pid": [
            2600
          ],
          "process_privileges": [
            "SeChangeNotifyPrivilege",
            "SeCreateGlobalPrivilege",
            "SeDebugPrivilege",
            "SeImpersonatePrivilege",
            "SeSystemProfilePrivilege",
            "SeTcbPrivilege"
          ],
          "process_product_name": "Microsoft® Windows® Operating System",
          "process_product_version": "10.0.19041.1806",
          "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": [
            "diagtrack"
          ],
          "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
          "process_start_time": "2023-04-05T05:29:10.450Z",
          "process_username": [
            "NT AUTHORITY\\SYSTEM"
          ],
          "regmod_count": 1417,
          "scriptload_count": 0,
          "sensor_action": [
            "BLOCK",
            "DENY"
          ],
          "ttp": [
            "INTERNATIONAL_SITE",
            "POLICY_DENY"
          ],
          "watchlist_hit": [
            "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
          ]
        }
      ],
      "total_events": 1
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "groups_num_available": 1,
  "approximate_unaggregated": 13262,
  "num_aggregated": 13262,
  "contacted": 47,
  "completed": 47
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/search_jobs/123456/group_results \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
    "fields": [
        "device_name"
    ],
    "rows": 1
}'
Response Body 
{
  "group_results": [
    {
      "group_key": "device_name",
      "group_value": "desktop",
      "group_start_timestamp": "2023-05-31T09:47:55.264Z",
      "group_end_timestamp": "2023-05-31T09:47:55.264Z",
      "results": [
        {
          "alert_category": [
            "THREAT"
          ],
          "alert_id": [
            "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
            "5f071f02-4325-9bd0-2df4-5d430957b6da",
            "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
            "fc6dfbf3-c264-3dba-6a06-1d009929308b"
          ],
          "backend_timestamp": "2023-05-31T09:52:57.975Z",
          "childproc_count": 0,
          "crossproc_count": 158,
          "device_external_ip": "10.10.10.10",
          "device_group_id": 0,
          "device_id": 6685063,
          "device_installed_by": "tester",
          "device_internal_ip": "10.243.93.126",
          "device_location": "UNKNOWN",
          "device_name": "desktop",
          "device_os": "WINDOWS",
          "device_os_version": "Windows 10 x64",
          "device_policy": "default",
          "device_policy_id": 6525,
          "device_sensor_version": "3.9.0.2357",
          "device_target_priority": "MEDIUM",
          "device_timestamp": "2023-05-31T09:47:55.264Z",
          "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
          "enriched": true,
          "enriched_event_type": [
            "NETWORK"
          ],
          "event_threat_score": [
            0,
            3
          ],
          "filemod_count": 97,
          "ingress_time": 1685526632142,
          "legacy": true,
          "modload_count": 47,
          "netconn_count": 1244,
          "observation_description": "The application share link hash=1d35014d937",
          "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
          "observation_type": "CONTEXTUAL_ACTIVITY",
          "org_id": "ABCD1234",
          "parent_cmdline": "C:\\Windows\\system32\\services.exe",
          "parent_cmdline_length": 32,
          "parent_effective_reputation": "TRUSTED_WHITE_LIST",
          "parent_effective_reputation_source": "APPROVED_DATABASE",
          "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
          "parent_hash": [
            "d8e577bf078c45954f4531885478d5a9",
            "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
          ],
          "parent_name": "c:\\windows\\system32\\services.exe",
          "parent_pid": 612,
          "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": "TRUSTED_WHITE_LIST",
          "process_cmdline": [
            "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
          ],
          "process_cmdline_length": [
            44
          ],
          "process_company_name": "Microsoft Corporation",
          "process_effective_reputation": "TRUSTED_WHITE_LIST",
          "process_effective_reputation_source": "CLOUD",
          "process_elevated": true,
          "process_file_description": "Host Process for Windows Services",
          "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
          "process_hash": [
            "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
            "b7f884c1b74a263f746ee12a5f7c9f6a"
          ],
          "process_integrity_level": "SYSTEM",
          "process_internal_name": "svchost.exe",
          "process_name": "c:\\windows\\system32\\svchost.exe",
          "process_original_filename": "svchost.exe",
          "process_pid": [
            2600
          ],
          "process_privileges": [
            "SeChangeNotifyPrivilege",
            "SeCreateGlobalPrivilege",
            "SeDebugPrivilege",
            "SeImpersonatePrivilege",
            "SeSystemProfilePrivilege",
            "SeTcbPrivilege"
          ],
          "process_product_name": "Microsoft® Windows® Operating System",
          "process_product_version": "10.0.19041.1806",
          "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": [
            "diagtrack"
          ],
          "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
          "process_start_time": "2023-04-05T05:29:10.450Z",
          "process_username": [
            "NT AUTHORITY\\SYSTEM"
          ],
          "regmod_count": 1417,
          "scriptload_count": 0,
          "sensor_action": [
            "BLOCK",
            "DENY"
          ],
          "ttp": [
            "INTERNATIONAL_SITE",
            "POLICY_DENY"
          ],
          "watchlist_hit": [
            "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
          ]
        }
      ],
      "total_events": 1
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "groups_num_available": 1,
  "approximate_unaggregated": 13262,
  "num_aggregated": 13262,
  "contacted": 47,
  "completed": 47
}
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")

observation_groups = api.select(Observation).where("process_name:svchost.exe").get_group_results("device_name")
for group in observation_groups:
    for obs in group.observations:
        print(obs._info)
Result 
{'backend_timestamp': '2023-05-31T18:11:20.950Z', 'device_group_id': 0, 'device_id': 18458193, 'device_name': 'cnauto\\確認2019', 'device_policy_id': 19888416, 'device_timestamp': '2023-05-31T18:09:29.988Z', 'enriched': True, 'enriched_event_type': ['CREATE_PROCESS'], 'event_description': 'The application "<share><link hash="7fd065bac18c5278777ae44908101cdfed72d26fa741367f0ad4d02020787ab6">C:\\Windows\\system32\\svchost.exe -k LocalServiceNetworkRestricted -p -s WinHttpAutoProxySvc</link></share" invoked the application "share link hash="ff4d515cdcbe9ce053d9cc4d3412f962875098ac87133019eeb12a0f9494bb91">c:\\windows\\system32\\pacjsworker.exe/link/share". The operation was successful.', 'event_id': '597b5206ffde11ed8aba57c9a698d109', 'event_type': 'childproc', 'ingress_time': 1685556618924, 'legacy': True, 'observation_description': 'The application "<share><link hash="7fd065bac18c5278777ae44908101cdfed72d26fa741367f0ad4d02020787ab6">C:\\Windows\\system32\\svchost.exe -k LocalServiceNetworkRestricted -p -s WinHttpAutoProxySvc</link></share>" invoked the application "<share><link hash="ff4d515cdcbe9ce053d9cc4d3412f962875098ac87133019eeb12a0f9494bb91">c:\\windows\\system32\\pacjsworker.exe</link></share>". The operation was successful.', 'observation_id': '597b5206ffde11ed8aba57c9a698d109', 'observation_type': 'CONTEXTUAL_ACTIVITY', 'org_id': 'ABCD1234', 'parent_guid': 'ABCD1234-0119a651-00000284-00000000-1d9735d0985e31b', 'parent_pid': 644, 'process_guid': 'ABCD1234-0119a651-00000660-00000000-1d993e6d9b2f03e', 'process_hash': ['7fd065bac18c5278777ae44908101cdfed72d26fa741367f0ad4d02020787ab6'], 'process_name': 'c:\\windows\\system32\\svchost.exe', 'process_pid': [1632], 'process_username': ['NT AUTHORITY\\LOCAL SERVICE']}
To learn about credentials handling, capabilities, and more about the CBC Python SDK, 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>"],
  "process_hash": "<string>",
  "device_id": <integer>,
  "count_unique_devices": <boolean>,
  "max_rows": <integer>
}

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

Note: Four new search payloads have been introduced: “process_hash”, “device_id”, “count_unique_devices”, and “max_rows.” The various combinations of these payloads yield distinct search outcomes:

  • process_hash
    • Finds the oldest event with this process hash.
  • process_hash + device_id
    • Finds the oldest event with this process hash on the given device_id.
  • process_hash + count_unique_devices
    • Returns how many unique devices have executed this process hash. It is recommended to set max_rows to 10,000 to ensure valid results from the endpoint.
  • max_rows
    • An optional parameter that can only be combined with process_hash. It filters the number of results the endpoint returns, with a maximum value of 10,000. Therefore, the following cases are valid:
      • process_hash + max_rows
      • process_hash + count_unique_devices + max_rows (recommended to be 10,000)
      • process_hash + device_id + max_rows - Returns the top max_rows events, sorted from the oldest to the newest.


Body Schema

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"]
process_hash A unique identifier for a specific process or event String N/A
device_id An identifier for the device where the event occurred Integer N/A
count_unique_devices Boolean
max_rows Filters the number of results the endpoint returns Integer N/A


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/ABCD1234/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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/detail_jobs \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
    "alert_id": "038894832709076d63111e99466f73575fcf3ca"
}'
Response Body 
{
    "job_id": "3a74e29f-5bad-4d0f-a489-f62a37f7b927"
}
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")

obs_list = api.select(Observation).where("process_name:svchost.exe")
print(obs_list[0].get_details())
Result 
Observation object, bound to https://defense.conferdeploy.net.
 Partially initialized. Use .refresh() to load all attributes
-------------------------------------------------------------------------------

                        backend_timestamp: 2023-05-31T18:27:23.735Z
                        childproc_cmdline: "C:\Windows\system32\devicecensus.exe" SystemCxt
                 childproc_cmdline_length: 48
           childproc_effective_reputation: LOCAL_WHITE
    childproc_effective_reputation_source: CERT
                           childproc_guid: ABCD1234-0119a4da-0000077c-00000000-1d993ed6b...
                           childproc_hash: [list:1 item]:
                                           [0]: 72f8fe48ec36570ff9a65cf472624eb64a9e480904e9b9f...
                           childproc_name: c:\windows\system32\devicecensus.exe
                            childproc_pid: 1916
                     childproc_reputation: NOT_LISTED
                       device_external_ip: 10.10.10.10
                          device_group_id: 0
                                device_id: 18457818
                      device_installed_by: Administrator
                       device_internal_ip: 10.193.5.12
                          device_location: OFFSITE
                              device_name: notassess\体験win10
                                device_os: WINDOWS
                        device_os_version: Windows 10 x64
                            device_policy: standard
                         device_policy_id: 19888416
                   device_target_priority: MEDIUM
                         device_timestamp: 2023-05-31T18:26:30.425Z
                            document_guid: Sz8It3csQr-U6CylIgSz_A
                                 enriched: True
                      enriched_event_type: CREATE_PROCESS
                        event_description: The application "share link hash="add683a6910...
                                 event_id: aaba81c2ffe011ed992d5782cf8f8308
                               event_type: childproc
                             ingress_time: 1685557605981
                                   legacy: True
                  observation_description: The application "share link hash="add683a6910...
                           observation_id: aaba81c2ffe011ed992d5782cf8f8308
                         observation_type: CONTEXTUAL_ACTIVITY
                                   org_id: ABCD1234
              parent_effective_reputation: LOCAL_WHITE
       parent_effective_reputation_source: CERT
                              parent_guid: ABCD1234-0119a4da-000002e4-00000000-1d9835e27...
                              parent_hash: [list:1 item]:
                                           [0]: e6fe9a94e8686e957dbcec2b89c1c1ddcf8e75d76e9200d...
                              parent_name: c:\windows\system32\services.exe
                               parent_pid: 740
                        parent_reputation: ADAPTIVE_WHITE_LIST
                          process_cmdline: [list:1 item]:
                                           [0]: C:\Windows\system32\svchost.exe -k netsvcs -p -...
                   process_cmdline_length: [list:1 item]:
                                           [0]: 57
             process_effective_reputation: TRUSTED_WHITE_LIST
      process_effective_reputation_source: CLOUD
                             process_guid: ABCD1234-0119a4da-000006cc-00000000-1d9835e29...
                             process_hash: [list:2 items]:
                                           [0]: b7f884c1b74a263f746ee12a5f7c9f6a
                                           [1]: add683a6910abbbf0e28b557fad0ba998166394932ae2ac...
                             process_name: c:\windows\system32\svchost.exe
                              process_pid: [list:1 item]:
                                           [0]: 1740
                       process_reputation: TRUSTED_WHITE_LIST
                           process_sha256: add683a6910abbbf0e28b557fad0ba998166394932ae2ac...
                       process_start_time: 2023-05-10T16:40:42.569Z
                         process_username: [list:1 item]:
                                           [0]: NT AUTHORITY\SYSTEM
                                      ttp: [list:1 item]:
                                           [0]: RUN_UNKNOWN_APP
To learn about credentials handling, capabilities, and more about the CBC Python SDK, 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 Type Description
start No Integer Starting rows of events, used for pagination
rows No Integer 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/ABCD1234/observations/detail_jobs/3a74e29f-5bad-4d0f-a489-f62a37f7b927/results
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "results": [
    {
      "alert_category": [
        "THREAT"
      ],
      "alert_id": [
        "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
        "5f071f02-4325-9bd0-2df4-5d430957b6da",
        "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
        "fc6dfbf3-c264-3dba-6a06-1d009929308b"
      ],
      "backend_timestamp": "2023-05-31T09:52:57.975Z",
      "childproc_count": 0,
      "crossproc_count": 158,
      "device_external_ip": "10.10.10.10",
      "device_group_id": 0,
      "device_id": 6685063,
      "device_installed_by": "suraj",
      "device_internal_ip": "10.243.93.126",
      "device_location": "UNKNOWN",
      "device_name": "desktop-ua4omu0",
      "device_os": "WINDOWS",
      "device_os_version": "Windows 10 x64",
      "device_policy": "default",
      "device_policy_id": 6525,
      "device_sensor_version": "3.9.0.2357",
      "device_target_priority": "MEDIUM",
      "device_timestamp": "2023-05-31T09:47:55.264Z",
      "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
      "enriched": true,
      "enriched_event_type": [
        "NETWORK"
      ],
      "event_threat_score": [
        0,
        3
      ],
      "filemod_count": 97,
      "ingress_time": 1685526632142,
      "legacy": true,
      "modload_count": 47,
      "netconn_count": 1244,
      "observation_description": "The application share link hash=1d35014d937",
      "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
      "observation_type": "CONTEXTUAL_ACTIVITY",
      "org_id": "ABCD1234",
      "parent_cmdline": "C:\\Windows\\system32\\services.exe",
      "parent_cmdline_length": 32,
      "parent_effective_reputation": "TRUSTED_WHITE_LIST",
      "parent_effective_reputation_source": "APPROVED_DATABASE",
      "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
      "parent_hash": [
        "d8e577bf078c45954f4531885478d5a9",
        "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
      ],
      "parent_name": "c:\\windows\\system32\\services.exe",
      "parent_pid": 612,
      "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": "TRUSTED_WHITE_LIST",
      "process_cmdline": [
        "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
      ],
      "process_cmdline_length": [
        44
      ],
      "process_company_name": "Microsoft Corporation",
      "process_effective_reputation": "TRUSTED_WHITE_LIST",
      "process_effective_reputation_source": "CLOUD",
      "process_elevated": true,
      "process_file_description": "Host Process for Windows Services",
      "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
      "process_hash": [
        "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
        "b7f884c1b74a263f746ee12a5f7c9f6a"
      ],
      "process_integrity_level": "SYSTEM",
      "process_internal_name": "svchost.exe",
      "process_name": "c:\\windows\\system32\\svchost.exe",
      "process_original_filename": "svchost.exe",
      "process_pid": [
        2600
      ],
      "process_privileges": [
        "SeChangeNotifyPrivilege",
        "SeCreateGlobalPrivilege",
        "SeDebugPrivilege",
        "SeImpersonatePrivilege",
        "SeSystemProfilePrivilege",
        "SeTcbPrivilege"
      ],
      "process_product_name": "Microsoft® Windows® Operating System",
      "process_product_version": "10.0.19041.1806",
      "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": [
        "diagtrack"
      ],
      "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
      "process_start_time": "2023-04-05T05:29:10.450Z",
      "process_username": [
        "NT AUTHORITY\\SYSTEM"
      ],
      "regmod_count": 1417,
      "scriptload_count": 0,
      "sensor_action": [
        "BLOCK",
        "DENY"
      ],
      "ttp": [
        "INTERNATIONAL_SITE",
        "POLICY_DENY"
      ],
      "watchlist_hit": [
        "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
      ]
    }
  ],
  "num_found": 1,
  "num_available": 1,
  "approximate_unaggregated": 13262,
  "num_aggregated": 13262,
  "contacted": 47,
  "completed": 47
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/detail_jobs/3a74e29f-5bad-4d0f-a489-f62a37f7b927/results \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
  {
    "results": [
      {
        "alert_category": [
          "THREAT"
        ],
        "alert_id": [
          "224b4281-ccc5-faf2-47a2-e8b07621dfc3",
          "5f071f02-4325-9bd0-2df4-5d430957b6da",
          "a14fd205-916a-d11b-b9d9-c7cdad975cd5",
          "fc6dfbf3-c264-3dba-6a06-1d009929308b"
        ],
        "backend_timestamp": "2023-05-31T09:52:57.975Z",
        "childproc_count": 0,
        "crossproc_count": 158,
        "device_external_ip": "10.10.10.10",
        "device_group_id": 0,
        "device_id": 6685063,
        "device_installed_by": "suraj",
        "device_internal_ip": "10.243.93.126",
        "device_location": "UNKNOWN",
        "device_name": "desktop-ua4omu0",
        "device_os": "WINDOWS",
        "device_os_version": "Windows 10 x64",
        "device_policy": "default",
        "device_policy_id": 6525,
        "device_sensor_version": "3.9.0.2357",
        "device_target_priority": "MEDIUM",
        "device_timestamp": "2023-05-31T09:47:55.264Z",
        "document_guid": "1JUvWe9RSX6jvio0IC0BMQ",
        "enriched": true,
        "enriched_event_type": [
          "NETWORK"
        ],
        "event_threat_score": [
          0,
          3
        ],
        "filemod_count": 97,
        "ingress_time": 1685526632142,
        "legacy": true,
        "modload_count": 47,
        "netconn_count": 1244,
        "observation_description": "The application share link hash=1d35014d937",
        "observation_id": "f1af2716ffd811ed992d5782cf8f8308",
        "observation_type": "CONTEXTUAL_ACTIVITY",
        "org_id": "ABCD1234",
        "parent_cmdline": "C:\\Windows\\system32\\services.exe",
        "parent_cmdline_length": 32,
        "parent_effective_reputation": "TRUSTED_WHITE_LIST",
        "parent_effective_reputation_source": "APPROVED_DATABASE",
        "parent_guid": "ABCD1234-00660187-00000264-00000000-1d9677f88c1cc0f",
        "parent_hash": [
          "d8e577bf078c45954f4531885478d5a9",
          "dfbea9e8c316d9bc118b454b0c722cd674c30d0a256340200e2c3a7480cba674"
        ],
        "parent_name": "c:\\windows\\system32\\services.exe",
        "parent_pid": 612,
        "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": "TRUSTED_WHITE_LIST",
        "process_cmdline": [
          "C:\\Windows\\System32\\svchost.exe -k utcsvc -p"
        ],
        "process_cmdline_length": [
          44
        ],
        "process_company_name": "Microsoft Corporation",
        "process_effective_reputation": "TRUSTED_WHITE_LIST",
        "process_effective_reputation_source": "CLOUD",
        "process_elevated": true,
        "process_file_description": "Host Process for Windows Services",
        "process_guid": "ABCD1234-00660187-00000a28-00000000-1d9677f8cc708f0",
        "process_hash": [
          "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
          "b7f884c1b74a263f746ee12a5f7c9f6a"
        ],
        "process_integrity_level": "SYSTEM",
        "process_internal_name": "svchost.exe",
        "process_name": "c:\\windows\\system32\\svchost.exe",
        "process_original_filename": "svchost.exe",
        "process_pid": [
          2600
        ],
        "process_privileges": [
          "SeChangeNotifyPrivilege",
          "SeCreateGlobalPrivilege",
          "SeDebugPrivilege",
          "SeImpersonatePrivilege",
          "SeSystemProfilePrivilege",
          "SeTcbPrivilege"
        ],
        "process_product_name": "Microsoft® Windows® Operating System",
        "process_product_version": "10.0.19041.1806",
        "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": [
          "diagtrack"
        ],
        "process_sha256": "add683a6910abbbf0e28b557fad0ba998166394932ae2aca069d9aa19ea8fe88",
        "process_start_time": "2023-04-05T05:29:10.450Z",
        "process_username": [
          "NT AUTHORITY\\SYSTEM"
        ],
        "regmod_count": 1417,
        "scriptload_count": 0,
        "sensor_action": [
          "BLOCK",
          "DENY"
        ],
        "ttp": [
          "INTERNATIONAL_SITE",
          "POLICY_DENY"
        ],
        "watchlist_hit": [
          "uB0MoTEMQNygtNX7iDlmmg:wclPcB3cQ3akRa6GnrrQzA:5"
        ]
      }
    ],
    "num_found": 1,
    "num_available": 1,
    "approximate_unaggregated": 13262,
    "num_aggregated": 13262,
    "contacted": 47,
    "completed": 47
  }
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk.platform import Observation
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")

obs_list = api.select(Observation).where("process_name:svchost.exe")
print(obs_list[0].get_details())
Result 
Observation object, bound to https://defense.conferdeploy.net.
 Partially initialized. Use .refresh() to load all attributes
-------------------------------------------------------------------------------

                        backend_timestamp: 2023-05-31T18:27:23.735Z
                        childproc_cmdline: "C:\Windows\system32\devicecensus.exe" SystemCxt
                 childproc_cmdline_length: 48
           childproc_effective_reputation: LOCAL_WHITE
    childproc_effective_reputation_source: CERT
                           childproc_guid: ABCD1234-0119a4da-0000077c-00000000-1d993ed6b...
                           childproc_hash: [list:1 item]:
                                           [0]: 72f8fe48ec36570ff9a65cf472624eb64a9e480904e9b9f...
                           childproc_name: c:\windows\system32\devicecensus.exe
                            childproc_pid: 1916
                     childproc_reputation: NOT_LISTED
                       device_external_ip: 10.10.10.10
                          device_group_id: 0
                                device_id: 18457818
                      device_installed_by: Administrator
                       device_internal_ip: 10.193.5.12
                          device_location: OFFSITE
                              device_name: notassess\体験win10
                                device_os: WINDOWS
                        device_os_version: Windows 10 x64
                            device_policy: standard
                         device_policy_id: 19888416
                   device_target_priority: MEDIUM
                         device_timestamp: 2023-05-31T18:26:30.425Z
                            document_guid: Sz8It3csQr-U6CylIgSz_A
                                 enriched: True
                      enriched_event_type: CREATE_PROCESS
                        event_description: The application "share link hash="add683a6910...
                                 event_id: aaba81c2ffe011ed992d5782cf8f8308
                               event_type: childproc
                             ingress_time: 1685557605981
                                   legacy: True
                  observation_description: The application "share link hash="add683a6910...
                           observation_id: aaba81c2ffe011ed992d5782cf8f8308
                         observation_type: CONTEXTUAL_ACTIVITY
                                   org_id: ABCD1234
              parent_effective_reputation: LOCAL_WHITE
       parent_effective_reputation_source: CERT
                              parent_guid: ABCD1234-0119a4da-000002e4-00000000-1d9835e27...
                              parent_hash: [list:1 item]:
                                           [0]: e6fe9a94e8686e957dbcec2b89c1c1ddcf8e75d76e9200d...
                              parent_name: c:\windows\system32\services.exe
                               parent_pid: 740
                        parent_reputation: ADAPTIVE_WHITE_LIST
                          process_cmdline: [list:1 item]:
                                           [0]: C:\Windows\system32\svchost.exe -k netsvcs -p -...
                   process_cmdline_length: [list:1 item]:
                                           [0]: 57
             process_effective_reputation: TRUSTED_WHITE_LIST
      process_effective_reputation_source: CLOUD
                             process_guid: ABCD1234-0119a4da-000006cc-00000000-1d9835e29...
                             process_hash: [list:2 items]:
                                           [0]: b7f884c1b74a263f746ee12a5f7c9f6a
                                           [1]: add683a6910abbbf0e28b557fad0ba998166394932ae2ac...
                             process_name: c:\windows\system32\svchost.exe
                              process_pid: [list:1 item]:
                                           [0]: 1740
                       process_reputation: TRUSTED_WHITE_LIST
                           process_sha256: add683a6910abbbf0e28b557fad0ba998166394932ae2ac...
                       process_start_time: 2023-05-10T16:40:42.569Z
                         process_username: [list:1 item]:
                                           [0]: NT AUTHORITY\SYSTEM
                                      ttp: [list:1 item]:
                                           [0]: RUN_UNKNOWN_APP
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Observation Facet Job


Start Facet Job

Creates an observations facet job. The results for the facet job may be requested using the job 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/ABCD1234/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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/facet_jobs \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
    "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.
Code 
from cbc_sdk.platform import ObservationFacet
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")

observations = api.select(ObservationFacet).where(process_name="chrome.exe").add_facet_field("process_name")
print(observations.results)
Result 
ObservationFacet object, bound to https://defense.conferdeploy.net.
-------------------------------------------------------------------------------

    completed: 8
    contacted: 8
       job_id: 6f8899e6-d1b4-47a5-9b32-2712c89f4569
    num_found: 186
       ranges: [list:0 items]
        terms: [list:1 item]:
               [0]: {'values': [{'total': 186, 'id': 'c:\\program f...
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Get Facet Results

Retrieves the observations facet 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}{cbc-hostname}/api/investigate/v2/orgs/{org_key}/observations/facet_jobs/{job_id}/results


Query Parameters

Parameter Required Description
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/ABCD1234/observations/facet_jobs/505bf994-a335-426e-bd8c-b2e388f977f2/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.
Request 
curl https://defense.conferdeploy.net/api/investigate/v2/orgs/ABCD1234/observations/facet_jobs/505bf994-a335-426e-bd8c-b2e388f977f2/results \
-X GET \
-H '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.
Code 
from cbc_sdk.platform import ObservationFacet
from cbc_sdk import CBCloudAPI

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile="example_profile")

observations = api.select(ObservationFacet).where(process_name="chrome.exe").add_facet_field("process_name")
print(observations.results)
Result 
ObservationFacet object, bound to https://defense.conferdeploy.net.
-------------------------------------------------------------------------------

    completed: 8
    contacted: 8
       job_id: 6f8899e6-d1b4-47a5-9b32-2712c89f4569
    num_found: 186
       ranges: [list:0 items]
        terms: [list:1 item]:
               [0]: {'values': [{'total': 186, 'id': 'c:\\program f...
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.


Last modified on November 17, 2023