Audit and Remediation REST API

Carbon Black Cloud Audit and Remediation is the new name for the product formerly called CB LiveOps.

Version: v1

Introduction

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.

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

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.

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

Initiates a new Live Query search.

This route includes osquery validation:

  1. Validates the osquery SQL, ensuring tables are correct, table columns match, etc.
  2. Validates 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: https://osquery.io/schema/3.3.2
MAC: https://osquery.io/schema/4.1.2
LINUX: https://osquery.io/schema/4.1.2

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.

RBAC Permissions Required

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

Request

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

Body 

{
    "sql": "<string>",
    "device_filter": {
        "device_id": [
            "<long>",
            "<long>"
        ],
        "os": [
            "<string>",
            "<string>"
        ],
        "policy_id": [
            "<long>"
        ]
    },
    "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>"
    }
}

Response

Code Description Content-Type Content
201 Successfully added a Live Query run application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value. Query is incompatible with supported Live Query OS platforms application/json N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy_id. This field and sub-filters are optional and by default, it will run on all devices. N/A No
device_filter.device_id A list of device IDs to filter on N/A 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
Limitation only one policy_id can be specified		 All Policies No
name Name for your Live Query 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 Live Query Run N/A Yes

Example

Request

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

Body 

{
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "name": "string",
  "notify_on_finish": true,
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string"
}

Response 

{
  "active_org_devices": 0,
  "archive_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "archived_by": "string",
  "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "cancelled_by": "string",
  "cancelled_count": 0,
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "error_count": 0,
  "id": "string",
  "in_progress_count": 0,
  "last_result_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "match_count": 0,
  "name": "string",
  "no_match_count": 0,
  "not_started_count": 0,
  "not_supported_count": 0,
  "notify_on_finish": true,
  "org_key": "string",
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "status": "ACTIVE",
  "status_update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "success_count": 0,
  "template_id": "string",
  "timeout_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "total_results": 0
}

Get Query Details

Returns the current details of a Live Query run. Users will be able to observe numerous metadata fields, such as 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
200 Successful retrieval of Live Query details application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

Field status options:

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

Example

Request

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

Response 

{
  "active_org_devices": 0,
  "archive_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "archived_by": "string",
  "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "cancelled_by": "string",
  "cancelled_count": 0,
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "error_count": 0,
  "id": "string",
  "in_progress_count": 0,
  "last_result_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "match_count": 0,
  "name": "string",
  "no_match_count": 0,
  "not_started_count": 0,
  "not_supported_count": 0,
  "notify_on_finish": true,
  "org_key": "string",
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "status": "ACTIVE",
  "status_update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "success_count": 0,
  "template_id": "string",
  "timeout_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "total_results": 0
}

Get Query Run Results

Gets results from a Live Query run. The Live Query results can also be exported as a CSV compressed in a ZIP, or exported asynchronously (see below for details).

RBAC Permissions Required

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

Request

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

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

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

Note: The last two routes will stream or download results to a CSV. See Additional Query Parameter Values below for additional information about using the stream or download CSV functionality.

Export Large Jobs Asynchronously

You can use the Job Service API to download large sets of query results without experiencing timeout errors or receiving corrupt files.

This route can take an optional URL query parameter that tells the server to process the request asynchronously.

When downloading very large sets of query results as CSV, make sure you pass “?format=csv&async=true” as a query parameter to the existing /results/_search route or you may receive errors and corrupt files.

You can only request format=csv when using async=true. - ?format=zip&async=true is not supported

Body 

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

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

Additional Query Parameter Values

To utilize the stream or download CSV functionality, please read the information below:

Field Description Default Required
format List of format to stream (currently only CSV is available) N/A No
download A parameter to allow download into specified format (will always return a zipped CSV file) False No

Stream CSV File

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

NOTE: To use the stream functionality, set the Accept: text/csv header for the correct response to return.

Download CSV File

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

NOTE: To retrieve the export as a zipped CSV file, set the Accept: application/octet-stream header and include download=true in the query parameters.

