Live Query API

Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.

EDR Live Query exposes an operating system as a high-performance relational database, which enables you to write SQL-based queries that explore operating system data. These queries allow you to gain a better understanding of your environment, analyze security vulnerabilities, and identify anomalies, like unencrypted disks or processes running without a binary on disk.

Live Query is based on osquery, which is an open-source project that uses a SQLite interface. The Live Query API allows you to execute queries against the operating system via API call and analyze the results outside of the EDR console.

The Live Query API is available in EDR Server versions 7.7 and above.

For information about the Live Query functionality, and how to run queries through the Carbon Black EDR console, see the Live Query topic in the EDR User Guide. This is the User Guide for EDR 7.7.

Requirements

  • EDR Server 7.2.0+
  • EDR Windows Sensor 7.1.0+

Limitations

  • Live Query is only available for Windows operating systems
  • Limit of querying a maximum of 200 sensors at a time
  • Only one query can be run at a time. If a new query is run, all previous query results are discarded. The Export Results call includes the currently active query so can be used to determine the last submitted query.

API Reference

Settings - Enable and Disable Live Query

Live Query is disabled by default. Carbon Black EDR Global Administrators and Carbon Black Hosted EDR Administrators can enable or disable Live Query.

Request

PUT {{hostname}}/api/v1/config_mgmt/LiveQueryEnabled

Request Body - application/json 

{
    "LiveQueryEnabled": {
        "value": "<boolean>"
}

Body Schema

Field Definition Data Type Values
LiveQueryEnabled Set to “true” to enable Live Query. Set to “false” to disable it. boolean true, false

Response

Code Description Content-Type Content
200 Successfully set whether Live Query is enabled or not application/json View example response below
401 Unauthorized N/A N/A
403 Unauthorized N/A N/A

Example Request - Enable Live Query

curl "https://$SERVER/api/v1/config_mgmt/LiveQueryEnabled" \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"LiveQueryEnabled": {"value": true}}'

Example Request - Disable Live Query

curl "https://$SERVER/api/v1/config_mgmt/LiveQueryEnabled" \
-X PUT \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"LiveQueryEnabled": {"value": false}}'

Example Response - Disable Live Query

{
    "LiveQueryEnabled": {
        "value": false
    }
}

Run a new Live Query

A live query can be run on specified sensors or a sensor group to retrieve information exposed by osquery.

You can run only one query at a time. If you run a new query, previous query results are discarded.

Request

POST {{hostname}}/api/v1/livequery/query

Request Body - application/json 

{
    "query": "<string>",
    "sensor_ids": ["<string>"],
    "group_ids":["<string>"]
}

Body Schema

Field Definition Data Type Values
query REQUIRED SQL query to be executed string N/A
group_ids IDs of the sensor groups. Either group_ids or sensor_ids must be included. Array 
[ "string" ]
sensor_ids Sensors that the query will be run on. Id is available on the Sensor Details page. Either group_ids or sensor_ids must be included. Array 
[ "string" ]

Response

Code Description Content-Type Content
200 Query submitted application/json View example response below
404 Zero targeted sensors support Live Query NA 404 Not Found
412 Live Query disabled 412 Precondition Failed
Precondition Failed
Feature is disabled
500 Server error NA NA

Example Request - Query one sensor group

curl "https://$SERVER/api/v1/livequery/query" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"query":"SELECT * FROM users WHERE UID >= 500;","group_ids":["2"]}'

Example Request - Query multiple sensor groups

curl "https://$SERVER/api/v1/livequery/query" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"query":"SELECT * FROM users WHERE UID >= 500;","group_ids":["2", "3"]}'

Example Request - Query one sensor

curl "https://$SERVER/api/v1/livequery/query" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"query":"SELECT * FROM users WHERE UID >= 500;","sensor_ids":["2"]}'

Example Request - Query multiple sensors

curl "https://$SERVER/api/v1/livequery/query" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-d'{"query":"SELECT * FROM users WHERE UID >= 500;","sensor_ids":["2", "3"]}'

Example - Response

{
    "id": "e4f941e7-2cad-4630-b913-5f618572563a"
}


Response Schema

Field Definition Data Type
id Unique identifier for the submitted query run. Can be used to correlate the query results with request. If another query has been started after the one you ran, the results will be for the most recently started query. string

Export results

Retrieve the results of the last query in json or csv format.

Results are included for all sensors that returned results and that the user is authorised to access.

Request

GET {{hostname}}/api/v1/livequery/export

Query Parameters

Field Definition Values Required
format Set the desired output format. Defaults to json. csv, json No

Response

Code Description Content-Type Content
200 Successfully retrieved Live Query results application/json View example response below
404 Zero targeted sensors support Live Query NA 404 Not Found
412 Live Query disabled 412 Precondition Failed
Precondition Failed
Feature is disabled
500 Server error NA NA

Example Request - Export results as csv

curl "https://$SERVER/api/v1/livequery/export?format=csv" \
TBC: -X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN"

Example Response - Export results as csv

cb_error_message,cb_query_status,cb_sensor_id,cb_sensor_name,cb_time_received,version
,success,3,PS-WIN-10-SENSO,2022-08-26 21:49:59.964084+00:00,4.6.0.2

Example Request - Export results as json

curl "https://$SERVER/api/v1/livequery/export?format=json" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-Auth-Token: $AUTH_TOKEN"

Example Response - Export results as json

{
    "query_id": "3e899e4d-8082-4ab6-8a6c-630af106a97b",
    "query": "SELECT version FROM osquery_info;",
    "results": [
        {
            "cb_sensor_id": 3,
            "cb_sensor_name": "PS-WIN-10-SENSO",
            "cb_time_received": "2022-08-26 21:49:59.964084+00:00",
            "cb_query_status": "success",
            "cb_error_message": "",
            "version": "4.6.0.2"
        }
    ]
}


Response Schema

Field Definition Data Type
cb_sensor_name User friendly name string
cb_time_received Time when the sensor’s response was received on the Carbon Black server string
cb_query_status Status of the currently executing query success
truncated
error - sensor’s results are incorrectly formatted
cb_error_message Additional detail when the query status is error string
version This is dependent on the query submitted. Fields as defined in the query will be included in the response. variable

Give Feedback

Use this form to give us feedback about this site or any of the documentation.


Last modified on September 8, 2022