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

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

Resources

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

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Live Query Run: {cbc-hostname}/livequery/v1/orgs/{org_key}/runs
  • Live Query Templates: {cbc-hostname}/livequery/v1/orgs/{org_key}/templates

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Live Query > Manage queries > livequery.manage, allow permission to CREATE, READ, UPDATE, DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Live Query Run: {cbc-hostname}/livequery/v1/orgs/{org_key}/runs
  • Live Query Templates: {cbc-hostname}/livequery/v1/orgs/{org_key}/templates

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Live.Query:livequery.Manage, allow permission to CREATE, READ, UPDATE, DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


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 Carbon Black Query Exchange or make an SQL Query Recommendations call to 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.

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.
1. Start Query Run
Initiate the Live Query with the example osquery sql statement, and os filter.
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
Request Headers
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
}
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.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih
Request Headers
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
}
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.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ahvf9rnfep53d5aijkyprfpcvyxyseih/results/_search
Request Headers
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": {}
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Use Live Query to find installed Firefox add-ons on endpoints in your organization. Narrow down the results by targeting specific endpoints or by utilizing any of the available search criteria. Use the gathered information to determine which endpoints might be violating some of your company-specific rules or guidelines. 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.
1. Start Query Run
Initiate the Live Query with the example osquery sql statement, and filter the results with the "WINDOWS" keyword, to get only Windows devices.
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
Request Headers
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
}
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.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/v6xbrjb7bztvapvtrg4pntydrgwhkryj
Request Headers
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
}
3. Get Results of Query
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.
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/v6xbrjb7bztvapvtrg4pntydrgwhkryj/results/_search
Request Headers
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"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Use Live Query to find installed Firefox add-ons on endpoints in your organization. Run the query automatically with the Live Query Templates at a specified recurring time. Use the gathered information to determine which endpoints might be violating some of your company-specific rules or guidelines. The workflow steps are:

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.
1. Create Template
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.
Request
POST https://defense.conferdeploy.netlivequery/v1/orgs/ABCD1234/templates
Request Headers
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"
  ]
}
2. Search Previous Query Runs
Use the id from step 1. to Search Previous Query Runs for this template between the initial run and the current moment.
Request
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/_search
Request Headers
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
    }
  ]
}
3. Analyze Changes
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.
To download or review the Carbon Black Cloud Postman collection, click here.

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.2 - https://osquery.io/schema/5.3.0

LINUX: Sensor 2.14 - https://osquery.io/schema/5.4.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.

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs

Request Body - application/json 

{
  "device_filter": {
    "deployment_type": [ "<string>" ],
    "device_id": [ <integer> ],
    "device_ids": [ <integer> ],
    "device_types": [ "<string>" ],
    "os": [ "<string>" ],
    "policy_id": [ <integer> ],
    "policy_ids": [ <integer> ]
  },
  "name": "<string>",
  "notify_on_finish": <boolean>,
  "schedule": {
    "cancellation_time": "<string>",
    "cancelled_by": "<string>",
    "next_run_time": "<string>",
    "previous_run_time": "<string>",
    "recurrence": "<string>",
    "rrule": "<string>",
    "status": "<string>",
    "timezone": "<string>"
  },
  "schema": "<string>",
  "sql": "<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 Schema below
name Name of the Live Query Run. If omitted the name will default to the SQL of the run String Default: SQL statement defined under field sql
notify_on_finish Receive an email notification when query is completed Boolean Default: false
schedule An optional configuration to rerun the query. A template_id will be included in the response. Object schedule Schema below
schema Allows one to specify the general OSQuery schema (not schema version) String OSQUERY, EXTENSION
sql REQUIRED SQL for the Live Query Run String

device_filter Schema

Field Definition Data Type Values
deployment_type A list of device deployment types to filter on String ENDPOINT, WORKLOAD, VDI, AWS
device_id A list of device IDs Array
device_types A list of device types to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
os A list of operating systems to filter on. This list is automatically set to only include the os platforms or device types that a query is compatible with Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
policy_id A list of policy IDs to filter on Array Limitation only one policy_id can be specified

schedule Schema

Field Definition Data Type Values
cancellation_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
cancelled_by String
next_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
previous_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
recurrence String MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY
rrule A recurrence rule to specify the pattern to rerun the query String See Recurrence Rules
status String ACTIVE, CANCELLED
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
401 Unauthorized
403 Forbidden
404 Not Found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "device_filter": {
    "os": [
      "WINDOWS"
    ]
  }
}
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Example run",
  "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "RW1LQSM3PZ",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:44:21.580Z",
  "status_update_time": "2022-11-28T13:44:21.580Z",
  "timeout_time": "2022-12-05T13:44:21.580Z",
  "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
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "device_filter": {
    "os": [
      "WINDOWS"
    ]
  }
}'
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Example run",
  "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "RW1LQSM3PZ",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:44:21.580Z",
  "status_update_time": "2022-11-28T13:44:21.580Z",
  "timeout_time": "2022-12-05T13:44:21.580Z",
  "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
}
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk import CBCloudAPI
from cbc_sdk import audit_remediation
from cbc_sdk.audit_remediation import Run

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile='example_profile')

query_string = "SELECT name, version FROM users JOIN firefox_addons USING (uid);"
query_object = api.select(Run).where(sql=query_string)
run = query_object.submit()

# All details of the run can be pretty printed with:
print(run)
Result 
Run object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

      active_org_devices: 3
            archive_time: None
             archived_by: None
       cancellation_time: None
            cancelled_by: None
         cancelled_count: 0
             create_time: 2022-11-29T07:39:45.183Z
              created_by: FUFNCEFBIU
            destinations: [list:1 item]:
                          [0]: LQ
           device_filter: [dict] {
                              deployment_type: None
                                    device_id: None
                                   device_ids: None
                                 device_types: [list:3 items]:
                                               [0]: WINDOWS
                                               [1]: MAC
                                               [2]: LINUX
                                           os: [list:3 items]:
                                               [0]: WINDOWS
                                               [1]: MAC
                                               [2]: LINUX
                                    policy_id: None
                                   policy_ids: None
                          }
             error_count: 0
                      id: o4zmamadnuadt7jamd0imfu28z6vznjq
       in_progress_count: 0
        last_result_time: None
             match_count: 0
                    name: None
          no_match_count: 0
       not_started_count: 3
     not_supported_count: 0
        notify_on_finish: False
                 org_key: ABCD1234
    recommended_query_id: None
                schedule: None
                  schema: None
                     sql: SELECT name, version FROM users JOIN firefox_ad...
                  status: ACTIVE
      status_update_time: 2022-11-29T07:39:45.183Z
           success_count: 0
             template_id: None
            timeout_time: 2022-12-06T07:39:45.183Z
           total_results: 0
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

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

