CB LiveOps REST API

Version: v1

Introduction

CB LiveOps is a real-time query and remediation solution that gives teams faster, easier access to audit and change the system state of endpoints across their organization.

CB LiveOps contains two components; Live Response and Live Query. This document refers to the Live Query REST API.

For API authentication information, view our Carbon Black Cloud Authentication Guide.

Common Headers/Parameters

Most API routes require all three headers, however, there are exceptions.

  1. X-Auth-Token: required in the request header. This is your authentication token.
  2. Content-Type: application/json
  3. org_key: required in the API path. This is your Carbon Black Cloud Org Key, you can view it under Settings > API Keys.

Start Query Run

Initiate a new LiveQuery search.

RBAC Permissions Required

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

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs

Body 

{
  "device_filter": {
    "device_id": [],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "name": "test",
  "notify_on_finish": false,
  "sql": "required string"
}

Response

Code Description Content-Type Content
201 Successfully added a live query run application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy. This field and sub-filters are optional and by default, it will run on all devices. All Devices No
device_filter.device_id A list of device IDs to filter on All Devices IDs No
device_filter.os A list of operating systems to filter on
Allowed Values: [ WINDOWS, MAC, LINUX]		 All Operating Systems No
device_filter.policy_id A list of policy IDs to filter on All Policies No
name Name for your LiveQuery Run SQL statement defined under field sql No
notify_on_finish Receive an email notification when query is completed false No
sql SQL for the LiveQuery Run N/A Yes

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs

Body 

{
    "notify_on_finish": false,
    "name": "Autoexecs",
    "device_filter": {
        "os": [
            "LINUX",
            "MAC",
            "WINDOWS"
        ]
    },
    "sql": "SELECT name, path, source FROM autoexec;"
}

Response 

{
    "template_id": null,
    "org_key": "ASDF12A",
    "name": "Autoexecs",
    "id": "erzo7cotkasdfghjk707srcjwnjgfmiv",
    "sql": "SELECT name, path, source FROM autoexec;",
    "created_by": "2AG12H123A",
    "create_time": "2019-06-24T21:14:02.824Z",
    "status_update_time": "2019-06-24T21:14:02.824Z",
    "timeout_time": "2019-07-01T21:14:02.824Z",
    "cancellation_time": null,
    "cancelled_by": null,
    "archive_time": null,
    "archived_by": null,
    "notify_on_finish": false,
    "active_org_devices": 35,
    "status": "ACTIVE",
    "device_filter": {
        "policy_id": null,
        "os": [
            "MAC",
            "LINUX",
            "WINDOWS"
        ],
        "device_id": null
    },
    "schedule": null,
    "last_result_time": null,
    "total_results": 0,
    "match_count": 0,
    "no_match_count": 0,
    "error_count": 0,
    "not_supported_count": 0,
    "cancelled_count": 0
}

Get Query Run Status

Returns the current status of a LiveQuery run. Users will observe the field status within the JSON response.

RBAC Permissions Required

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

Request

GET <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}

Response

Code Description Content-Type Content
201 Successful retrieval of query details application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Field status options:

  • ACTIVE: currently running.
  • TIMED_OUT: query timed out.
  • COMPLETE: query completed.
  • CANCELLED: user cancelled the LiveQuery run.

Example

Request

GET https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv

Response 

{
    "template_id": null,
    "org_key": "ASDF12A",
    "name": "Autoexecs",
    "id": "erzo7cotkasdfghjk707srcjwnjgfmiv",
    "sql": "SELECT name, path, source FROM autoexec;",
    "created_by": "2AG12H123A",
    "create_time": "2019-06-24T21:14:02.824Z",
    "status_update_time": "2019-06-24T21:14:02.824Z",
    "timeout_time": "2019-07-01T21:14:02.824Z",
    "cancellation_time": null,
    "cancelled_by": null,
    "archive_time": null,
    "archived_by": null,
    "notify_on_finish": false,
    "active_org_devices": 35,
    "status": "ACTIVE",
    "device_filter": {
        "policy_id": null,
        "os": [
            "MAC",
            "LINUX",
            "WINDOWS"
        ],
        "device_id": null
    },
    "schedule": null,
    "last_result_time": null,
    "total_results": 0,
    "match_count": 0,
    "no_match_count": 0,
    "error_count": 0,
    "not_supported_count": 0,
    "cancelled_count": 0
}