Request Body Schema

Field Description Default Required
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
criteria.device.os List of os’s to filter on N/A No
criteria.device.policy_id List of device policy IDs to filter on N/A No
criteria.device.policy_name List of device policy names to filter on N/A No
criteria.status List of statuses to filter on N/A 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 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "device": {
        "id": 0,
        "name": "string",
        "os": "WINDOWS",
        "policy_id": 0,
        "policy_name": "string"
      },
      "device_message": "string",
      "fields": {},
      "id": "string",
      "status": "not_started",
      "time_received": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Get Live Query Recommendations

Get TauTin Live Query Recommendations.

RBAC Permissions Required

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

Request

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

Responses

Code Description Content-Type Content
200 Successful retrieval of recommended queries application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

Example

Request

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

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "link": "string",
      "queries": {
        "description": "string",
        "interval": 0,
        "query": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "results": "string",
        "supported_platforms": [
          "string"
        ],
        "title": "string"
      },
      "type": "string"
    }
  ]
}

Stop Query Run

Stop a running Live Query Run by changing its status to CANCELLED. Note that once a Run has been stopped it cannot be set back to ACTIVE.

RBAC Permissions Required

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

Request

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

Request Body 

{
    "status": "<string>"
}

Responses

Code Description Content-Type Content
204 Successfully stopped a Live Query run N/A N/A
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

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 

{}

Delete Query Run

Deletes a Live Query 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 

{}

Get Facets From Live Query Results

Retrieves facets for Live Query results.

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": {
        "device.id": [
            "<integer>",
            "<integer>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<integer>",
            "<integer>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

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.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
criteria.device.os List of os’s to filter on N/A No
criteria.device.policy_id List of device policy IDs to filter on N/A No
criteria.device.policy_name List of device policy names to filter on N/A No
criteria.status List of statuses to filter on N/A 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
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": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

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

Get Device Summary Facets

Gets 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": {
        "device.id": [
            "<long>",
            "<long>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<long>",
            "<long>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "error_description": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

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

Request Body Schema

Field Description Default Required
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
criteria.device.os List of os’s to filter on N/A No
criteria.device.policy_id List of device policy IDs to filter on N/A No
criteria.device.policy_name List of device policy names to filter on N/A No
criteria.status List of statuses to filter on N/A 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
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/device_summaries/_facet

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "error_description": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

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

Get Device Summary From Results

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

RBAC Permissions Required

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

Request

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

Body 

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

Code Description Content-Type Content
200 Successfully retrieved Live Query device summaries application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 No Live Query run found for the specified id N/A N/A

Request Body Schema

Field Description Default Required
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
criteria.device.os List of os’s to filter on N/A No
criteria.device.policy_id List of device policy IDs to filter on N/A No
criteria.device.policy_name List of device policy names to filter on N/A No
criteria.status List of statuses to filter on N/A 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
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No

Example

Request

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

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "error_description": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "device": {
        "id": 0,
        "name": "string",
        "os": "WINDOWS",
        "policy_id": 0,
        "policy_name": "string"
      },
      "error_description": "string",
      "finish_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "metrics": {
        "additionalProp1": 0,
        "additionalProp2": 0,
        "additionalProp3": 0
      },
      "start_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "status": "not_started",
      "total_results": 0,
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Get Query History

Get and search for Live Query runs.

RBAC Permissions Required

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

Request

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

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

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 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "active_org_devices",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "created_by": "string",
      "device_filter": {
        "device_id": [
          0
        ],
        "os": [
          "WINDOWS"
        ],
        "policy_id": [
          0
        ]
      },
      "id": "string",
      "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "name": "string",
      "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "notify_on_finish": true,
      "recommended_query_id": "string",
      "schedule": {
        "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "cancelled_by": "string",
        "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "recurrence": "DAILY",
        "rrule": "string",
        "status": "ACTIVE",
        "timezone": "America/New_York"
      },
      "sql": "string",
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Create Live Query Template

Creates a Live Query Template.

This route includes osquery validation:

  1. Validates the osquery SQL, ensuring tables are correct, table columns match, etc.
  2. Validates 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: https://osquery.io/schema/3.3.2
MAC: https://osquery.io/schema/4.1.2
LINUX: https://osquery.io/schema/4.1.2

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.

RBAC Permissions Required

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

Request

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

Body 

{
    "sql": "<string>",
    "device_filter": {
      "device_id": [
          "<long>",
          "<long>"
      ],
      "os": [
          "<string>",
          "<string>"
      ],
      "policy_id": [
          "<long>",
          "<long>"
      ]
    },
    "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>"
    }
}