API 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 and AWS GovCloud (US)

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
403 Forbidden
404 Resource does not exist

Examples

Request 
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Example run",
  "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "RW1LQSM3PZ",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:44:21.580Z",
  "status_update_time": "2022-11-28T13:46:08.011Z",
  "timeout_time": "2022-12-05T13:44:21.580Z",
  "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-11-28T13:45:51.379Z",
  "total_results": 63,
  "not_started_count": 0,
  "match_count": 2,
  "no_match_count": 0,
  "success_count": 2,
  "in_progress_count": 0,
  "error_count": 0,
  "not_supported_count": 0,
  "cancelled_count": 0
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Check installed browser add-ons on daily basis on Windows endpoints",
  "id": "ymbvji8yrtfvh756eppimd6ob0jusj5b",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "MQZ6LW8T6K",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:51:00.000Z",
  "status_update_time": "2022-11-28T13:54:07.387Z",
  "timeout_time": "2022-11-28T14:02:00.000Z",
  "cancellation_time": "2022-11-28T13:54:07.387Z",
  "cancelled_by": "RW1LQSM3PZ",
  "archive_time": null,
  "archived_by": null,
  "notify_on_finish": false,
  "active_org_devices": 29,
  "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": "zqbkupel7mzwqehuhlkjnwmcj38ezogj",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "MINUTELY",
    "timezone": "America/New_York",
    "rrule": "FREQ=MINUTELY;INTERVAL=15;BYSECOND=0",
    "previous_run_time": "2022-11-28T13:51:00.000Z",
    "next_run_time": "2022-11-28T14:03:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "schema": null,
  "last_result_time": null,
  "total_results": 0,
  "not_started_count": 27,
  "match_count": 0,
  "no_match_count": 0,
  "success_count": 0,
  "in_progress_count": 1,
  "error_count": 0,
  "not_supported_count": 0,
  "cancelled_count": 1
}
To download or review the Carbon Black Cloud Postman collection, click here.
Code 
from cbc_sdk import CBCloudAPI
from cbc_sdk import audit_remediation
from cbc_sdk.audit_remediation import Run

# For more information on credential handling in the SDK, see https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/authentication/
api = CBCloudAPI(profile='example_profile')

# Run the query with a specific id
run = api.select(Run, 'bxnrsex8dkzq7fw28rmdzhng6mzhczei')

# All details of the run can be pretty printed with:
print(run)
Result 
Run object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

      active_org_devices: 2
            archive_time: None
             archived_by: None
       cancellation_time: None
            cancelled_by: None
         cancelled_count: 0
             create_time: 2022-11-28T13:44:21.580Z
              created_by: RW1LQSM3PZ
            destinations: [list:1 item]:
                          [0]: LQ
           device_filter: [dict] {
                              deployment_type: None
                                    device_id: None
                                   device_ids: None
                                 device_types: [list:1 item]:
                                               [0]: WINDOWS
                                           os: [list:1 item]:
                                               [0]: WINDOWS
                                    policy_id: None
                                   policy_ids: None
                          }
             error_count: 0
                      id: bxnrsex8dkzq7fw28rmdzhng6mzhczei
       in_progress_count: 0
        last_result_time: 2022-11-28T13:45:51.379Z
             match_count: 2
                    name: Example run
          no_match_count: 0
       not_started_count: 0
     not_supported_count: 0
        notify_on_finish: False
                 org_key: ABCD1234
    recommended_query_id: None
                schedule: None
                  schema: None
                     sql: SELECT name, version, path FROM users JOIN fire...
                  status: COMPLETE
      status_update_time: 2022-11-28T13:46:08.011Z
           success_count: 2
             template_id: None
            timeout_time: 2022-12-05T13:44:21.580Z
           total_results: 63
To learn about credentials handling, capabilities, and more about the CBC Python SDK, click here.

Search Previous Query Runs

Get and search for Live Query runs.

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/_search

Request Body - application/json 