Get Query Run Results

Lists LiveQuery results for a given run ID.

This route uses pagination.

Note: The response schema changes according to the osquery SQL query. The following example response is only valid for the example query listed above.

RBAC Permissions Required

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

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_search

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "fields.type": [
      "active"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "fields.field": "string",
      "fields.order": "ASC"
    }
  ],
  "start": 0
}

The only requirement for the body is to be a valid JSON:

{

}

Will fetch all results.

Response

Code Description Content-Type Content
200 Successfully retrieved live query results application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Request Body Schema

Field Description Default Required
criteria A LiveQuery Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this object. A dynamic field would be a column name you’d expect to be returned as part of your live query run. For example, if you create a run that targets the users table, a dynamic field on this criteria could be username or any other column outlined in the osQuery schema. N/A No
criteria.device_id List of device IDs to filter on All Devices No
criteria.device_name List of device names to filter on All Devices No
query A query to perform as part of the results search. Supports Apache Lucene syntax N/A No
rows For pagination, how many results to return N/A No
start For pagination, where to start retrieving results from 0 No
sort field: SQL Response Column
order: [ASC or DESC]		 N/A No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv/results/_search

Body 

{
    "rows": 1,
    "start": 0
}

Response 

{
    "org_key": "ASDF12A",
    "num_found": 2034,
    "results": [
        {
            "id": "ff8eb1bdb29049cd8bdeddf7b6ff8397",
            "device": {
                "id": 1371955,
                "name": "rspeakerWin1064",
                "policy_id": 43421,
                "policy_name": "bobby-test",
                "os": "WINDOWS"
            },
            "status": "matched",
            "time_received": "2019-06-20T13:11:29.180Z",
            "device_message": "",
            "fields": {
                "name": "PolicyConverter",
                "path": "\\Microsoft\\Windows\\AppID\\PolicyConverter",
                "source": "scheduled_tasks"
            },
            "metrics": {
                "osquery_current_percent_of_all_memory_": 0,
                "osquery_total_user_mode_time_ms_": 859,
                "current_system_memory_in_use_": 46,
                "process_monitoring_rate_ms_": 500,
                "peak_system_memory_in_use_mb_": 1909,
                "current_write_operation_rate": 15,
                "osquery_average_percent_of_memory_in_use_": 0.96,
                "current_misc_io_operation_rate": 329,
                "average_write_transfer_rate_kb_": 1,
                "osquery_peak_percent_of_all_memory_": 1.09,
                "total_cpu_current_": 15,
                "total_misc_io_transfer_count_mb_": 0,
                "total_read_operations": 0,
                "current_system_memory_available_": 54,
                "kernel_cpu_average_": 2.45,
                "average_misc_io_transfer_rate_kb_": 5,
                "peak_system_memory_in_use_": 46,
                "peak_system_memory_available_": 54,
                "current_read_operation_rate": 0,
                "total_write_transfer_count_mb_": 0,
                "osquery_current_memory_in_use_mb_": 0,
                "average_system_memory_available_": 55,
                "current_misc_io_transfer_rate_kb_": 6,
                "total_cpu_average_": 3.5,
                "osquery_life_time_ms_": 20568,
                "osquery_total_kernel_mode_time_ms_": 2187,
                "peak_system_memory_available_mb_": 2278,
                "total_misc_io_operations": 5718,
                "user_cpu_current_": 1.67,
                "osquery_average_percent_of_all_memory_": 0.81,
                "average_system_memory_available_mb_": 2221,
                "current_system_memory_available_mb_": 2198,
                "user_cpu_average_": 1.05,
                "osquery_exit_time_unix_ms_": 1561036148221,
                "average_write_operation_rate": 0,
                "osquery_average_memory_in_use_mb_": 18,
                "osquery_creation_time_unix_ms_": 1561036127653,
                "total_read_transfer_count_mb_": 0,
                "current_write_transfer_rate_kb_": 57,
                "user_cpu_peak_": 12.12,
                "kernel_cpu_current_": 13.33,
                "total_cpu_peak_": 25,
                "kernel_cpu_peak_": 21.21,
                "average_system_memory_in_use_": 45,
                "osquery_current_percent_of_memory_in_use_": 0,
                "total_write_operations": 15,
                "average_read_operation_rate": 0,
                "current_system_memory_in_use_mb_": 1897,
                "current_read_transfer_rate_kb_": 0,
                "average_read_transfer_rate_kb_": 0,
                "osquery_peak_memory_in_use_mb_": 23,
                "osquery_peak_percent_of_memory_in_use_": 1.25,
                "average_misc_io_operation_rate": 139,
                "average_system_memory_in_use_mb_": 1873
            }
        }
    ]
}