Code Description Content-Type Content
201 Successfully created 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. Query is incompatible with supported Live Query OS platforms. application/json N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 No Live Query run found for the specified id N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy_id. 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 Live Query 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 Live Query Run N/A Yes

Example

Request

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

Body 

{
  "sql": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "name": "string",
  "notify_on_finish": true,
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  }
}

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Retrieve Facets Live Query Templates

Retrieve facets for Live Query Templates.

RBAC Permissions Required

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

Request

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

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

Code Description Content-Type Content
200 Successfully retrieved facet values 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.recommended_query_id The id of a recommended query. This can be found in the output of the recommendations API All Devices No
criteria.schedule.status The current status of the schedule. ACTIVE or CANCELLED 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
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/templates/_facet

Body 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

{

}

Search Live Query Templates

Get and search for Live Query templates.

RBAC Permissions Required

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

Request

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

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

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

Request Body Schema

Field Description Default Required
criteria.recommended_query_id The id of a recommended query. This can be found in the output of the recommendations API All Devices No
criteria.schedule.status The current status of the schedule. ACTIVE or CANCELLED 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
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/templates/_search

Body 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "created_by": "string",
      "device_filter": {
        "device_id": [
          0
        ],
        "os": [
          "WINDOWS"
        ],
        "policy_id": [
          0
        ]
      },
      "id": "string",
      "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "name": "string",
      "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "notify_on_finish": true,
      "recommended_query_id": "string",
      "schedule": {
        "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "cancelled_by": "string",
        "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "recurrence": "DAILY",
        "rrule": "string",
        "status": "ACTIVE",
        "timezone": "America/New_York"
      },
      "sql": "string",
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Retrieve Live Query Template by ID

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

RBAC Permissions Required

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

Request

GET <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}
Code Description Content-Type Content
200 Successfully retrieved a Live Query template application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Example

Request

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

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Edit Live Query Template by ID

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

RBAC Permissions Required

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

Request

PUT <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}

Body 

{
    "create_time": "<string>",
    "created_by": "<string>",
    "device_filter": {
      "device_id": [
          "<long>",
          "<long>"
      ],
      "os": [
          "<string>",
          "<string>"
      ],
      "policy_id": [
          "<long>",
          "<long>"
      ]
    },
    "id": "<string>",
    "last_run_create_time": "<string>",
    "name": "<string>",
    "next_run_time": "<string>",
    "notify_on_finish": "<boolean>",
    "recommended_query_id": "<string>",
    "schedule": {
        "cancellation_time": "<string>",
        "cancelled_by": "<string>",
        "next_run_time": "<string>",
        "previous_run_time": "<string>",
        "recurrence": "<string>",
        "rrule": "<string>",
        "status": "<string>",
        "timezone": "<string>"
    },
    "sql": "<string>",
    "update_time": "<string>"
}

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

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy_id. 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 Live Query 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 Live Query Run N/A Yes

Example

Request

PUT https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/erzo7cotkasdfghjk707srcjwnjgfmiv

Body 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Delete Query Schedule by ID

Delete a query schedule by id.

RBAC Permissions Required

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

Request

DELETE <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}

Responses

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

Example

Request

DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/erzo7cotkasdfghjk707srcjwnjgfmiv

Response 

{}

Last modified on May 19, 2020