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.
It is a subset of the broader EDR REST APIs. Authentication uses the same AuthToken Header as the EDR REST API.
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
API Reference
Settings - Enable and Disable Live Query
/api/v1/config_mgmt/LiveQueryEnabled
Supports PUT
The PUT request accepts the following fields in a JSON payload:
LiveQueryEnabled- Set to “true” to enable Live Query. Set to “false” to disable it.
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}}'
Run a new Live Query
/api/v1/livequery/query
Supports POST
The POST request accepts the following fields in a JSON payload:
query- SQL query to be executed,"string"group_ids- IDs of the sensor groups,[ "<integer>" ]sensor_ids- sensors that the query will be run on,[ "<integer>" ]
Response Status Codes
- 200 - Query submitted
- 404 - Zero targeted sensors support Live Query
- 412 - Live Query disabled
- 500 - Server error
Example - 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 - 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 - 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 - 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"]}'
Export results
/api/v1/livequery/export
Supports GET
GET Parameters:
format- Set to “csv” or “json” to get the output in the desired format.
Example - 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 - 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"