Stop Query Run

Stop a LiveQuery Run that is running.

RBAC Permissions Required

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

Request

PUT <psc-hostname>/livequery/orgs/{org_key}/runs/{id}/status

Request Body 

{
    "status": "CANCELLED"
}

Responses

Code Description Content-Type Content
200 Successfully stopped a live query run application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
409 The query is not currently running application/json N/A

Request Body Schema

Field Description Default Required
status Status to apply to the query CANCELLED Yes

Example

Request

PUT https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8/status

Body

{
    "status": "CANCELLED"
}

Response

{
    "template_id": null,
    "org_key": "ASDF12A",
    "name": null,
    "id": "nnk1idf2xz3cit8unv3usfwyzmdqj8",
    "sql": "select * from logged_in_users;",
    "created_by": "L97AM9ECAU",
    "create_time": "2019-07-24T20:19:16.654Z",
    "status_update_time": "2019-07-24T20:19:28.762Z",
    "timeout_time": "2019-07-31T20:19:16.654Z",
    "cancellation_time": "2019-07-24T20:19:28.762Z",
    "cancelled_by": "L97AM9ECAU",
    "archive_time": null,
    "archived_by": null,
    "notify_on_finish": false,
    "active_org_devices": 12,
    "status": "CANCELLED",
    "device_filter": null,
    "schedule": null,
    "last_result_time": null,
    "total_results": 0,
    "match_count": 0,
    "no_match_count": 0,
    "error_count": 0,
    "not_supported_count": 0,
    "cancelled_count": 0
}

Delete Query Run

Delete a LiveQuery Run.

RBAC Permissions Required

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

Request

DELETE <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}

Responses

Code Description Content-Type Content
204 Successful deletion of a live query run N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8

Response

Response Code: 200.

Filters on Results

Get filters of results specified by criteria.

RBAC Permissions Required

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

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_facet

Body 

