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.
For API authentication information, view our Carbon Black Cloud Authentication Guide.
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/json
org_key
: required in the API path. This is your Carbon Black Cloud Org Key, you can view it under Settings > API Keys.Initiate a new LiveQuery search.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
CREATE |
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs
Body
{
"device_filter": {
"device_id": [],
"os": [
"WINDOWS"
],
"policy_id": [
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 |
Contains 3 sub-filters: device_id , os , policy . This field and sub-filters are optional and by default, it will run on all devices. |
All Devices | No |
device_filter.device_id |
A list of device IDs to filter on | All Devices IDs | No |
device_filter.os |
A list of operating systems to filter on Allowed Values: [ WINDOWS , MAC , LINUX ] |
All Operating Systems | No |
device_filter.policy_id |
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 for the LiveQuery Run | N/A | Yes |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs
Body
{
"notify_on_finish": false,
"name": "Autoexecs",
"device_filter": {
"os": [
"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_id": null,
"os": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_id": 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.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
READ |
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.conferdeploy.net/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_id": null,
"os": [
"MAC",
"LINUX",
"WINDOWS"
],
"device_id": 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.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
READ |
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_search
Body
{
"criteria": {
"device.id": [
0
],
"device.name": [
"string"
],
"fields.type": [
"active"
]
},
"query": "string",
"rows": 0,
"sort": [
{
"fields.field": "string",
"fields.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 |
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.conferdeploy.net/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
}
}
]
}
Stop a LiveQuery Run that is running.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
UPDATE |
Request
PUT <psc-hostname>/livequery/orgs/{org_key}/runs/{id}/status
Request Body
{
"status": "CANCELLED"
}
Responses
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully stopped 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 |
409 | The query is not currently running | application/json | N/A |
Request Body Schema
Field | Description | Default | Required |
---|---|---|---|
status | Status to apply to the query | CANCELLED | Yes |
Example
Request
PUT https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8/status
Body
{
"status": "CANCELLED"
}
Response
{
"template_id": null,
"org_key": "ASDF12A",
"name": null,
"id": "nnk1idf2xz3cit8unv3usfwyzmdqj8",
"sql": "select * from logged_in_users;",
"created_by": "L97AM9ECAU",
"create_time": "2019-07-24T20:19:16.654Z",
"status_update_time": "2019-07-24T20:19:28.762Z",
"timeout_time": "2019-07-31T20:19:16.654Z",
"cancellation_time": "2019-07-24T20:19:28.762Z",
"cancelled_by": "L97AM9ECAU",
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 12,
"status": "CANCELLED",
"device_filter": 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
}
Delete a LiveQuery Run.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
DELETE |
Request
DELETE <psc-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/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8
Response
Response Code: 200
.
Get filters of results specified by criteria.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
READ |
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_facet
Body
{
"criteria": {
"additionalProp1": [
"string"
],
"additionalProp2": [
"string"
],
"additionalProp3": [
"string"
]
},
"query": "string",
"terms": {
"fields": [
"string"
],
"rows": 0
}
}
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 |
Request Body Schema
Field | Description | Default | Required |
---|---|---|---|
criteria.additionalProperties | Map of criteria filter to get facets for | N/A | No |
query | Free text search that supports case insensitive value queries. Requires whole word values. | N/A | No |
terms.fields | Facet terms to retrieve | N/A | Yes |
terms.rows | Number of rows to retrieve per facet search result | 20 | No |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/_facet
Body
{
"criteria": {
"fields.type": [
"disconnected"
]
},
"terms": {
"fields": [
"id",
"status"
]
}
}
Response
{
"terms": [
{
"field": "id",
"values": [
{
"total": 1,
"id": "0f70de14281e4c2b9ae8dc0b3d7a6080",
"name": "0f70de14281e4c2b9ae8dc0b3d7a6080"
},
{
"total": 1,
"id": "29e6a25bdbef4cae88dcc2d4ee63284d",
"name": "29e6a25bdbef4cae88dcc2d4ee63284d"
},
{
"total": 1,
"id": "43526614397a449e965432970ea1ea76",
"name": "43526614397a449e965432970ea1ea76"
},
{
"total": 1,
"id": "46d02871c4cc42c78aed28509a7a28c4",
"name": "46d02871c4cc42c78aed28509a7a28c4"
},
{
"total": 1,
"id": "62a8f521c25d4033adf312bcf230d382",
"name": "62a8f521c25d4033adf312bcf230d382"
},
{
"total": 1,
"id": "b33b32fd52ce47a6aad286c08d534698",
"name": "b33b32fd52ce47a6aad286c08d534698"
},
{
"total": 1,
"id": "c72df6a9c2c94638b4f4e669b139b1d4",
"name": "c72df6a9c2c94638b4f4e669b139b1d4"
}
]
},
{
"field": "status",
"values": [
{
"total": 7,
"id": "matched",
"name": "matched"
}
]
}
]
}
Get facets for device summaries
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
READ |
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_facet
Body
{
"criteria": {
"additionalProp1": [
"string"
],
"additionalProp2": [
"string"
],
"additionalProp3": [
"string"
]
},
"query": "string",
"terms": {
"fields": [
"string"
],
"rows": 0
}
}
Response
{
"terms": [
{
"field": "string",
"values": [
{
"id": "string",
"name": "string",
"total": 0
}
]
}
]
}
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 | Not found | N/A | N/A |
Request Body Schema
Field | Description | Default | Required |
---|---|---|---|
criteria.additionalProperties | Map of criteria filter to get facets for | N/A | No |
query | Free text search that supports case insensitive value queries. Requires whole word values. | N/A | No |
terms.fields | Device summary fields to filter results on | N/A | Yes |
terms.rows | Number of rows to retrieve per facet search result | 20 | No |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/device_summaries/_facet
Body
{
"criteria": {
"policy_name": [
"BERKLY PC Standard"
]
},
"terms": {
"fields": [
"id",
"status",
"policy_name"
]
}
}
Response
{
"terms": [
{
"field": "status",
"values": [
{
"total": 2,
"id": "matched",
"name": "matched"
}
]
},
{
"field": "id",
"values": [
{
"total": 1,
"id": "Slohuq4XaymlAqrJcZK9JB3OAbsZ8fYJ",
"name": "Slohuq4XaymlAqrJcZK9JB3OAbsZ8fYJ"
},
{
"total": 1,
"id": "ruRn8k7aure3OQX9DmNGMDBJUvfrIl6b",
"name": "ruRn8k7aure3OQX9DmNGMDBJUvfrIl6b"
}
]
}
]
}
Get all LiveQuery results for a specific organization.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
livequery.manage |
READ |
Request
POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/_search
Body
{
"query": "string",
"rows": 0,
"sort": [
{
"field": "archive_time",
"order": "ASC"
}
],
"start": 0
}
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 |
Request Body Schema
Field | Description | Default | Required |
---|---|---|---|
query | Free text search that supports case insensitive value queries. Requires whole word values. | N/A | No |
rows | For paging, how many runs to return | 20 | No |
sort.field | Field to sort results on | N/A | No |
sort.order | Return runs in ascending (ASC) or descending (DESC) order. | ASC | No |
start | For paging, where to start retrieving runs from | 0 | No |
Example
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/_search
Body
{
"query": "efuykoprimz74d4ys5ugj5unqfphxpuz",
"rows": "25",
"sort": [
{
"field": "archive_time",
"order": "ASC"
}
],
"start": "0"
}
Response
{
"org_key": "ASDF12A",
"num_found": 1,,
"results": [
{
"template_id": null,
"org_key": "ASDF12A",
"name": null,
"id": "efuykoprimz74d4ys5ugj5unqfphxpuz",
"sql": "select * from logged_in_users;",
"created_by": "L97AM9ECAU",
"create_time": "2019-07-24T20:19:16.654Z",
"status_update_time": "2019-07-24T20:19:28.762Z",
"timeout_time": "2019-07-31T20:19:16.654Z",
"cancellation_time": "2019-07-24T20:19:28.762Z",
"cancelled_by": "L97AM9ECAU",
"archive_time": null,
"archived_by": null,
"notify_on_finish": false,
"active_org_devices": 12,
"status": "CANCELLED",
"device_filter": 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
}
]
}