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"
Last modified on July 28, 2022