CB LiveQuery API

This page documents the public interfaces exposed by cbapi when communicating with Carbon Black LiveQuery devices.

Main Interface

To use cbapi with Carbon Black LiveQuery, you use CbLiveQueryAPI objects.

The LiveQuery API is used in two stages: run submission and result retrieval.

class cbapi.psc.livequery.rest_api.CbLiveQueryAPI(*args, **kwargs)

The main entry point into the Cb PSC LiveQuery API.

Parameters:profile (str) – (optional) Use the credentials in the named profile when connecting to the Carbon Black server. Uses the profile named ‘default’ when not specified.

Usage:

>>> from cbapi.psc.livequery import CbLiveQueryAPI
>>> cb = CbLiveQueryAPI(profile="production")
create(cls, data=None)

Creates a new object.

Parameters:cls (class) – The Model class (only some models can be created, for example, Feed, Notification, …)
Returns:An empty instance of the Model class
Raises:ApiError – if the Model cannot be created
select(cls, unique_id=None, *args, **kwargs)

Prepares a query against the Carbon Black data store.

Parameters:
  • cls (class) – The Model class (for example, Computer, Process, Binary, FileInstance) to query
  • unique_id – (optional) The unique id of the object to retrieve, to retrieve a single object by ID
Returns:

An instance of the Model class if a unique_id is provided, otherwise a Query object

Queries

The LiveQuery API uses QueryBuilder instances to construct structured or unstructured (i.e., raw string) queries. You can either construct these instances manually, or allow CbLiveQueryAPI.select() to do it for you:

class cbapi.psc.livequery.query.QueryBuilder(**kwargs)

Provides a flexible interface for building prepared queries for the CB LiveQuqery backend.

This object can be instantiated directly, or can be managed implicitly through the CbLiveQuqeryAPI.select() API.

and_(q, **kwargs)

Adds a conjunctive filter to a query.

Parameters:
  • q – string or solrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

QueryBuilder object

Return type:

QueryBuilder

not_(q, **kwargs)

Adds a negative filter to a query.

Parameters:
  • qsolrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

QueryBuilder object

Return type:

QueryBuilder

or_(q, **kwargs)

Adds a disjunctive filter to a query.

Parameters:
  • qsolrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

QueryBuilder object

Return type:

QueryBuilder

where(q, **kwargs)

Adds a conjunctive filter to a query.

Parameters:
  • q – string or solrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

QueryBuilder object

Return type:

QueryBuilder

class cbapi.psc.livequery.query.RunQuery(doc_class, cb)

Represents a query that either creates or retrieves the status of a LiveQuery run.

device_ids(device_ids)

Restricts the devices that this LiveQuery run is performed on to the given IDs.

Parameters:device_ids – list of ints
Returns:This instance
device_types(device_types)

Restricts the devices that this LiveQuery run is performed on to the given device types.

Parameters:device_types – list of strs
Returns:This instance
name(name)

Sets this LiveQuery run’s name. If no name is explicitly set, the run is named after its SQL.

Parameters:name – The run name
Returns:This instance
notify_on_finish()

Sets the notify-on-finish flag on this LiveQuery run.

Returns:This instance
policy_ids(policy_ids)

Restricts this LiveQuery run to the given policy IDs.

Parameters:policy_ids – list of ints
Returns:This instance
submit()

Submits this LiveQuery run.

Returns:A new Run instance containing the run’s status
where(sql)

Sets this LiveQuery run’s underlying SQL.

Parameters:sql – The SQL to execute
Returns:This instance
class cbapi.psc.livequery.models.ResultQuery(doc_class, cb)

Represents a query that retrieves results from a LiveQuery run.

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:
  • q – Query string or solrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

Query object

Return type:

Query

criteria(**kwargs)

Sets the filter criteria on a query’s results.

Example:

>>> cb.select(Result).run_id(my_run).criteria(device_id=[123, 456])
not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:
  • qsolrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

Query object

Return type:

Query

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:
  • qsolrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

Query object

Return type:

Query

run_id(run_id)

Sets the run ID to query results for.

Example:

>>> cb.select(Result).run_id(my_run)
sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example:

>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")
Parameters:
  • key – the key in the schema to sort by
  • direction – the sort order, either “ASC” or “DESC”
Return type:

ResultQuery

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q – Query string, QueryBuilder, or solrq.Q object
  • kwargs – Arguments to construct a solrq.Q with
Returns:

Query object

Return type:

Query

Models

class cbapi.psc.livequery.models.Run(cb, model_unique_id=None, initial_data=None)

Represents a Run object in the Carbon Black server.

Variables:
  • template_id – Placeholder
  • org_key – The organization key for this run
  • name – The name of the LiveQuery run
  • id – The run’s unique ID
  • sql – The LiveQuery query
  • created_by – Placeholder
  • create_time – When this run was created
  • status_update_time – When the status of this run was last updated
  • timeout_time – Placeholder
  • cancellation_time – Placeholder
  • cancelled_by – Placeholder
  • archive_time – Placeholder
  • archived_by – Placeholder
  • notify_on_finish – Whether or not to send an email on query completion
  • active_org_devices – The number of devices active in the organization
  • status – The run status
  • device_filter – Any device filter rules associated with the run
  • schedule – Placeholder
  • last_result_time – When the most recent result for this run was reported
  • total_results – Placeholder
  • match_count – Placeholder
  • no_match_count – Placeholder
  • error_count – Placeholder
  • not_supported_count – Placeholder
  • cancelled_count – Placeholder
class cbapi.psc.livequery.models.Result(cb, initial_data)

Represents a Result object in the Carbon Black server.

Variables:
  • id – The result’s unique ID
  • device – The device associated with the result
  • status – The result’s status
  • time_received – The time at which this result was received
  • device_message – Placeholder
  • fields – The fields returned by the backing osquery query
  • metrics – Metrics associated with the result’s host
class Device(cb, initial_data)

Represents a Device object in the Carbon Black server.

class Fields(cb, initial_data)

Represents a Fields object in the Carbon Black server.

class Metrics(cb, initial_data)

Represents a Metrics object in the Carbon Black server.

device_

Returns the reified Result.Device for this result.

fields_

Returns the reified Result.Fields for this result.

metrics_

Returns the reified Result.Metrics for this result.