{
  "criteria": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "query": "string",
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response

Code Description Content-Type Content
200 Successfully retrieved query run facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
terms.fields Facet terms to retrieve N/A Yes
terms.rows Number of rows to retrieve per facet search result 20 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/_facet

Body 

{
  "criteria": {
    "fields.type": [
      "disconnected"
    ]
  },

  "terms": {
    "fields": [
      "id",
      "status"
    ]
  }
}

Response 

{
    "terms": [
        {
            "field": "id",
            "values": [
                {
                    "total": 1,
                    "id": "0f70de14281e4c2b9ae8dc0b3d7a6080",
                    "name": "0f70de14281e4c2b9ae8dc0b3d7a6080"
                },
                {
                    "total": 1,
                    "id": "29e6a25bdbef4cae88dcc2d4ee63284d",
                    "name": "29e6a25bdbef4cae88dcc2d4ee63284d"
                },
                {
                    "total": 1,
                    "id": "43526614397a449e965432970ea1ea76",
                    "name": "43526614397a449e965432970ea1ea76"
                },
                {
                    "total": 1,
                    "id": "46d02871c4cc42c78aed28509a7a28c4",
                    "name": "46d02871c4cc42c78aed28509a7a28c4"
                },
                {
                    "total": 1,
                    "id": "62a8f521c25d4033adf312bcf230d382",
                    "name": "62a8f521c25d4033adf312bcf230d382"
                },
                {
                    "total": 1,
                    "id": "b33b32fd52ce47a6aad286c08d534698",
                    "name": "b33b32fd52ce47a6aad286c08d534698"
                },
                {
                    "total": 1,
                    "id": "c72df6a9c2c94638b4f4e669b139b1d4",
                    "name": "c72df6a9c2c94638b4f4e669b139b1d4"
                }
            ]
        },
        {
            "field": "status",
            "values": [
                {
                    "total": 7,
                    "id": "matched",
                    "name": "matched"
                }
            ]
        }
    ]
}

Get Device Summary Facets

Get facets for device summaries

RBAC Permissions Required

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

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_facet

Body 

{
  "criteria": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "query": "string",
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

{
  "terms": [
    {
      "field": "string",
      "values": [
        {
          "id": "string",
          "name": "string",
          "total": 0
        }
      ]
    }
  ]
}

Code Description Content-Type Content
200 Successfully retrieved live query device summary facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
terms.fields Device summary fields to filter results on N/A Yes
terms.rows Number of rows to retrieve per facet search result 20 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/device_summaries/_facet

Body 

{
  "criteria": {
    "policy_name": [
      "BERKLY PC Standard"
    ]
  },

  "terms": {
    "fields": [
      "id",
      "status",
      "policy_name"
    ]
  }
}

Response 

{
    "terms": [
        {
            "field": "status",
            "values": [
                {
                    "total": 2,
                    "id": "matched",
                    "name": "matched"
                }
            ]
        },
        {
            "field": "id",
            "values": [
                {
                    "total": 1,
                    "id": "Slohuq4XaymlAqrJcZK9JB3OAbsZ8fYJ",
                    "name": "Slohuq4XaymlAqrJcZK9JB3OAbsZ8fYJ"
                },
                {
                    "total": 1,
                    "id": "ruRn8k7aure3OQX9DmNGMDBJUvfrIl6b",
                    "name": "ruRn8k7aure3OQX9DmNGMDBJUvfrIl6b"
                }
            ]
        }
    ]
}

Get Query History

Get all LiveQuery results for a specific organization.

RBAC Permissions Required

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

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/_search

Body 

{
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "archive_time",
      "order": "ASC"
    }
  ],
  "start": 0
}

Responses

Code Description Content-Type Content
200 Successfully retrieved query runs application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
rows For paging, how many runs to return 20 No
sort.field Field to sort results on N/A No
sort.order Return runs in ascending (ASC) or descending (DESC) order. ASC No
start For paging, where to start retrieving runs from 0 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/_search

Body 

{
    "query": "efuykoprimz74d4ys5ugj5unqfphxpuz",
    "rows": "25",
    "sort": [
        {
            "field": "archive_time",
            "order": "ASC"
        }
    ],
    "start": "0"
}

Response 

{
    "org_key": "ASDF12A",
    "num_found": 1,,
    "results": [
        {
            "template_id": null,
            "org_key": "ASDF12A",
            "name": null,
            "id": "efuykoprimz74d4ys5ugj5unqfphxpuz",
            "sql": "select * from logged_in_users;",
            "created_by": "L97AM9ECAU",
            "create_time": "2019-07-24T20:19:16.654Z",
            "status_update_time": "2019-07-24T20:19:28.762Z",
            "timeout_time": "2019-07-31T20:19:16.654Z",
            "cancellation_time": "2019-07-24T20:19:28.762Z",
            "cancelled_by": "L97AM9ECAU",
            "archive_time": null,
            "archived_by": null,
            "notify_on_finish": false,
            "active_org_devices": 12,
            "status": "CANCELLED",
            "device_filter": null,
            "schedule": null,
            "last_result_time": null,
            "total_results": 0,
            "match_count": 0,
            "no_match_count": 0,
            "error_count": 0,
            "not_supported_count": 0,
            "cancelled_count": 0
        }
    ]
}

Last modified on June 24, 2019