{
  "criteria": {
    "template_id": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>
}

Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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. Object criteria Schema below
query A query to perform as part of the runs search. Supports Apache Lucene syntax. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
start Row to start from when retrieving results. Limit = 10000. 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

criteria Schema

Field Definition Data Type Values
template_id Allows the templateId to be set in search criteria Array

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
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 20820,
  "results": [
    {
      "org_key": "ABCD1234",
      "name": "Check installed browser add-ons on daily basis on Windows endpoints",
      "id": "nbmfpaiiq6gnmsvlnaf6hyyczj1eaejt",
      "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
      "created_by": "MQZ6LW8T6K",
      "destinations": [
        "LQ"
      ],
      "create_time": "2022-11-28T14:15:00.000Z",
      "status_update_time": "2022-11-28T14:15:00.000Z",
      "timeout_time": "2022-11-28T14:17:00.000Z",
      "cancellation_time": null,
      "cancelled_by": null,
      "archive_time": null,
      "archived_by": null,
      "notify_on_finish": false,
      "active_org_devices": 29,
      "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": "zqbkupel7mzwqehuhlkjnwmcj38ezogj",
      "schedule": {
        "status": "ACTIVE",
        "recurrence": "MINUTELY",
        "timezone": "America/New_York",
        "rrule": "FREQ=MINUTELY;INTERVAL=15;BYSECOND=0",
        "previous_run_time": "2022-11-28T14:15:00.000Z",
        "next_run_time": "2022-11-28T14:18:00.000Z",
        "cancellation_time": null,
        "cancelled_by": null
      },
      "schema": null,
      "last_result_time": null,
      "total_results": 0,
      "not_started_count": 27,
      "match_count": 0,
      "no_match_count": 0,
      "success_count": 0,
      "in_progress_count": 2,
      "error_count": 0,
      "not_supported_count": 0,
      "cancelled_count": 0
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "rows": 1
}'
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 20848,
  "results": [
    {
      "org_key": "ABCD1234",
      "name": "Check installed browser add-ons on daily basis on Windows endpoints",
      "id": "yfnyuhx17glkkazkrianus1dfvfc1eck",
      "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
      "created_by": "MQZ6LW8T6K",
      "destinations": [
        "LQ"
      ],
      "create_time": "2022-11-28T20:51:00.000Z",
      "status_update_time": "2022-11-28T21:11:59.169Z",
      "timeout_time": "2022-11-28T21:02:00.000Z",
      "cancellation_time": null,
      "cancelled_by": null,
      "archive_time": null,
      "archived_by": null,
      "notify_on_finish": false,
      "active_org_devices": 29,
      "status": "TIMED_OUT",
      "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": "zqbkupel7mzwqehuhlkjnwmcj38ezogj",
      "schedule": {
        "status": "ACTIVE",
        "recurrence": "MINUTELY",
        "timezone": "America/New_York",
        "rrule": "FREQ=MINUTELY;INTERVAL=15;BYSECOND=0",
        "previous_run_time": "2022-11-28T20:51:00.000Z",
        "next_run_time": "2022-11-28T21:03:00.000Z",
        "cancellation_time": null,
        "cancelled_by": null
      },
      "schema": null,
      "last_result_time": "2022-11-28T20:53:22.550Z",
      "total_results": 63,
      "not_started_count": 27,
      "match_count": 2,
      "no_match_count": 0,
      "success_count": 2,
      "in_progress_count": 0,
      "error_count": 0,
      "not_supported_count": 0,
      "cancelled_count": 0
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

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.

API 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 and AWS GovCloud (US)

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, ACTIVE, COMPLETE, TIMED_OUT, ARCHIVED

Responses

Code Description Content-Type Content
200 Successfully stopped a Live Query run
400 The JSON body was malformed, or some part of the JSON body included an invalid value
401 Unauthorized
403 Forbidden
404 Resource does not exist
409 Can’t cancel a run that isn’t running

Examples

Request 
PUT https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ymbvji8yrtfvh756eppimd6ob0jusj5b/status
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "status": "CANCELLED"
}
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Check installed browser add-ons on daily basis on Windows endpoints",
  "id": "ymbvji8yrtfvh756eppimd6ob0jusj5b",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "MQZ6LW8T6K",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:51:00.000Z",
  "status_update_time": "2022-11-28T13:54:07.387Z",
  "timeout_time": "2022-11-28T14:02:00.000Z",
  "cancellation_time": "2022-11-28T13:54:07.387Z",
  "cancelled_by": "RW1LQSM3PZ",
  "archive_time": null,
  "archived_by": null,
  "notify_on_finish": false,
  "active_org_devices": 29,
  "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": "zqbkupel7mzwqehuhlkjnwmcj38ezogj",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "MINUTELY",
    "timezone": "America/New_York",
    "rrule": "FREQ=MINUTELY;INTERVAL=15;BYSECOND=0",
    "previous_run_time": "2022-11-28T13:51:00.000Z",
    "next_run_time": "2022-11-28T14:03:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "schema": null,
  "last_result_time": null,
  "total_results": 0,
  "not_started_count": 28,
  "match_count": 0,
  "no_match_count": 0,
  "success_count": 0,
  "in_progress_count": 1,
  "error_count": 0,
  "not_supported_count": 0,
  "cancelled_count": 0
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/ymbvji8yrtfvh756eppimd6ob0jusj5b/status \
-X PUT \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "status": "CANCELLED"
}'
Response Body 
{
  "org_key": "ABCD1234",
  "name": "Check installed browser add-ons on daily basis on Windows endpoints",
  "id": "ymbvji8yrtfvh756eppimd6ob0jusj5b",
  "sql": "SELECT name, version, path FROM users JOIN firefox_addons USING (uid);",
  "created_by": "MQZ6LW8T6K",
  "destinations": [
    "LQ"
  ],
  "create_time": "2022-11-28T13:51:00.000Z",
  "status_update_time": "2022-11-28T13:54:07.387Z",
  "timeout_time": "2022-11-28T14:02:00.000Z",
  "cancellation_time": "2022-11-28T13:54:07.387Z",
  "cancelled_by": "RW1LQSM3PZ",
  "archive_time": null,
  "archived_by": null,
  "notify_on_finish": false,
  "active_org_devices": 29,
  "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": "zqbkupel7mzwqehuhlkjnwmcj38ezogj",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "MINUTELY",
    "timezone": "America/New_York",
    "rrule": "FREQ=MINUTELY;INTERVAL=15;BYSECOND=0",
    "previous_run_time": "2022-11-28T13:51:00.000Z",
    "next_run_time": "2022-11-28T14:03:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "schema": null,
  "last_result_time": null,
  "total_results": 0,
  "not_started_count": 28,
  "match_count": 0,
  "no_match_count": 0,
  "success_count": 0,
  "in_progress_count": 1,
  "error_count": 0,
  "not_supported_count": 0,
  "cancelled_count": 0
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Query Run

Deletes a Live Query Run.

API 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 and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}

Responses

Code Description Content-Type Content
204 Live Query Run has been successfully deleted
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8 \
-X DELETE \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

SQL Query Recommendations

Get Tau Tin Live Query Recommendations.

API 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 and AWS GovCloud (US)

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
403 Forbidden
404 Resource does not exist

Examples

Request 
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/recommendations
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "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"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/recommendations \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "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"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Live Query Results

Search Results of Query

Get the results from a Live Query Run, download them as a CSV compressed in a ZIP, or export them asynchronously.

API 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 and AWS GovCloud (US)

Request Body - application/json 

{
  "criteria": {
    "device.id": [ <integer> ],
    "device.name": [ "<string>"],
    "device.os": [ "<string>" ],
    "device.policy_id": [ <integer> ],
    "device.policy_name": [ "<string>" ],
    "status": [ "<string>" ],
    "time_received": {
      "all_time": <boolean>,
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "fields.insert_field_name": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "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

Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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. Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
start Row to start from when retrieving results. Limit = 10000. 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

criteria Schema

Field Definition Data Type Values
device.id List of device IDs to filter on Array
device.name List of device names to filter on Array
device.os List of os’s to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
device.policy_id List of device policy IDs to filter on Array
device.policy_name List of device policy names to filter on Array
status List of statuses to filter on Array not_started, matched, error, not_matched, not_supported, cancelled, in_progress, unrecognized
time_received Time range filter on the time the results were received by Carbon Black Cloud Object 
{
  "end": "2023-10-24T00:00:00.000Z",
  "start": "2023-10-23T00:00:00.000Z"
}
fields.insert_field_name List values for a dynamic os query field returned from the run Array 
"fields.user": ["user1", "user2"]

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
401 Unauthorized
403 Forbidden
404 Not Found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei/results/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "device.id": [ 11412673 ]
  },
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 45,
  "results": [
    {
      "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
      "device": {
        "id": 11412673,
        "name": "test-machine",
        "policy_id": 7113786,
        "policy_name": "Standard",
        "os": "WINDOWS"
      },
      "status": "matched",
      "time_received": "2022-11-28T13:45:51.379Z",
      "device_message": "",
      "fields": {
        "name": "Privacy Badger",
        "path": "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-MnnxcxisBPnSXQ@jetpack.xpi",
        "version": "2021.11.23.1"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei/results/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "device.id": [ 11412673 ]
  },
  "rows": 1
}'
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 45,
  "results": [
    {
      "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
      "device": {
        "id": 11412673,
        "name": "test-machine",
        "policy_id": 7113786,
        "policy_name": "Standard",
        "os": "WINDOWS"
      },
      "status": "matched",
      "time_received": "2022-11-28T13:45:51.379Z",
      "device_message": "",
      "fields": {
        "name": "Privacy Badger",
        "path": "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-MnnxcxisBPnSXQ@jetpack.xpi",
        "version": "2021.11.23.1"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Query Results

Export the query results in CSV, JSON or Zipped CSV. Optionally the export can be executed asynchronously to prevent a gateway timeout.

For asynchronous export, to receive the actual JSON or CSV results, you need to use the Job Service API. First, use the Get Job Details to get the status of the async job, then Download Job Output call to download the actual content.

API 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 and AWS GovCloud (US)

Stream CSV File
Request 

POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv

Download CSV File
Request 

POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv&download=true

Export Query Results Asynchronously
Request 

POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/_search?format=csv&async=true

Request Body - application/json 

{
  "criteria": {
    "device.id": [ <integer> ],
    "device.name": [ "<string>"],
    "device.os": [ "<string>" ],
    "device.policy_id": [ <integer> ],
    "device.policy_name": [ "<string>" ],
    "status": [ "<string>" ],
    "time_received": {
      "all_time": <boolean>,
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "fields.insert_field_name": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>
}

Query Parameters

Field Definition Values Required
format List of format to stream.

Note: Only provide format=json if you are also using async otherwise for json use Search Results of Query		 csv, json

Default: json		 No
download Allow download into specified format (will always return a zipped CSV file) true, false

Default: false		 No
async Process the request asynchronously true, false

Default: false		 No

Body Schema

See Search Results of Query for the detail schema breakdown


Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei/results/_search?format=csv
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "device.id": [ 11412673 ]
  },
  "rows": 1
}
Response Body 
"device_id","device_name","response","sensor_msg","name","path","version"
"11412673", "test-machine", "matched", "", "Privacy Badger", "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-MnnxcxisBPnSXQ@jetpack.xpi", "2021.11.23.1"
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/bxnrsex8dkzq7fw28rmdzhng6mzhczei/results/_search?format=csv&async=true
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "device.id": [ 11412673 ]
  },
  "rows": 1
}
Response Body 
{
    "ref_url": "https://defense.conferdeploy.net/jobs/v1/orgs/ABCD1234/jobs/5932134",
    "job_id": 5932134
}
To download or review the Carbon Black Cloud Postman collection, click here.

Scroll Query Results

Fetch the results across Live Query Runs.

You can filter on a list of devices or runs to retrieve all the results. After requesting the initial results use the search_after from the response and the same search request to paginate the remaining result set. Repeat using the next search_after in the response until num_remaining is 0.

Note: The API endpoint is limited to the last 24hrs of results and sorts by time_received ascending by default

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/results/_scroll

Request Body - application/json 

{
  "criteria": {
    "device.id": [<integer>],
    "device.name": ["<string>"],
    "device.os": ["<string>"],
    "device.policy_id": [<integer>],
    "device.policy_name": ["<string>"],
    "run_id": ["<string>"],
    "status": ["<string>"],
    "time_received": {
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "fields.insert_field_name": ["<string>"]
  },
  "query": "<string>",
  "rows": <integer>,
  "search_after": "<string>"
}


Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/results/_search?format=csv&async=true


Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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.

Required: Either start time or range should be specified in the time received field of the query request OR run_id list should be specified.		 Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
search_after The offset to indicate current progress through the results.

Note: search_after only required on subsequent calls to fetch remaining results		 String

criteria Schema

Field Definition Data Type Values
device.id List of device IDs to filter on Array
device.name List of device names to filter on Array
device.os List of os’s to filter on Array WINDOWS, MAC, LINUX, OTHER
device.policy_id List of device policy IDs to filter on Array
device.policy_name List of device policy names to filter on Array
run_id List of live query run ids to filter on Array
status List of statuses to filter on Array not_started, matched, error, not_matched, not_supported, cancelled, in_progress, unrecognized
time_received Time range filter on the time the results were received by Carbon Black Cloud Object 
{
  "end": "2023-10-24T00:00:00.000Z",
  "start": "2023-10-23T00:00:00.000Z"
}


Note: You may only specify range, or start and end. range supports max of 24hrs
fields.insert_field_name List values for a dynamic os query field returned from the run Array 
"fields.user": ["user1", "user2"]

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
401 Unauthorized
403 Forbidden
404 Not Found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/results/_scroll
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "device.id": [ 11412673 ],
    "time_received": {
        "range": "-3h"
    },
  },
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 45,
  "num_remaining": 44,
  "search_after": "MTY5OTQ0OTQ2MDY1NywxODU2MzkwMSwyaGtiY3F4cjl3dG1sZmlienloYzBmcmludW44Y2I1MCwxMTY7MTY5OTM4OTkxMzAwMCwxNjk5NDc2MzEzMDAwOzEzMTU=",
  "results": [
    {
      "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
      "run_name": "Example run",
      "device": {
        "id": 11412673,
        "name": "test-machine",
        "policy_id": 7113786,
        "policy_name": "Standard",
        "os": "WINDOWS"
      },
      "status": "matched",
      "time_received": "2023-11-07T21:33:14.482Z",
      "device_message": "",
      "fields": {
        "name": "Privacy Badger",
        "path": "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-MnnxcxisBPnSXQ@jetpack.xpi",
        "version": "2021.11.23.1"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/results/_scroll \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "device.id": [ 11412673 ],
    "time_received": {
        "range": "-3h"
    },
  },
  "rows": 1
}'
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 45,
  "num_remaining": 44,
  "search_after": "MTY5OTQ0OTQ2MDY1NywxODU2MzkwMSwyaGtiY3F4cjl3dG1sZmlienloYzBmcmludW44Y2I1MCwxMTY7MTY5OTM4OTkxMzAwMCwxNjk5NDc2MzEzMDAwOzEzMTU=",
  "results": [
    {
      "id": "bxnrsex8dkzq7fw28rmdzhng6mzhczei",
      "run_name": "Example run",
      "device": {
        "id": 11412673,
        "name": "test-machine",
        "policy_id": 7113786,
        "policy_name": "Standard",
        "os": "WINDOWS"
      },
      "status": "matched",
      "time_received": "2023-11-07T21:33:14.482Z",
      "device_message": "",
      "fields": {
        "name": "Privacy Badger",
        "path": "C:\\Users\\Administrator\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\6jmaljui.default-release\\extensions\\jid1-MnnxcxisBPnSXQ@jetpack.xpi",
        "version": "2021.11.23.1"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Facets Query Results

Retrieves facets for Live Query results.

API 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 and AWS GovCloud (US)

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>" ],
    "time_received": {
      "all_time": <boolean>,
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    }
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>,
  "terms": {
    "fields": [ "<string>" ],
    "rows": <integer>
  }
}

Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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. Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
start Row to start from when retrieving results. Limit = 10000. 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
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

criteria Schema

Field Definition Data Type Values
device.id List of device IDs to filter on Array
device.name List of device names to filter on Array
device.os List of os’s to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
device.policy_id List of device policy IDs to filter on Array
device.policy_name List of device policy names to filter on Array
status List of statuses to filter on Array not_started, matched, error, not_matched, not_supported, cancelled, in_progress, unrecognized
time_received Used to specify a time range for filtering. You can either provide a fixed start and end timestamp, or a dynamic range like “-3w” or “all”.You cannot specify both a fixed start/end timestamp and a range. Time ranges will be rounded to the nearest second. Object time_received Schema below

time_received Schema

Field Definition Data Type Values
all_time Boolean
end End of the time range for a time filter (newer timestamp) String
range Relative time window for the time filter. Specified as all to retrieve results from all time, or -[quantity][units], where quantity is any integer and units is one of the allowed time units: y years, w weeks, d days, h hours, m minutes, s seconds String
start Beginning of the time range for a time filter (older timestamp) String

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
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "device.os": [ "WINDOWS" ]
  },
  "terms": {
        "fields": [ "fields.name" ],
        "rows": 5
    }
}
Response Body 
{
  "terms": [
    {
      "field": "fields.name",
      "values": [
        {
          "total": 2,
          "id": "Add-ons Search Detection",
          "name": "Add-ons Search Detection"
        }
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/_facet \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "device.os": [
      "WINDOWS"
    ]
  },
  "terms": {
        "fields": [
            "fields.name"
        ],
        "rows": 1
    }
}'
Response Body 
{
  "terms": [
    {
      "field": "fields.name",
      "values": [
        {
          "total": 2,
          "id": "Add-ons Search Detection",
          "name": "Add-ons Search Detection"
        }
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Facet Device Summary Results

Gets facets for device summaries.

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_facet

Request Body - application/json 

{
  "criteria": {
    "device.id": [ <integer> ],
    "device.name": [ "<string>" ],
    "device.os": [ <string> ],
    "device.policy_id": [ <integer> ],
    "device.policy_name": [ "<string>" ],
    "error_description": [ "<string>" ],
    "status": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>,
  "terms": {
    "fields": [ "<string>" ],
    "rows": <integer>
  }
}

Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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. Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
start Row to start from when retrieving results. Limit = 10000. 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
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

criteria Schema

Field Definition Data Type Values
device.id List of device IDs to filter on Array
device.name List of device names to filter on Array
device.os List of os’s to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
device.policy_id List of device policy IDs to filter on Array
device.policy_name List of device policy names to filter on Array
error_description Error message string to filter on Array
status List of statuses to filter on Array not_started, matched, error, not_matched, not_supported, cancelled, in_progress, unrecognized

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
401 Unauthorized
403 Forbidden
404 No Live Query run found for the specified id

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "terms": {
    "fields": [
      "device.name",
      "device.id"
    ],
    "rows": 1
  }
}
Response Body 
{
  "terms": [
    {
      "field": "device.id",
      "values": [
        {
          "total": 1,
          "id": "11412673",
          "name": "11412673"
        }
      ]
    },
    {
      "field": "device.name",
      "values": [
        {
          "total": 1,
          "id": "WinTest",
          "name": "WinTest"
        }
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_facet \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "terms": {
    "fields": [
      "device.name",
      "device.id"
    ],
    "rows": 1
  }
}'
Response Body 
{
  "terms": [
    {
      "field": "device.id",
      "values": [
        {
          "total": 1,
          "id": "11412673",
          "name": "11412673"
        }
      ]
    },
    {
      "field": "device.name",
      "values": [
        {
          "total": 1,
          "id": "WinTest",
          "name": "WinTest"
        }
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Device Summary Results

Gets device summaries from the results of a Live Query run.

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_search

Request Body - application/json 

{
  "criteria": {
    "device.id": [ <integer> ],
    "device.name": [ "<string>" ],
    "device.os": [ "<string>" ],
    "device.policy_id": [ <integer> ],
    "device.policy_name": [ "<string>" ],
    "error_description": [ "<string>" ],
    "status": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>
}

Body Schema

Field Definition Data Type Values
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this LiveQueryCriteria 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. Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows Number of rows to retrieve per search result. Limit = 10000. Integer Default: 100
start Row to start from when retrieving results. Limit = 10000. 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

criteria Schema

Field Definition Data Type Values
device.id List of device IDs to filter on Array
device.name List of device names to filter on Array
device.os List of os’s to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
device.policy_id List of device policy IDs to filter on Array
device.policy_name List of device policy names to filter on Array
error_description Error message string to filter on Array
status List of statuses to filter on Array not_started, matched, error, not_matched, not_supported, cancelled, in_progress, unrecognized

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
401 Unauthorized
403 Forbidden
404 No Live Query run found for the specified id

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 29,
  "results": [
    {
      "total_results": 18,
      "status": "matched",
      "device": {
        "id": 16801738,
        "name": "win-2016-devrel",
        "policy_id": 7113785,
        "policy_name": "Monitored",
        "os": "WINDOWS"
      },
      "error_description": "",
      "metrics": {
        "average_system_memory_in_use": 50.0,
        "osquery_creation_time_unix_ms": 1.669661202244E12,
        "total_cpu_peak": 16.67,
        "osquery_current_memory_in_use_mb": 0.0,
        "current_misc_io_operation_rate": 219.0,
        "current_misc_io_transfer_rate_kb": 1.0,
        "current_system_memory_in_use_mb": 2098.0,
        "current_write_transfer_rate_kb": 114.0,
        "total_cpu_current": 16.67,
        "total_write_operations": 87.0,
        "average_read_transfer_rate_kb": 384.0,
        "average_write_operation_rate": 43.0,
        "current_system_memory_available": 49.0,
        "osquery_life_time_ms": 898.0,
        "total_read_operations": 285.0,
        "average_misc_io_transfer_rate_kb": 9.0,
        "total_cpu_average": 16.67,
        "current_system_memory_in_use": 51.0,
        "peak_system_memory_available": 49.0,
        "kernel_cpu_average": 10.42,
        "total_write_transfer_count_mb": 0.0,
        "osquery_peak_memory_in_use_mb": 13.0,
        "average_misc_io_operation_rate": 242.0,
        "average_system_memory_in_use_mb": 2096.0,
        "average_read_operation_rate": 142.0,
        "peak_system_memory_in_use": 51.0,
        "current_read_operation_rate": 263.0,
        "osquery_total_kernel_mode_time_ms": 156.0,
        "kernel_cpu_peak": 10.42,
        "osquery_average_percent_of_memory_in_use": 0.25,
        "average_write_transfer_rate_kb": 57.0,
        "average_system_memory_available": 50.0,
        "osquery_average_memory_in_use_mb": 5.0,
        "total_read_transfer_count_mb": 0.0,
        "user_cpu_average": 6.25,
        "peak_system_memory_available_mb": 2009.0,
        "peak_system_memory_in_use_mb": 2103.0,
        "current_system_memory_available_mb": 1996.0,
        "current_read_transfer_rate_kb": 768.0,
        "kernel_cpu_current": 10.42,
        "total_misc_io_transfer_count_mb": 0.0,
        "osquery_current_percent_of_all_memory": 0.0,
        "osquery_peak_percent_of_memory_in_use": 0.66,
        "user_cpu_peak": 6.25,
        "osquery_current_percent_of_memory_in_use": 0.0,
        "average_system_memory_available_mb": 1999.0,
        "osquery_total_user_mode_time_ms": 62.0,
        "total_misc_io_operations": 492.0,
        "current_write_operation_rate": 75.0,
        "osquery_peak_percent_of_all_memory": 0.69,
        "osquery_average_percent_of_all_memory": 0.26,
        "process_monitoring_rate_ms": 500.0,
        "user_cpu_current": 6.25,
        "osquery_exit_time_unix_ms": 1.669661203142E12
      },
      "start_time": "2022-11-28T10:49:10.785Z",
      "finish_time": "2022-11-28T10:50:11.545Z",
      "update_time": "2022-11-28T10:50:24.922Z"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/runs/796g7bqc6pprul4g6xitlfljmpbf5cch/results/device_summaries/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "rows": 1
}'
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 29,
  "results": [
    {
      "total_results": 18,
      "status": "matched",
      "device": {
        "id": 16801738,
        "name": "win-2016-devrel",
        "policy_id": 7113785,
        "policy_name": "Monitored",
        "os": "WINDOWS"
      },
      "error_description": "",
      "metrics": {
        "average_system_memory_in_use": 50.0,
        "osquery_creation_time_unix_ms": 1.669661202244E12,
        "total_cpu_peak": 16.67,
        "osquery_current_memory_in_use_mb": 0.0,
        "current_misc_io_operation_rate": 219.0,
        "current_misc_io_transfer_rate_kb": 1.0,
        "current_system_memory_in_use_mb": 2098.0,
        "current_write_transfer_rate_kb": 114.0,
        "total_cpu_current": 16.67,
        "total_write_operations": 87.0,
        "average_read_transfer_rate_kb": 384.0,
        "average_write_operation_rate": 43.0,
        "current_system_memory_available": 49.0,
        "osquery_life_time_ms": 898.0,
        "total_read_operations": 285.0,
        "average_misc_io_transfer_rate_kb": 9.0,
        "total_cpu_average": 16.67,
        "current_system_memory_in_use": 51.0,
        "peak_system_memory_available": 49.0,
        "kernel_cpu_average": 10.42,
        "total_write_transfer_count_mb": 0.0,
        "osquery_peak_memory_in_use_mb": 13.0,
        "average_misc_io_operation_rate": 242.0,
        "average_system_memory_in_use_mb": 2096.0,
        "average_read_operation_rate": 142.0,
        "peak_system_memory_in_use": 51.0,
        "current_read_operation_rate": 263.0,
        "osquery_total_kernel_mode_time_ms": 156.0,
        "kernel_cpu_peak": 10.42,
        "osquery_average_percent_of_memory_in_use": 0.25,
        "average_write_transfer_rate_kb": 57.0,
        "average_system_memory_available": 50.0,
        "osquery_average_memory_in_use_mb": 5.0,
        "total_read_transfer_count_mb": 0.0,
        "user_cpu_average": 6.25,
        "peak_system_memory_available_mb": 2009.0,
        "peak_system_memory_in_use_mb": 2103.0,
        "current_system_memory_available_mb": 1996.0,
        "current_read_transfer_rate_kb": 768.0,
        "kernel_cpu_current": 10.42,
        "total_misc_io_transfer_count_mb": 0.0,
        "osquery_current_percent_of_all_memory": 0.0,
        "osquery_peak_percent_of_memory_in_use": 0.66,
        "user_cpu_peak": 6.25,
        "osquery_current_percent_of_memory_in_use": 0.0,
        "average_system_memory_available_mb": 1999.0,
        "osquery_total_user_mode_time_ms": 62.0,
        "total_misc_io_operations": 492.0,
        "current_write_operation_rate": 75.0,
        "osquery_peak_percent_of_all_memory": 0.69,
        "osquery_average_percent_of_all_memory": 0.26,
        "process_monitoring_rate_ms": 500.0,
        "user_cpu_current": 6.25,
        "osquery_exit_time_unix_ms": 1.669661203142E12
      },
      "start_time": "2022-11-28T10:49:10.785Z",
      "finish_time": "2022-11-28T10:50:11.545Z",
      "update_time": "2022-11-28T10:50:24.922Z"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Live Query Templates


Create Template

Creates a Live Query Template to perform the query on a schedule.

API 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 and AWS GovCloud (US)

Request 
POST {cbc-hostname}/livequery/v1/orgs/{org_key}/templates

Request Body - application/json 

{
  "device_filter": {
    "deployment_type": [ "<string>" ],
    "device_id": [ <integer> ],
    "device_ids": [ <integer> ],
    "device_types": [ "<string>" ],
    "os": [ "<string>" ],
    "policy_id": [ <integer> ],
    "policy_ids": [ <integer> ]
  },
  "name": "<string>",
  "notify_on_finish": <boolean>,
  "schedule": {
    "cancellation_time": "<string>",
    "cancelled_by": "<string>",
    "next_run_time": "<string>",
    "previous_run_time": "<string>",
    "recurrence": "<string>",
    "rrule": "<string>",
    "status": "<string>",
    "timezone": "<string>"
  },
  "schema": "<string>",
  "sql": "<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 Schema below
name Name of the Live Query Run. If omitted the name will default to the SQL of the run String Default: SQL statement defined under field sql
notify_on_finish Receive an email notification when query is completed Boolean Default: false
schedule An optional configuration to rerun the query. A template_id will be included in the response. Object schedule Schema below
schema Allows one to specify the general OSQuery schema (not schema version) String OSQUERY, EXTENSION
sql REQUIRED SQL for the Live Query Run String

device_filter Schema

Field Definition Data Type Values
deployment_type A list of device deployment types to filter on String ENDPOINT, WORKLOAD, VDI, AWS
device_id A list of device IDs Array
device_ids A list of device IDs Array
device_types A list of device types to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
os A list of operating systems to filter on. This list is automatically set to only include the os platforms or device types that a query is compatible with Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
policy_id A list of policy IDs to filter on Array Limitation only one policy_id can be specified
policy_ids A list of policy IDs to filter on Array

schedule Schema

Field Definition Data Type Values
cancellation_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
cancelled_by String
next_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
previous_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
recurrence String MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY
rrule A recurrence rule to specify the pattern to rerun the query String See Recurrence Rules
status String ACTIVE, CANCELLED
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
401 Unauthorized
403 Forbidden
404 Not Found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "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 Body 
{
  "id": "r9rwnw2bwjyxoxjlqmqzmveixaduzbxz",
  "name": "Example",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-11-28T21:32:08.883Z",
  "update_time": "2022-11-28T21:32:08.883Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
  "last_run_create_time": null,
  "next_run_time": "2022-11-29T18: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": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "device_filter": {
    "os": [
      "WINDOWS"
    ]
  },
  "name": "Example",
  "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 Body 
{
  "id": "r9rwnw2bwjyxoxjlqmqzmveixaduzbxz",
  "name": "Example",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-11-28T21:32:08.883Z",
  "update_time": "2022-11-28T21:32:08.883Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date, uninstall_string FROM programs;",
  "last_run_create_time": null,
  "next_run_time": "2022-11-29T18: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": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Templates

Get and search for Live Query templates.

API 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 and AWS GovCloud (US)

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>"
    }
  ],
  "start": <integer>
}

Body Schema

Field Definition Data Type Values
criteria A Live Query Template Search criteria Object criteria Schema below
query Free text search that supports case insensitive value queries. Requires whole word values. String
rows For pagination, how many results to return Integer Default: 100
start Row to start from when retrieving results. Limit = 10000 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

criteria Schema

Field Definition Data Type Values
recommended_query_id List of recommended query ids to filter on. This can be found in the output of the recommendations API Array
schedule.status List of query run statuses to filter on Array ACTIVE, CANCELLED

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
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
POST https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "sort": [
    {
      "field": "last_run_create_time",
      "order": "ASC"
    }
  ],
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 6,
  "results": [
    {
      "id": "ixgvgo4jzdeblp1att14jbku9fpiwv9n",
      "name": "Installed Programs",
      "created_by": "RW1LQSM3PZ",
      "create_time": "2022-10-04T09:31:57.494Z",
      "update_time": "2022-10-04T09:31:57.494Z",
      "notify_on_finish": false,
      "device_filter": {
        "policy_id": null,
        "os": [
          "WINDOWS"
        ],
        "device_id": null,
        "deployment_type": null,
        "policy_ids": null,
        "device_types": [
          "WINDOWS"
        ],
        "device_ids": null
      },
      "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
      "last_run_create_time": "2022-11-28T18:30:00.000Z",
      "next_run_time": "2022-11-29T18:30:00.000Z",
      "schedule": {
        "status": "ACTIVE",
        "recurrence": "DAILY",
        "timezone": "America/New_York",
        "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
        "previous_run_time": "2022-11-28T18:30:00.000Z",
        "next_run_time": "2022-11-29T18:30:00.000Z",
        "cancellation_time": null,
        "cancelled_by": null
      },
      "recommended_query_id": null,
      "schema": null,
      "destinations": [
        "LQ"
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "sort": [
    {
      "field": "last_run_create_time",
      "order": "ASC"
    }
  ],
  "rows": 1
}
Response Body 
{
  "org_key": "ABCD1234",
  "num_found": 6,
  "results": [
    {
      "id": "ixgvgo4jzdeblp1att14jbku9fpiwv9n",
      "name": "Installed Programs",
      "created_by": "RW1LQSM3PZ",
      "create_time": "2022-10-04T09:31:57.494Z",
      "update_time": "2022-10-04T09:31:57.494Z",
      "notify_on_finish": false,
      "device_filter": {
        "policy_id": null,
        "os": [
          "WINDOWS"
        ],
        "device_id": null,
        "deployment_type": null,
        "policy_ids": null,
        "device_types": [
          "WINDOWS"
        ],
        "device_ids": null
      },
      "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
      "last_run_create_time": "2022-11-28T18:30:00.000Z",
      "next_run_time": "2022-11-29T18:30:00.000Z",
      "schedule": {
        "status": "ACTIVE",
        "recurrence": "DAILY",
        "timezone": "America/New_York",
        "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
        "previous_run_time": "2022-11-28T18:30:00.000Z",
        "next_run_time": "2022-11-29T18:30:00.000Z",
        "cancellation_time": null,
        "cancelled_by": null
      },
      "recommended_query_id": null,
      "schema": null,
      "destinations": [
        "LQ"
      ]
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Template by ID

Retrieve a Live Query template (i.e. run schedule) by template id.

API 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 and AWS GovCloud (US)

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
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
GET https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "id": "ixgvgo4jzdeblp1att14jbku9fpiwv9n",
  "name": "Installed Programs",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-10-04T09:31:57.494Z",
  "update_time": "2022-10-04T09:31:57.494Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
  "last_run_create_time": "2022-11-28T18:30:00.000Z",
  "next_run_time": "2022-11-29T18:30:00.000Z",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "DAILY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "id": "zmubxsjrjh5pkfbcn9ln1wrrqggyf085",
  "name": "Installed Programs UPDATED",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-10-11T13:14:02.134Z",
  "update_time": "2022-11-28T19:52:28.692Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
  "last_run_create_time": "2022-11-28T18:30:00.000Z",
  "next_run_time": "2022-11-29T18:30:00.000Z",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "DAILY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Edit Template by ID

Edit a query template (i.e. run schedule).

API 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 and AWS GovCloud (US)

Request 
PUT {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/{template_id}

Request Body - application/json 

{
  "create_time": "<string>",
  "created_by": "<string>",
  "device_filter": {
    "deployment_type": [ "<integer>" ],
    "device_id": [ <integer> ],
    "device_ids": [ <integer> ],
    "device_types": [ "<string>" ],
    "os": [ "<string>" ],
    "policy_id": [ <integer> ],
    "policy_ids": [ <integer> ]
  },
  "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>"
  },
  "schema": "<string>",
  "sql": "<string>",
  "update_time": "<string>"
}

Body Schema

Field Definition Data Type Values
create_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
created_by String
device_filter A set of filters to limit the query to run only on matching devices Object device_filter Schema below
id String
last_run_create_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
name Name of the Live Query Run. If omitted the name will default to the SQL of the run String Default: SQL statement defined under field sql
next_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
notify_on_finish Receive an email notification when query is completed Boolean Default: false
schedule An optional configuration to rerun the query. A template_id will be included in the response. Object schedule Schema below
schema Allows one to specify the general OSQuery schema (not schema version) String OSQUERY, EXTENSION
sql REQUIRED SQL for the Live Query Run String
update_time String

device_filter Schema

Field Definition Data Type Values
deployment_type A list of device deployment types to filter on String ENDPOINT, WORKLOAD, VDI, AWS
device_id A list of device IDs Array
device_ids A list of device IDs Array
device_types A list of device types to filter on Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
os A list of operating systems to filter on. This list is automatically set to only include the os platforms or device types that a query is compatible with Array WINDOWS, ANDROID, MAC, IOS, LINUX, OTHER
policy_id A list of policy IDs to filter on Array Limitation only one policy_id can be specified
policy_ids A list of policy IDs to filter on Array

schedule Schema

Field Definition Data Type Values
cancellation_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
cancelled_by String
next_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
previous_run_time Format timestamp yyyy-MM-dd’T’HH:mm:ss.SSS’Z' String
recurrence String MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY
rrule A recurrence rule to specify the pattern to rerun the query String See Recurrence Rules
status String ACTIVE, CANCELLED
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
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
PUT https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "id": "ixgvgo4jzdeblp1att14jbku9fpiwv9n",
  "name": "Installed Programs UPDATED",
  "device_filter": {
    "policy_id": null,
    "os": [
      "LINUX"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "WEEKLY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  }
}
Response Body 
{
  "id": "zmubxsjrjh5pkfbcn9ln1wrrqggyf085",
  "name": "Installed Programs UPDATED",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-10-11T13:14:02.134Z",
  "update_time": "2022-11-28T19:52:28.692Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
  "last_run_create_time": "2022-11-28T18:30:00.000Z",
  "next_run_time": "2022-11-29T18:30:00.000Z",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "DAILY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju \
-X PUT \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "id": "ixgvgo4jzdeblp1att14jbku9fpiwv9n",
  "name": "Installed Programs UPDATED2",
  "device_filter": {
    "policy_id": null,
    "os": [
      "LINUX"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "WEEKLY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  }
}'
Response Body 
{
  "id": "zmubxsjrjh5pkfbcn9ln1wrrqggyf085",
  "name": "Installed Programs UPDATED",
  "created_by": "RW1LQSM3PZ",
  "create_time": "2022-10-11T13:14:02.134Z",
  "update_time": "2022-11-28T19:52:28.692Z",
  "notify_on_finish": false,
  "device_filter": {
    "policy_id": null,
    "os": [
      "WINDOWS"
    ],
    "device_id": null,
    "deployment_type": null,
    "policy_ids": null,
    "device_types": [
      "WINDOWS"
    ],
    "device_ids": null
  },
  "sql": "SELECT name, VERSION, install_location, install_source, publisher, install_date FROM programs;",
  "last_run_create_time": "2022-11-28T18:30:00.000Z",
  "next_run_time": "2022-11-29T18:30:00.000Z",
  "schedule": {
    "status": "ACTIVE",
    "recurrence": "DAILY",
    "timezone": "America/New_York",
    "rrule": "FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0",
    "previous_run_time": "2022-11-28T18:30:00.000Z",
    "next_run_time": "2022-11-29T18:30:00.000Z",
    "cancellation_time": null,
    "cancelled_by": null
  },
  "recommended_query_id": null,
  "schema": null,
  "destinations": [
    "LQ"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Template by ID

Delete a query schedule by id.

API 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 and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/livequery/v1/orgs/{org_key}/templates/{template_id}

Responses

Code Description Content-Type Content
204 Successfully deleted a query schedule
401 Unauthorized
403 Forbidden
404 Not found

Examples

Request 
DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/livequery/v1/orgs/ABCD1234/templates/1tmi0r8cbmivkhu77e8zg1rxij2xcgju \
-X DELETE \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

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:

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 May 13, 2024