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 two components; Live Response and Live Query. This document refers to 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.

Key Features

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)
  • 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 get hundreds of recommendations created by Carbon Black security experts.


Use Live Query to find files on a Windows system used for Dell Vulnerability DSA-2021-088. Look for a file called "dbutil_2_3.sys" in 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.

1. Start Query Run

Initiate the Live Query with the example osquery sql statement, and os filter.

Request
POST https://defense-eap01.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs

Request Headers
X-AUTH-TOKEN: "ABCD1234/DEFG12354"
Content-Type: "application/json"

Request Body
{
  "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"
    ]
  }
}

Response Body
{
  "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
}

2. Get Query by ID

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.

Request
GET https://defense-eap01.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih

Request Headers
X-AUTH-TOKEN: "ABCD1234/DEFG12354"

Response Body
{
  "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
}

3. Get Results of Query

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.

Request
POST https://defense-eap01.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih/results/_search

Request Headers
X-AUTH-TOKEN: "ABCD1234/DEFG12354"
Content-Type: "application/json"

Response Body
{
  "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": {}
    }
  ]
}

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 - https://osquery.io/schema/4.8.0 Previous Sensor Versions - https://osquery.io/schema/4.5.0

MAC: Sensor 3.5.3 - https://osquery.io/schema/4.8.0 Previous Sensor Versions - https://osquery.io/schema/4.1.2

LINUX: Sensor 2.12 - https://osquery.io/schema/4.8.0 Previous Sensor Versions - https://osquery.io/schema/4.1.2

See this UEX article 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.


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

Permission (.notation name) Operation(s)
livequery.manage CREATE

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 
{
  "os": [ "WINDOWS" ]
}
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 
{
  "rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
  "timezone": "America/New_York"
}
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 running
  • TIMED_OUT: query timed out
  • COMPLETE: query completed
  • CANCELLED: user cancelled the Live Query run with Stop Query Run call

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
[
  {
    "field": "fields.install_date",
    "order": ASC
  }
]
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

Permission (.notation name) Operation(s)
livequery.manage READ

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

Permission (.notation name) Operation(s)
livequery.manage UPDATE

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

Permission (.notation name) Operation(s)
livequery.manage DELETE

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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
{
  "fields": [
    "fields.name"
  ],
  "rows": 100
}
Default Rows: 20
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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
{
  "fields": [
    "fields.name"
  ],
  "rows": 100
}
Default Rows: 20
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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
[
  {
    "field": "fields.install_date",
    "order": ASC
  }
]
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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
[
  {
    "field": "fields.install_date",
    "order": ASC
  }
]
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

Permission (.notation name) Operation(s)
livequery.manage CREATE

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 
{
  "os": [ "WINDOWS" ]
}
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 
{
  "rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
  "timezone": "America/New_York"
}
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

Permission (.notation name) Operation(s)
livequery.manage READ

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 
[
  {
    "field": "fields.install_date",
    "order": ASC
  }
]
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

Permission (.notation name) Operation(s)
livequery.manage READ

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

Permission (.notation name) Operation(s)
livequery.manage UPDATE

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 
{
  "os": [ "WINDOWS" ]
}
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 
{
  "rrule": "RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
  "timezone": "America/New_York"
}
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

Permission (.notation name) Operation(s)
livequery.manage DELETE

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

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:

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.

Last modified on December 17, 2021