Live Query API
Overview
Audit and Remediation 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. It contains three components; Live Response, Live Query, and Differential Analysis. This document describes the Live Query API - formerly called CB LiveOps.
With Live Query, you can ask questions of endpoints and quickly identify areas for improving security and IT hygiene by using recommended SQL queries created by Carbon Black security experts or by crafting your own. Live Query is powered by https://osquery.io, an open-source project that uses an SQLite interface.
Note: For returning users, three sub-fields inside device_filter
named: device_ids
, policy_ids
, and device_types
, have been deprecated in favor of device_id
, policy_id
, and os
, respectively.
Key Features
- Perform SQL queries on endpoints
- Get SQL query recommendations created by Carbon Black security experts
- Use Live Query Extension Tables for further insight into the Carbon Black Cloud sensor
- Use Templates to automate your security and IT hygiene further
- Fine-tune automated queries per your specific needs with the broad range of Recurrence Rules
- Support for Windows, Mac, and Linux sensors
Note: For returning users, three sub-fields inside device_filter
named: device_ids
, policy_ids
, and device_types
, have been deprecated in favor of device_id
, policy_id
, and os
, respectively.
Use Cases
- IT Hygiene
- Compliance
- Incident Response
- Vulnerability Management
Requirements
- For a full list of supported Sensor versions and OSs, click here
- All API calls require an API key with appropriate permissions see Authentication
Authentication
Use the following information for authentication, or see the Carbon Black Cloud Authentication Guide for full instructions.
- Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
- for the category Live Query > Manage queries > “livequery.manage”, allow permission to
CREATE
,READ
,UPDATE
,DELETE
(or see each call below for individual requirements)
- for the category Live Query > Manage queries > “livequery.manage”, allow permission to
- API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
- Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)
- API Routes:
- Live Query Run: {cbc-hostname}/livequery/v1/orgs/{org_key}/runs
- Live Query Templates: {cbc-hostname}/livequery/v1/orgs/{org_key}/templates
Note: when you insert your org_key, you must also remove the { } brackets.
Quick Start
Quick Start guides follow entire workflows for common scenarios using Live Query API.
You can find many community-supported, ready-to-use osquery SQL statements in the VMware Carbon Black Query Exchange or make an SQL Query Recommendations call to get hundreds of recommendations created by Carbon Black security experts.
C:\Windows
or C:\Users
directories. Use this to determine which endpoints have a file associated with a Dell firmware vulnerability. The workflow steps are:
1. Start Query Run with the osquery SQL payload in the example below, and filter the devices by Windows OS
2. Get Query by ID to check the status of the query from step 1.
3. Get Results of Query to get the results of the osquery SQL command from step 1.
Note: If you want this call to recur on a specific period automatically, use Recurrence Rules in the Start Query Run request body, or create a template with Live Query Templates. Follow the "Automatically Recurring Query" Quick Start guide for detailed workflow examples.
Initiate the Live Query with the example osquery
sql
statement, and os
filter.
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"sql": "SELECT filename, path FROM file WHERE path = 'C:\\Windows\\Temp\\dbutil_2_3.sys\\' OR path LIKE 'C:\\Users\\%\\AppData\\Local\\Temp\\dbutil_2_3.sys';",
"device_filter": {
"os": [
"WINDOWS"
]
}
}
{
"org_key": "ABCD1234",
"name": null,
"id": "ahvf9rnfep53d5aijkyprfpcvyxyseih",
"sql": "SELECT filename, path FROM file WHERE path = 'C:\\Windows\\Temp\\dbutil_2_3.sys\\' OR path LIKE 'C:\\Users\\%\\AppData\\Local\\Temp\\dbutil_2_3.sys';",
"created_by": "FUFNCEFBIU",
"destinations": [
"LQ"
],
"create_time": "2021-12-08T13:00:00.615Z",
"status_update_time": "2021-12-08T13:00:00.615Z",
"timeout_time": "2021-12-15T13:00:00.615Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 3,
"status": "ACTIVE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 3,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Check the status of the
Start Query Run
from step 1. As Get Query by ID
is asynchronous, you can repeat this call until you receive "status": "COMPLETE"
or other relevant status, in the response body.
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"org_key": "ABCD1234",
"name": null,
"id": "ahvf9rnfep53d5aijkyprfpcvyxyseih",
"sql": "SELECT filename, path FROM file WHERE path = 'C:\\Windows\\Temp\\dbutil_2_3.sys\\' OR path LIKE 'C:\\Users\\%\\AppData\\Local\\Temp\\dbutil_2_3.sys';",
"created_by": "FUFNCEFBIU",
"destinations": [
"LQ"
],
"create_time": "2021-12-08T13:00:00.615Z",
"status_update_time": "2021-12-08T13:02:09.670Z",
"timeout_time": "2021-12-15T13:00:00.615Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 3,
"status": "COMPLETE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": "2021-12-08T13:01:51.470Z",
"total_results": 0,
"not_started_count": 0,
"match_count": 0,
"no_match_count": 3,
"success_count": 3,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Get the results of the osquery SQL statement executed in step 1. In this particular example, there are no matching vulnerabilities found. Note: There are several different options for receiving/exporting the results from this call. Click here for more details.
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih/results/_search
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"criteria": {
"device.os": [
"WINDOWS"
]
}
}
{
"org_key": "ABCD1234",
"num_found": 3,
"results": [
{
"id": "ahvf9rnfep53d5aijkyprfpcvyxyseih",
"device": {
"id": 12345678,
"name": "WinTest",
"policy_id": 13897056,
"policy_name": "test2",
"os": "WINDOWS"
},
"status": "not_matched",
"time_received": "2021-12-08T12:48:15.368Z",
"device_message": "",
"fields": {}
},
{
"id": "ahvf9rnfep53d5aijkyprfpcvyxyseih",
"device": {
"id": 34567891,
"name": "sensor-d",
"policy_id": 13897056,
"policy_name": "test",
"os": "WINDOWS"
},
"status": "not_matched",
"time_received": "2021-12-08T12:46:43.996Z",
"device_message": "",
"fields": {}
},
{
"id": "ahvf9rnfep53d5aijkyprfpcvyxyseih",
"device": {
"id": 56789123,
"name": "perf-event-generator-vm",
"policy_id": 13944152,
"policy_name": "perf_Events",
"os": "WINDOWS"
},
"status": "not_matched",
"time_received": "2021-12-08T12:46:40.839Z",
"device_message": "",
"fields": {}
}
]
}
1. Start Query Run with the osquery SQL payload in the example below, and filter the devices by Windows OS
2. Get Query by ID to check the status of the query from step 1.
3. Get Results of Query to get the results of the osquery SQL command from step 1.
Note: If you want this call to recur on a specific period automatically, use Recurrence Rules in the Start Query Run request body, or create a template with Live Query Templates. Follow the "Automatically Recurring Query" Quick Start guide for detailed workflow examples.
Initiate the Live Query with the example
osquery sql
statement, and filter the results with the "WINDOWS" keyword, to get only Windows devices.
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"device_filter": {
"os": [
"WINDOWS"
]
}
}
{
"org_key": "ABCD1234",
"name": null,
"id": "v6xbrjb7bztvapvtrg4pntydrgwhkryj",
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"created_by": "FUFNCEFBIU",
"destinations": [
"LQ"
],
"create_time": "2022-01-05T12:54:15.223Z",
"status_update_time": "2022-01-05T12:54:15.223Z",
"timeout_time": "2022-01-12T12:54:15.223Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 2,
"status": "ACTIVE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 2,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Check the status of the
Start Query Run
from step 1. As Get Query by ID
is asynchronous, you can repeat this call until you receive "status": "COMPLETE"
or other relevant status, in the response body.
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/v6xbrjb7bztvapvtrg4pntydrgwhkryj
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
{
"org_key": "ABCD1234",
"name": null,
"id": "v6xbrjb7bztvapvtrg4pntydrgwhkryj",
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"created_by": "FUFNCEFBIU",
"destinations": [
"LQ"
],
"create_time": "2022-01-05T12:54:15.223Z",
"status_update_time": "2022-01-05T12:56:12.349Z",
"timeout_time": "2022-01-12T12:54:15.223Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 2,
"status": "COMPLETE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": "2022-01-05T12:55:53.719Z",
"total_results": 1,
"not_started_count": 0,
"match_count": 1,
"no_match_count": 1,
"success_count": 2,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Get the results of the osquery SQL statement executed in step 1. In this particular example, there is a "AdBlocker for YouTube" installed on endpoint with
id: 11412673
.
Note: There are several different options for receiving/exporting the results from this call. Click here for more details.
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/v6xbrjb7bztvapvtrg4pntydrgwhkryj/results/_search
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"criteria": {
"device.id": [ "11412673" ]
}
}
{
"org_key": "ABCD1234",
"num_found": 1,
"results": [
{
"id": "v6xbrjb7bztvapvtrg4pntydrgwhkryj",
"device": {
"id": 11412673,
"name": "WinTest",
"policy_id": 13897056,
"policy_name": "test-policy",
"os": "WINDOWS"
},
"status": "matched",
"time_received": "2022-01-05T12:55:53.719Z",
"device_message": "",
"fields": {
"name": "AdBlocker for YouTube™",
"path": "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-q4sG8pYhq8KGHs@jetpack.xpi",
"version": "0.3.4"
}
}
]
}
1. Create Template with the osquery SQL payload in the example below.
2. Search Previous Query Runs to check all query runs executed with the template from step 1. to this moment.
3. Analyze the changes that occurred between two query runs.
Note: Use the Differential Analysis API to compare and understand the changes between two Live Query runs with a simple API call.
Create Template, and optionally, use the
device_filter
object to limit your query to specific endpoints. This example template will perform the query on a daily basis.
POST https://defense.conferdeploy.netlivequery/v1/orgs/ABCD1234/templates
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"schedule": {
"rrule": "FREQ=DAILY;BYHOUR=7;BYMINUTE=30;BYSECOND=0",
"timezone": "America/New_York"
},
"name": "Check installed browser add-ons on daily basis on Windows endpoints",
"device_filter": {
"device_id": [ "11412673" ],
"os": [ "WINDOWS" ]
}
}
{
"id": "khnngnp2p7xnu62b9qkayc5s0fpoma6t",
"name": "Check installed browser add-ons on daily basis on Windows endpoints",
"created_by": "RW1LQSM3PZ",
"create_time": "2022-01-14T12:07:19.837Z",
"update_time": "2022-01-14T12:07:19.837Z",
"notify_on_finish": false,
"device_filter": {
"policy_id": null,
"os": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_ids": null
},
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"last_run_create_time": "2022-01-17T12:30:00.000Z",
"next_run_time": "2022-01-18T12:30:00.000Z",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=7;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2022-01-17T12:30:00.000Z",
"next_run_time": "2022-01-18T12:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
Use the
id
from step 1. to Search Previous Query Runs for this template between the initial run and the current moment.
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/_search
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
{
"criteria": {
"template_id": [ "khnngnp2p7xnu62b9qkayc5s0fpoma6t" ]
}
}
{
"org_key": "ABCD1234",
"num_found": 2,
"results": [
{
"org_key": "ABCD1234",
"name": "Check installed browser add-ons",
"id": "gxugbmhda1llpc9pmpdzy6a7c2kv1tce",
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"created_by": "RW1LQSM3PZ",
"destinations": [
"LQ"
],
"create_time": "2022-01-15T12:30:00.000Z",
"status_update_time": "2022-01-16T12:33:11.531Z",
"timeout_time": "2022-01-16T12:29:00.000Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 146,
"status": "TIMED_OUT",
"device_filter": {
"policy_id": null,
"os": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": "khnngnp2p7xnu62b9qkayc5s0fpoma6t",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=7;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2022-01-17T12:30:00.000Z",
"next_run_time": "2022-01-18T12:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"schema": null,
"last_result_time": "2022-01-15T12:32:17.232Z",
"total_results": 57,
"not_started_count": 143,
"match_count": 2,
"no_match_count": 1,
"success_count": 3,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
},
{
"org_key": "ABCD1234",
"name": "Check installed browser add-ons",
"id": "bq2yocsfqwjsdmgovp4oqdrw4ygw2heo",
"sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
"created_by": "RW1LQSM3PZ",
"destinations": [
"LQ"
],
"create_time": "2022-01-14T12:30:00.000Z",
"status_update_time": "2022-01-15T12:33:11.329Z",
"timeout_time": "2022-01-15T12:29:00.000Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 146,
"status": "TIMED_OUT",
"device_filter": {
"policy_id": null,
"os": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": "khnngnp2p7xnu62b9qkayc5s0fpoma6t",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=7;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2022-01-17T12:30:00.000Z",
"next_run_time": "2022-01-18T12:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"schema": null,
"last_result_time": "2022-01-14T12:32:55.704Z",
"total_results": 55,
"not_started_count": 143,
"match_count": 2,
"no_match_count": 1,
"success_count": 3,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
]
}
To analyze the results, first, perform either Get Results of Query or Facets Query Results on each of the query
id
from step 2. you want to explore, then compare them using your custom logic.
Optional: Use the Differential Analysis API to compare and understand the changes between two Live Query runs with a simple API call. Follow the Compare two point-in-time Snapshots guide for more detailed information.
API Calls
Create Template and Start Query Run routes support osquery validation:
- Validate the
osquery SQL
, ensuring tables are correct, table columns match, etc - Validate that the
osquery SQL
is compatible with the selected device type(s)
Device compatibility is checked against the osquery schema. The schema version depends upon the device type of the sensor. The following device schemas can be used to query for a specific device:
WINDOWS: Sensor 3.8.0.627
- https://osquery.io/schema/5.2.3
MAC: Sensor 3.7.1
- https://osquery.io/schema/5.2.3
LINUX: Sensor 2.12
- https://osquery.io/schema/4.8.0
See the Carbon Black Cloud User Guide for information about which Carbon Black Cloud sensor versions support which osquery versions.
Note: Queries will still be allowed to be added when a list of device ids
is specified in the filter and none of the corresponding devices are compatible with the query. In these cases, no results will be returned and the query will be shown as NOT_SUPPORTED
in the query result device summaries.
Note: In some cases, you will need to clear the AppData for apps that have been uninstalled for Live Query to fetch correct values.
Live Query Run
Start Query Run
Initiate a new Live Query search. Use your own custom SQL query, get SQL Query Recommendations, or browse Carbon Black’s approved user-submitted queries in the Query Exchange. To run the API call automatically on a schedule, include the schedule object in the request. Using a schedule will automatically create a new Template which you can reuse in the future.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
CREATE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.create |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs
Request Body - application/json
{
"sql": "<string>",
"device_filter": {
"device_id": [ "<long>" ],
"os": [ "<string>" ],
"policy_id": [ "<long>" ]
},
"name": "<string>",
"notify_on_finish": "<boolean>",
"schedule": {
"rrule": "<string>",
"timezone": "<string>"
}
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
device_filter |
A set of filters to limit the query to run only on matching devices | Object |
|
device_filter.device_id |
A list of device IDs | Array | N/A |
device_filter.os |
A list of operating systems | Array | WINDOWS , MAC , LINUX |
device_filter.policy_id |
A list of policy IDs | Array | Limitation only one policy_id can be specified |
name |
Name for your Live Query Run | String | Default: SQL statement defined under field sql |
notify_on_finish |
Receive an email notification when query is completed | Boolean | Default: false |
sql REQUIRED
|
SQL for the Live Query Run | String | N/A |
schedule |
An optional configuration to rerun the query. A template_id will be included in the response. |
Object |
|
schedule.rrule |
A recurrence rule to specify the pattern to rerun the query | String | See Recurrence Rules |
schedule.timezone |
The timezone that the rrule will be applied against | String | TZ Database Name ie America/New_York |
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. Query is incompatible with supported Live Query OS platforms | application/json | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not Found | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
Request Body - application/json
{
"device_filter": {
"os": [ "WINDOWS" ]
},
"name": "Example",
"notify_on_finish": true,
"schedule": {
"rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"timezone": "America/New_York"
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;"
}
Response
{
"org_key": "ABCD1234",
"name": "Example",
"id": "796g7bqc6pprul4g6xitlfljmpbf5cch",
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"created_by": "ABCDE12345",
"destinations": [
"LQ"
],
"create_time": "2020-12-04T22:28:23.739Z",
"status_update_time": "2020-12-04T22:28:23.739Z",
"timeout_time": "2020-12-05T18:29:00.000Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": true,
"active_org_devices": 1,
"status": "ACTIVE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"recommended_query_id": null,
"template_id": "3gxndaedkgu69femybsacsy7eassebsv",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2020-12-04T22:28:23.739Z",
"next_run_time": "2020-12-05T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 1,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Get Query by ID
Return the current details of a Live Query Run. Observe numerous metadata fields, such as match_count
, total_results
, or the status
field which indicates the status of all deployed queries. As this call is asynchronous, you can repeat it until you receive “status”: “COMPLETE” or other relevant status, in the response body. The full status
options are:
ACTIVE
: currently runningTIMED_OUT
: query timed outCOMPLETE
: query completedCANCELLED
: user cancelled the Live Query run with Stop Query Run call
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful retrieval of Live Query details | application/json | View example response below |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Resource does not exist | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch
Response
{
"org_key": "ABCD1234",
"name": "Example",
"id": "796g7bqc6pprul4g6xitlfljmpbf5cch",
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"created_by": "ALDS6YAEIL",
"destinations": [
"LQ"
],
"create_time": "2020-12-04T22:28:23.739Z",
"status_update_time": "2020-12-04T22:28:40.899Z",
"timeout_time": "2020-12-05T18:29:00.000Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": true,
"active_org_devices": 1,
"status": "COMPLETE",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": "3gxndaedkgu69femybsacsy7eassebsv",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2020-12-04T22:28:23.739Z",
"next_run_time": "2020-12-05T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"schema": null,
"last_result_time": "2020-12-04T22:28:39.461Z",
"total_results": 14,
"not_started_count": 0,
"match_count": 1,
"no_match_count": 0,
"success_count": 1,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Get Results of Query
Get the results from a Live Query Run, download them as a CSV compressed in a ZIP, or export them asynchronously.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search
Request Body - application/json
{
"criteria": {
"device.id": [ "<integer>" ],
"device.name": [ "<string>" ],
"device.os": [ "<string>" ],
"device.policy_id": [ "<integer>" ],
"device.policy_name": [ "<string>" ],
"status": [ "<string>" ]
},
"query": "<string>",
"rows": "<integer>",
"sort": [
{
"field": "<string>",
"order": "<string>"
},
{
"field": "<string>",
"order": "<string>"
}
],
"start": "<integer>"
}
Query Parameters
Field | Definition | Values | Required |
---|---|---|---|
format |
List of format to stream. Defaults to json |
csv , json |
No |
download |
Allow download into specified format (will always return a zipped CSV file). Defaults to false |
true , false |
No |
async |
Process the request asynchronously | true , false |
No |
Stream CSV File
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv
Note: To use the stream functionality, set the Accept: text/csv
header for the correct response to return.
Download CSV File
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv&download=true
Note: To retrieve the export as a zipped CSV file, set the Accept: application/octet-stream
header and include download=true
in the query parameters.
Export Query Results Asynchronously
You can use the Job Service API to download large sets of query results without experiencing timeout errors or receiving corrupt files.
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv&async=true
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.device.id |
List of device IDs to filter on | Array | N/A |
criteria.device.name |
List of device names to filter on | Array | N/A |
criteria.device.os |
List of os’s to filter on | Array | WINDOWS , MAC , LINUX |
criteria.device.policy_id |
List of device policy IDs to filter on | Array | N/A |
criteria.device.policy_name |
List of device policy names to filter on | Array | N/A |
criteria.status |
List of statuses to filter on | Array | ACTIVE , TIMED_OUT , COMPLETE , CANCELLED |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
rows |
For pagination, how many results to return | Integer | Default: 100 |
start |
For pagination, where to start retrieving results from | Integer | Default: 0 |
sort |
Sort is a collection of sort parameters that specify a field and order to sort the results. | Array |
order supports ASC or DESC
Supported fields: fields. + any field in the fields object of the 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 |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/erzo7cotkasdfghjk707srcjwnjgfmiv/results/_search
Request Body - application/json
{
"criteria": {
"device.os": [
"WINDOWS"
]
},
"rows": 2,
"sort": [
{
"field": "fields.install_date",
"order": "ASC"
}
],
"start": 0
}
Response
{
"org_key": "ABCD1234",
"num_found": 1,
"results": [
{
"id": "796g7bqc6pprul4g6xitlfljmpbf5cch",
"device": {
"id": 123456,
"name": "DESKTOP-8QONQUJ",
"policy_id": 2198,
"policy_name": "default",
"os": "WINDOWS"
},
"status": "matched",
"time_received": "2020-12-04T22:28:39.461Z",
"device_message": "",
"fields": {
"install_date": 20200316,
"install_location": "",
"install_source": "C:\\ProgramData\\Package Cache\\{C9DE51F8-7846-4621-815D-E8AFD3E3C0FF}v14.20.27508\\packages\\vcRuntimeAdditional_x86\\",
"name": "Microsoft Visual C++ 2019 X86 Additional Runtime - 14.20.27508",
"publisher": "Microsoft Corporation",
"uninstall_string": "MsiExec.exe /I{C9DE51F8-7846-4621-815D-E8AFD3E3C0FF}",
"version": "14.20.27508"
}
}
]
}
SQL Query Recommendations
Get Tau Tin Live Query Recommendations.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/recommendations
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful retrieval of recommended queries | application/json | View example response below |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Resource does not exist | N/A | N/A |
Example
Request
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/recommendations
Response
{
"org_key": "ABCD1234",
"num_found": 1,
"results": [
{
"link": null,
"queries": {
"description": "The Authorized_keys file for SSH is a critical file that controls which users can log into which systems.",
"interval": 86400,
"query": {
"c5df11f1dfaec0fbf0aad23e": "SELECT *\nFROM users\nJOIN authorized_keys USING (UID);"
},
"results": "Lists all relevant information about the authorized keys on the target systems.",
"supported_platforms": [
"linux",
"mac"
],
"title": "Authorized SSH Keys"
},
"type": "compliance"
}
]
}
Stop Query Run
Stop a running Live Query Run by changing its status to CANCELLED
. Note that once a Run has been stopped, it cannot be set back to ACTIVE
.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/status
Request Body - application/json
{
"status": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
status REQUIRED | Status to apply to the query | String | CANCELLED |
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully stopped a Live Query run | N/A | N/A |
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 | Resource does not exist | N/A | N/A |
409 | Can’t cancel a run that isn’t running | N/A | N/A |
Example
Request
PUT https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/wo6ryi4rq2vmxhzwlnoc5xbpfez0kw1n/status
Request Body - application/json
{
"status": "CANCELLED"
}
Response
{
"org_key": "wnexfkq7",
"name": "Example",
"id": "wo6ryi4rq2vmxhzwlnoc5xbpfez0kw1n",
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"created_by": "ALDS6YAEIL",
"destinations": [
"LQ"
],
"create_time": "2020-12-04T23:45:06.403Z",
"status_update_time": "2020-12-04T23:45:10.588Z",
"timeout_time": "2020-12-05T18:29:00.000Z",
"cancellation_time": "2020-12-04T23:45:10.588Z",
"cancelled_by": "ALDS6YAEIL",
"archive_time": null,
"archived_by": null,
"notify_on_finish": true,
"active_org_devices": 1,
"status": "CANCELLED",
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
],
"device_ids": null
},
"recommended_query_id": null,
"template_id": "dyk4moxdmssnfawqmqjn4vd7ngxnifts",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": "2020-12-04T23:45:06.403Z",
"next_run_time": "2020-12-05T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 1,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
Delete Query Run
Deletes a Live Query Run.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successful deletion of a Live Query run | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
Example
Request
DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8
Response
No Content
Facets Query Results
Retrieves facets for Live Query results.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_facet
Request Body - application/json
{
"criteria": {
"device.id": [ "<integer>" ],
"device.name": [ "<string>" ],
"device.os": [ "<string>" ],
"device.policy_id": [ "<integer>" ],
"device.policy_name": [ "<string>" ],
"status": [ "<string>" ]
},
"query": "<string>",
"terms": {
"fields": [ "<string>" ],
"rows": "<integer>"
}
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.device.id |
List of device IDs to filter on | Array | N/A |
criteria.device.name |
List of device names to filter on | Array | N/A |
criteria.device.os |
List of os’s to filter on | Array | WINDOWS , MAC , LINUX |
criteria.device.policy_id |
List of device policy IDs to filter on | Array | N/A |
criteria.device.policy_name |
List of device policy names to filter on | Array | N/A |
criteria.status |
List of statuses to filter on | Array | ACTIVE , TIMED_OUT , COMPLETE , CANCELLED |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
terms REQUIRED
|
The alert fields to facet and how many of the top entries to return. | Object |
Supported Fields: fields. + any field in the fields object of the results |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved query run facets | 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 |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/_facet
Request Body - application/json
{
"criteria": {
"device.os": [
"WINDOWS"
]
},
"terms": {
"fields": [
"fields.name"
],
"rows": 5
}
}
Response
{
"terms": [
{
"field": "fields.name",
"values": [
{
"total": 1,
"id": "Carbon Black Cloud Sensor 64-bit",
"name": "Carbon Black Cloud Sensor 64-bit"
},
{
"total": 1,
"id": "Google Chrome",
"name": "Google Chrome"
},
{
"total": 1,
"id": "Google Update Helper",
"name": "Google Update Helper"
},
{
"total": 1,
"id": "Microsoft Edge",
"name": "Microsoft Edge"
},
{
"total": 1,
"id": "Microsoft Edge Update",
"name": "Microsoft Edge Update"
}
]
}
]
}
Facet Device Summary Results
Gets facets for device summaries.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_facet
Request Body - application/json
{
"criteria": {
"device.id": [ "<long>" ],
"device.name": [ "<string>" ],
"device.os": [ "<string>" ],
"device.policy_id": [ "<long>" ],
"device.policy_name": [ "<string>" ],
"status": [ "<string>" ]
},
"query": "<string>",
"terms": {
"fields": [ "<string>" ],
"rows": "<integer>"
}
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.device.id |
List of device IDs to filter on | Array | N/A |
criteria.device.name |
List of device names to filter on | Array | N/A |
criteria.device.os |
List of os’s to filter on | Array | WINDOWS , MAC , LINUX |
criteria.device.policy_id |
List of device policy IDs to filter on | Array | N/A |
criteria.device.policy_name |
List of device policy names to filter on | Array | N/A |
criteria.status |
List of statuses to filter on | Array | ACTIVE , TIMED_OUT , COMPLETE , CANCELLED |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
terms REQUIRED
|
The alert fields to facet and how many of the top entries to return. | Object |
Supported Fields: The criteria fields listed above |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved Live Query device summary facets | 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 | No Live Query run found for the specified id | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_facet
Request Body - application/json
{
"criteria": {
"device.os": [
"WINDOWS"
]
},
"terms": {
"fields": [
"device.id"
],
"rows": 5
}
}
Response
{
"terms": [
{
"field": "device.id",
"values": [
{
"total": 1,
"id": "329219",
"name": "329219"
}
]
}
]
}
Search Device Summary Results
Gets device summaries from the results of a Live Query run.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_search
Request Body - application/json
{
"criteria": {
"device.id": [ "<long>" ],
"device.name": [ "<string>" ],
"device.os": [ "<string>" ],
"device.policy_id": [ "<long>" ],
"device.policy_name": [ "<string>" ],
"error_description": [ "<string>" ],
"status": [ "<string>" ]
},
"query": "<string>",
"rows": "<integer>",
"sort": [
{
"field": "<string>",
"order": "<string>"
},
{
"field": "<string>",
"order": "<string>"
}
],
"start": "<integer>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.device.id |
List of device IDs to filter on | Array | N/A |
criteria.device.name |
List of device names to filter on | Array | N/A |
criteria.device.os |
List of os’s to filter on | Array | WINDOWS , MAC , LINUX |
criteria.device.policy_id |
List of device policy IDs to filter on | Array | N/A |
criteria.device.policy_name |
List of device policy names to filter on | Array | N/A |
criteria.status |
List of statuses to filter on | Array | ACTIVE , TIMED_OUT , COMPLETE , CANCELLED |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
rows |
For pagination, how many results to return | Integer | Default: 100 |
start |
For pagination, where to start retrieving results from | Integer | Default: 0 |
sort |
Sort is a collection of sort parameters that specify a field and order to sort the results. | Array |
order supports ASC or DESC
Supported fields: metrics. + any field in the fields object of the results |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved Live Query device summaries | 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 | No Live Query run found for the specified id | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_search
Request Body - application/json
{
"criteria": {
"device.os": [
"WINDOWS"
]
},
"rows": 2,
"start": 0
}
Response
{
"org_key": "ABCD1234",
"num_found": 1,
"results": [
{
"total_results": 14,
"status": "matched",
"device": {
"id": 329219,
"name": "DESKTOP-8QONQUJ",
"policy_id": 2198,
"policy_name": "default",
"os": "WINDOWS"
},
"error_description": "",
"metrics": {
"average_system_memory_in_use": 29.0,
"osquery_creation_time_unix_ms": 1.607120918782E12,
"osquery_current_memory_in_use_mb": 0.0,
"total_cpu_peak": 0.0,
"current_misc_io_operation_rate": 381.0,
"current_misc_io_transfer_rate_kb": 19.0,
"current_write_transfer_rate_kb": 28.0,
"current_system_memory_in_use_mb": 2437.0,
"total_cpu_current": 0.0,
"total_write_operations": 8.0,
"average_read_transfer_rate_kb": 164.0,
"average_write_operation_rate": 8.0,
"current_system_memory_available": 71.0,
"osquery_life_time_ms": 406.0,
"total_read_operations": 44.0,
"average_misc_io_transfer_rate_kb": 19.0,
"total_cpu_average": 0.0,
"current_system_memory_in_use": 29.0,
"peak_system_memory_available": 71.0,
"kernel_cpu_average": 0.0,
"total_write_transfer_count_mb": 0.0,
"osquery_peak_memory_in_use_mb": 1.0,
"average_misc_io_operation_rate": 381.0,
"average_system_memory_in_use_mb": 2438.0,
"average_read_operation_rate": 44.0,
"peak_system_memory_in_use": 29.0,
"current_read_operation_rate": 44.0,
"osquery_total_kernel_mode_time_ms": 46.0,
"kernel_cpu_peak": 0.0,
"osquery_average_percent_of_memory_in_use": 0.03,
"average_write_transfer_rate_kb": 28.0,
"average_system_memory_available": 71.0,
"osquery_average_memory_in_use_mb": 0.0,
"total_read_transfer_count_mb": 0.0,
"user_cpu_average": 0.0,
"peak_system_memory_available_mb": 5753.0,
"peak_system_memory_in_use_mb": 2439.0,
"current_system_memory_available_mb": 5753.0,
"current_read_transfer_rate_kb": 164.0,
"kernel_cpu_current": 0.0,
"total_misc_io_transfer_count_mb": 0.0,
"osquery_current_percent_of_all_memory": 0.0,
"osquery_peak_percent_of_memory_in_use": 0.06,
"user_cpu_peak": 0.0,
"average_system_memory_available_mb": 5752.0,
"osquery_current_percent_of_memory_in_use": 0.0,
"osquery_total_user_mode_time_ms": 0.0,
"total_misc_io_operations": 387.0,
"current_write_operation_rate": 8.0,
"osquery_peak_percent_of_all_memory": 0.02,
"osquery_average_percent_of_all_memory": 0.01,
"process_monitoring_rate_ms": 500.0,
"user_cpu_current": 0.0,
"osquery_exit_time_unix_ms": 1.607120919188E12
},
"start_time": "2020-12-04T22:28:38.354Z",
"finish_time": "2020-12-04T22:28:39.461Z",
"update_time": "2020-12-04T22:28:40.886Z"
}
]
}
Search Previous Query Runs
Get and search for Live Query runs.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/_search
Request Body - application/json
{
"criteria": {
"recommended_query_id": [ "<string>" ],
"schedule.status": [ "<string>" ],
"template_id": [ "<string>" ]
},
"query": "<string>",
"rows": "<integer>",
"sort": [
{
"field": "<string>",
"order": "<string>"
},
{
"field": "<string>",
"order": "<string>"
}
],
"start": "<integer>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.recommended_query_id |
List of recommended query ids to filter on. This can be found in the output of the recommendations API | Array | N/A |
criteria.schedule.status |
List of query run statuses to filter on | Array | ACTIVE , CANCELLED |
criteria.template_id |
List of template ids that created scheduled runs | Array | N/A |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
rows |
For pagination, how many results to return | Integer | Default: 100 |
start |
For pagination, where to start retrieving results from | Integer | Default: 0 |
sort |
Sort is a collection of sort parameters that specify a field and order to sort the results. | Array |
order supports ASC or DESC
Supported fields: Any fields from the results not within an object |
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved query runs | 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 |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/_search
Request Body - application/json
{
"criteria": {
"schedule.status": [
"COMPLETE"
]
},
"rows": 2,
"sort": [
{
"field": "create_time",
"order": "ASC"
}
],
"start": 0
}
Response
{
"org_key": "ABCD1234",
"num_found": 23,
"results": [
{
"org_key": "wnexfkq7",
"name": null,
"id": "s0m51cvwm0k1yik0wycvamg1sdhlptt0",
"sql": "SELECT * FROM logged_in_users;",
"created_by": "ECQPVHWP2Y",
"destinations": [
"LQ"
],
"create_time": "2019-11-14T18:42:48.225Z",
"status_update_time": "2019-11-14T18:44:14.694Z",
"timeout_time": "2019-11-21T18:42:48.225Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 1,
"status": "COMPLETE",
"device_filter": null,
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 0,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
},
{
"org_key": "wnexfkq7",
"name": null,
"id": "dfvlzwddywxrvirhugkzpgul9ng1ag1f",
"sql": "SELECT name,",
"created_by": "ECQPVHWP2Y",
"destinations": [
"LQ"
],
"create_time": "2019-11-14T18:44:02.669Z",
"status_update_time": "2019-11-14T18:44:14.861Z",
"timeout_time": "2019-11-21T18:44:02.669Z",
"cancellation_time": null,
"cancelled_by": null,
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 1,
"status": "COMPLETE",
"device_filter": null,
"recommended_query_id": null,
"template_id": null,
"schedule": null,
"schema": null,
"last_result_time": null,
"total_results": 0,
"not_started_count": 0,
"match_count": 0,
"no_match_count": 0,
"success_count": 0,
"in_progress_count": 0,
"error_count": 0,
"not_supported_count": 0,
"cancelled_count": 0
}
]
}
Live Query Templates
Create Template
Creates a Live Query Template to perform the query on a schedule.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
CREATE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.create |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/templates
Request Body - application/json
{
"sql": "<string>",
"device_filter": {
"device_id": [ "<long>" ],
"os": [ "<string>" ],
"policy_id": [ "<long>" ]
},
"name": "<string>",
"notify_on_finish": "<boolean>",
"schedule": {
"rrule": "<string>",
"timezone": "<string>"
}
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
device_filter |
A set of filters to limit the query to run only on matching devices | Object |
|
device_filter.device_id |
A list of device IDs | Array | N/A |
device_filter.os |
A list of operating systems | Array | WINDOWS , MAC , LINUX |
device_filter.policy_id |
A list of policy IDs | Array | Limitation only one policy_id can be specified |
name REQUIRED
|
Name for your Live Query Run | String | Default: SQL statement defined under field sql |
notify_on_finish |
Receive an email notification when query is completed | Boolean | Default: false |
sql REQUIRED
|
SQL for the Live Query Run | String | N/A |
schedule REQUIRED
|
A configuration to rerun the query | Object |
|
schedule.rrule |
A recurrence rule to specify the pattern to rerun the query | String | See Recurrence Rules |
schedule.timezone |
The timezone that the rrule will be applied against | String | TZ Database Name ie America/New_York |
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. Query is incompatible with supported Live Query OS platforms | application/json | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not Found | N/A | N/A |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates
Request Body - application/json
{
"device_filter": {
"os": [
"WINDOWS"
]
},
"name": "Example",
"notify_on_finish": true,
"schedule": {
"rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"timezone": "America/New_York"
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;"
}
Response
{
"id": "1tmi0r8cbmivkhu77e8zg1rxij2xcgju",
"name": "Example",
"created_by": "ABCDE12345",
"create_time": "2020-12-07T22:57:03.395Z",
"update_time": "2020-12-07T22:57:03.395Z",
"notify_on_finish": true,
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"last_run_create_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
Search Templates
Get and search for Live Query templates.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/_search
Request Body - application/json
{
"criteria": {
"recommended_query_id": [ "<string>" ],
"schedule.status": [ "<string>" ]
},
"query": "<string>",
"rows": "<integer>",
"sort": [
{
"field": "<string>",
"order": "<string>"
},
{
"field": "<string>",
"order": "<string>"
}
],
"start": "<integer>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
criteria.recommended_query_id |
List of recommended query ids to filter on. This can be found in the output of the recommendations API | Array | N/A |
criteria.schedule.status |
List of query run statuses to filter on | Array | ACTIVE , CANCELLED |
query |
Free text search that supports case insensitive value queries. Requires whole word values. | String | N/A |
rows |
For pagination, how many results to return | Integer | Default: 100 |
start |
For pagination, where to start retrieving results from | Integer | Default: 0 |
sort |
Sort is a collection of sort parameters that specify a field and order to sort the results. | Array |
order supports ASC or DESC
Supported fields: name , sql , create_time , last_run_create_time , update_time , schedule.next_run_time |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved Live Query templates, sorted by create_time descending by default | 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 |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/_search
Request Body - application/json
{
"criteria": {
"schedule.status": [
"ACTIVE"
]
},
"rows": 2,
"sort": [
{
"field": "last_run_create_time",
"order": "ASC"
}
],
"start": 0
}
Response
{
"org_key": "ABCD1234",
"num_found": 1,
"results": [
{
"id": "1tmi0r8cbmivkhu77e8zg1rxij2xcgju",
"name": "Example",
"created_by": "ABCDE12345",
"create_time": "2020-12-07T22:57:03.395Z",
"update_time": "2020-12-07T22:57:03.395Z",
"notify_on_finish": true,
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"last_run_create_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
]
}
Get Template by ID
Retrieve a Live Query template (i.e. run schedule) by template id.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.read |
N/A - included in permission name | Prod UK |
Request
GET {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/{template_id}
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully retrieved a Live Query template | 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 |
Example
Request
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Response
{
"id": "1tmi0r8cbmivkhu77e8zg1rxij2xcgju",
"name": "Example",
"created_by": "ABCDE12345",
"create_time": "2020-12-07T22:57:03.395Z",
"update_time": "2020-12-07T22:57:03.395Z",
"notify_on_finish": true,
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"last_run_create_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"schedule": {
"status": "ACTIVE",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
Edit Template by ID
Edit a query template (i.e. run schedule).
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
UPDATE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.update |
N/A - included in permission name | Prod UK |
Request
PUT {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/{template_id}
Request Body - application/json
{
"create_time": "<string>",
"created_by": "<string>",
"device_filter": {
"device_id": [ "<long>" ],
"os": [ "<string>" ],
"policy_id": [ "<long>" ]
},
"id": "<string>",
"last_run_create_time": "<string>",
"name": "<string>",
"next_run_time": "<string>",
"notify_on_finish": "<boolean>",
"recommended_query_id": "<string>",
"schedule": {
"cancellation_time": "<string>",
"cancelled_by": "<string>",
"next_run_time": "<string>",
"previous_run_time": "<string>",
"recurrence": "<string>",
"rrule": "<string>",
"status": "<string>",
"timezone": "<string>"
},
"sql": "<string>",
"update_time": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
device_filter |
A set of filters to limit the query to run only on matching devices | Object |
|
device_filter.device_id |
A list of device IDs | Array | N/A |
device_filter.os |
A list of operating systems | Array | WINDOWS , MAC , LINUX |
device_filter.policy_id |
A list of policy IDs | Array | Limitation only one policy_id can be specified |
name REQUIRED
|
Name for your Live Query Run | String | Default: SQL statement defined under field sql |
notify_on_finish |
Receive an email notification when query is completed | Boolean | Default: false |
sql REQUIRED
|
SQL for the Live Query Run | String | N/A |
schedule REQUIRED
|
An optional configuration to rerun the query | Object |
|
schedule.rrule |
A recurrence rule to specify the pattern to rerun the query | String | See Recurrence Rules |
schedule.timezone |
The timezone that the rrule will be applied against | String | TZ Database Name ie America/New_York |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated Live Query template | 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 |
Example
Request
PUT https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Request Body - application/json
{
"id": "1tmi0r8cbmivkhu77e8zg1rxij2xcgju",
"name": "Example",
"created_by": "ABCDE12345",
"create_time": "2020-12-07T22:57:03.395Z",
"update_time": "2020-12-07T22:57:03.395Z",
"notify_on_finish": true,
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"last_run_create_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"schedule": {
"status": "CANCELLED",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": null,
"next_run_time": "2020-12-08T18:30:00.000Z",
"cancellation_time": null,
"cancelled_by": null
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
Response
{
"id": "1tmi0r8cbmivkhu77e8zg1rxij2xcgju",
"name": "Example",
"created_by": "ABCDE12345",
"create_time": "2020-12-07T22:57:03.395Z",
"update_time": "2020-12-07T23:17:31.264Z",
"notify_on_finish": true,
"device_filter": {
"policy_id": null,
"os": [
"WINDOWS"
],
"device_id": null,
"deployment_type": null,
"device_ids": null,
"policy_ids": null,
"device_types": [
"WINDOWS"
]
},
"sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
"last_run_create_time": null,
"next_run_time": null,
"schedule": {
"status": "CANCELLED",
"recurrence": "DAILY",
"timezone": "America/New_York",
"rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"previous_run_time": null,
"next_run_time": null,
"cancellation_time": "2020-12-07T23:17:31.264Z",
"cancelled_by": "ABCDE12345"
},
"recommended_query_id": null,
"schema": null,
"destinations": [
"LQ"
]
}
Delete Template by ID
Delete a query schedule by id.
RBAC Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | livequery.manage |
DELETE |
Majority of environments |
VMware Cloud Services Platform | _API.Live.Query:livequery.Manage.delete |
N/A - included in permission name | Prod UK |
Request
DELETE {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/{template_id}
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
204 | Successfully deleted a query schedule | N/A | N/A |
401 | Unauthorized | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Not found | N/A | N/A |
Example
Request
DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Response
No Content
Recurrence Rules
Live query runs can be scheduled to recur on a specified basis which consists of a recurrence rule and a timezone.
{
"rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
"timezone": "America/New_York"
}
Recurrence Rule Fields
The following tables list the fields and values that are supported for each FREQ in a rrule.
Note: Any field that supports “One or more” must use a comma delimiter i.e. 1,2,3
MINUTELY
Field | Values |
---|---|
BYSECOND |
0 |
INTERVAL |
15 or 30 |
# Minutely at every 30 minutes
RRULE:FREQ=MINUTELY;INTERVAL=30;BYSECOND=0
HOURLY
Field | Values |
---|---|
BYSECOND |
0 |
BYMINUTE |
0 |
INTERVAL |
1 |
# Hourly at every hour
RRULE:FREQ=HOURLY;INTERVAL=1;BYMINUTE=0;BYSECOND=0
DAILY
Field | Values |
---|---|
BYSECOND |
0 |
BYMINUTE |
0 or 30 |
BYHOUR |
0 to 23 |
# Daily at 1:30PM
RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0
WEEKLY
Field | Values |
---|---|
BYSECOND |
0 |
BYMINUTE |
0 or 30 |
BYHOUR |
0 to 23 |
BYDAY |
One or more: SU , MO , TU , WE , TH , FR , SA |
# Monday and Friday of the week at 2:30 AM
RRULE:FREQ=WEEKLY;BYDAY=MO,FR;BYHOUR=13;BYMINUTE=30;BYSECOND=0
MONTHLY
Note: Either (BYDAY and BYSETPOS) or BYMONTHDAY is required.
Field | Values |
---|---|
BYSECOND |
0 |
BYMINUTE |
0 or 30 |
BYHOUR |
0 to 23 |
BYDAY |
One or more: SU , MO , TU , WE , TH , FR , SA |
BYSETPOS |
-1 , 1 , 2 , 3 , 4 |
BYMONTHDAY |
One or more: 1 to 28 |
# Last Monday of the Month at 2:30 AM
RRULE:FREQ=MONTHLY;BYDAY=MO;BYSETPOS=-1;BYHOUR=2;BYMINUTE=30;BYSECOND=0
# 1st and 15th of the Month at 2:30 AM
RRULE:FREQ=DAILY;BYMONTHDAY=1,15;BYHOUR=2;BYMINUTE=30;BYSECOND=0
See the following sections of RFC 2445 for more information on Recurrence Rules:
- https://tools.ietf.org/html/rfc2445#section-4.3.10
- https://tools.ietf.org/html/rfc2445#section-4.8.5.4
Timezone Database Names
The timezone field uses the UTC timezone database names to specify which timezone to apply to the recurrence rule. A list of timezone database names can be found here
Live Query Extension Tables
Live Query extension tables are available for Windows 3.8+ sensors. These tables provide insight into the Carbon Black Cloud Windows sensor. To learn more about the extensions, click here.