CB LiveOps is a real-time query and remediation solution that gives teams faster, easier access to audit and change the system state of endpoints across their organization.
CB LiveOps contains two components; Live Response and Live Query. This document refers to the Live Query REST API.
CB LiveQuery APIs are authenticated via a header token X-Auth-Token.
Required:
Custom) with permissions:
X-Auth-TokenX-Auth-Token: ABCD/1234
For more details, view CB LiveOps Authentication.
Most API routes require all three headers, however, there are exceptions.
X-Auth-Token: required in the request header. This is your authentication token.Content-Type: application/jsonorg_key: required in the API path. This is your PSC Org Key, you can view it under Settings > API Keys.Initiate a new LiveQuery search.
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs
Body
{
"device_filter": {
"device_ids": [
0
],
"device_types": [
"WINDOWS"
],
"policy_ids": [
0
]
},
"name": "test",
"notify_on_finish": false,
"sql": "required string"
}
Response
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 201 | Successfully added a live query run | application/json | View example response below |
| 400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
| 401 | Unauthorized | N/A | N/A |
| 403 | Forbidden | N/A | N/A |
| 404 | Not Found | N/A | N/A |
Request Body Schema
| Field | Description | Default | Required |
|---|---|---|---|
device_filter.device_id |
A list of device IDs to filter on | All Devices | No |
device_filter.device_types |
A list of operating systems to filter on Values: [ WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER ] |
All Operating Systems | No |
device_filter.policy_ids |
A list of policy IDs to filter on | All Policies | No |
name |
Name for your LiveQuery Run | SQL statement defined under field sql |
No |
notify_on_finish |
Receive an email notification when query is completed | false | No |
sql |
SQL of the LiveQuery Run | N/A | Yes |
Example
Request
POST https://defense-prod05/livequery/v1/orgs/ASDF12A/runs
Body
{
"notify_on_finish": false,
"name": "Autoexecs",
"device_filter": {
"device_types": [
"LINUX",
"MAC",
"WINDOWS"
]
},
"sql": "SELECT name, path, source FROM autoexec;"
}
Response
{
"template_id": null,
"org_key": "ASDF12A",
"name": "Autoexecs",
"id": "erzo7cotkasdfghjk707srcjwnjgfmiv",
"sql": "SELECT name, path, source FROM autoexec;",
"created_by": "2AG12H123A",
"create_time": "2019-06-24T21:14:02.824Z",
"status_update_time": "2019-06-24T21:14:02.824Z",
"timeout_time": "2019-07-01T21:14:02.824Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 35,
"status": "ACTIVE",
"device_filter": {
"policy_ids": null,
"device_types": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_ids": null
},
"schedule": null,
"last_result_time": null,
"total_results": 0,
"match_count": 0,
"no_match_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Returns the current status of a LiveQuery run. Users will observe the field status within the JSON response.
Request
GET <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}
Response
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 201 | Successful retrieval of query details | application/json | View example response below |
| 401 | Unauthorized | N/A | N/A |
| 403 | Forbidden | N/A | N/A |
| 404 | Not Found | N/A | N/A |
Field status options:
ACTIVE: currently running.TIMED_OUT: query timed out.COMPLETE: query completed.CANCELLED: user cancelled the LiveQuery run.Example
Request
GET https://defense-prod05/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv
Response
{
"template_id": null,
"org_key": "ASDF12A",
"name": "Autoexecs",
"id": "erzo7cotkasdfghjk707srcjwnjgfmiv",
"sql": "SELECT name, path, source FROM autoexec;",
"created_by": "2AG12H123A",
"create_time": "2019-06-24T21:14:02.824Z",
"status_update_time": "2019-06-24T21:14:02.824Z",
"timeout_time": "2019-07-01T21:14:02.824Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 35,
"status": "ACTIVE",
"device_filter": {
"policy_ids": null,
"device_types": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_ids": null
},
"schedule": null,
"last_result_time": null,
"total_results": 0,
"match_count": 0,
"no_match_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Lists LiveQuery results for a given run ID.
This route uses pagination.
Note: The response schema changes according to the osquery SQL query. The following example response is only valid for the example query listed above.
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_search
Body
{
"criteria": {
"device_id": [
0
],
"device_name": [
"string"
],
"status": [
"matched"
]
},
"query": "string",
"rows": 0,
"sort": [
{
"field": "string",
"order": "ASC"
}
],
"start": 0
}
The only requirement for the body is to be a valid JSON:
{
}
Will fetch all results.
Response
| Code | Description | Content-Type | Content |
|---|---|---|---|
| 200 | Successfully retrieved live query results | application/json | View example response below |
| 400 | The JSON body was malformed, or some part of the JSON body included an invalid value | N/A | N/A |
| 401 | Unauthorized | N/A | N/A |
| 403 | Forbidden | N/A | N/A |
| 404 | Not Found | N/A | N/A |
Request Body Schema
| Field | Description | Default | Required |
|---|---|---|---|
criteria |
A LiveQuery Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this object. A dynamic field would be a column name you’d expect to be returned as part of your live query run. For example, if you create a run that targets the users table, a dynamic field on this criteria could be username or any other column outlined in the osQuery schema. |
N/A | No |
criteria.device_id |
List of device IDs to filter on | All Devices | No |
criteria.device_name |
List of device names to filter on | All Devices | No |
criteria.status |
List of device statuses to filter on Values: [ matched, error, not_matched, not_supported, cancelled, unrecognized ] |
All Devices | No |
query |
A query to perform as part of the results search. Supports Apache Lucene syntax | N/A | No |
rows |
For pagination, how many results to return | N/A | No |
start |
For pagination, where to start retrieving results from | 0 | No |
sort |
field: SQL Response Column order: [ASC or DESC] |
N/A | No |
Example
Request
POST https://defense-prod05/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv/results/_search
Body
{
"rows": 1,
"start": 0
}
Response
{
"org_key": "ASDF12A",
"num_found": 2034,
"results": [
{
"id": "ff8eb1bdb29049cd8bdeddf7b6ff8397",
"device": {
"id": 1371955,
"name": "rspeakerWin1064",
"policy_id": 43421,
"policy_name": "bobby-test",
"os": "WINDOWS"
},
"status": "matched",
"time_received": "2019-06-20T13:11:29.180Z",
"device_message": "",
"fields": {
"name": "PolicyConverter",
"path": "\\Microsoft\\Windows\\AppID\\PolicyConverter",
"source": "scheduled_tasks"
},
"metrics": {
"osquery_current_percent_of_all_memory_": 0,
"osquery_total_user_mode_time_ms_": 859,
"current_system_memory_in_use_": 46,
"process_monitoring_rate_ms_": 500,
"peak_system_memory_in_use_mb_": 1909,
"current_write_operation_rate": 15,
"osquery_average_percent_of_memory_in_use_": 0.96,
"current_misc_io_operation_rate": 329,
"average_write_transfer_rate_kb_": 1,
"osquery_peak_percent_of_all_memory_": 1.09,
"total_cpu_current_": 15,
"total_misc_io_transfer_count_mb_": 0,
"total_read_operations": 0,
"current_system_memory_available_": 54,
"kernel_cpu_average_": 2.45,
"average_misc_io_transfer_rate_kb_": 5,
"peak_system_memory_in_use_": 46,
"peak_system_memory_available_": 54,
"current_read_operation_rate": 0,
"total_write_transfer_count_mb_": 0,
"osquery_current_memory_in_use_mb_": 0,
"average_system_memory_available_": 55,
"current_misc_io_transfer_rate_kb_": 6,
"total_cpu_average_": 3.5,
"osquery_life_time_ms_": 20568,
"osquery_total_kernel_mode_time_ms_": 2187,
"peak_system_memory_available_mb_": 2278,
"total_misc_io_operations": 5718,
"user_cpu_current_": 1.67,
"osquery_average_percent_of_all_memory_": 0.81,
"average_system_memory_available_mb_": 2221,
"current_system_memory_available_mb_": 2198,
"user_cpu_average_": 1.05,
"osquery_exit_time_unix_ms_": 1561036148221,
"average_write_operation_rate": 0,
"osquery_average_memory_in_use_mb_": 18,
"osquery_creation_time_unix_ms_": 1561036127653,
"total_read_transfer_count_mb_": 0,
"current_write_transfer_rate_kb_": 57,
"user_cpu_peak_": 12.12,
"kernel_cpu_current_": 13.33,
"total_cpu_peak_": 25,
"kernel_cpu_peak_": 21.21,
"average_system_memory_in_use_": 45,
"osquery_current_percent_of_memory_in_use_": 0,
"total_write_operations": 15,
"average_read_operation_rate": 0,
"current_system_memory_in_use_mb_": 1897,
"current_read_transfer_rate_kb_": 0,
"average_read_transfer_rate_kb_": 0,
"osquery_peak_memory_in_use_mb_": 23,
"osquery_peak_percent_of_memory_in_use_": 1.25,
"average_misc_io_operation_rate": 139,
"average_system_memory_in_use_mb_": 1873
}
}
]
}