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 Carbon Black Cloud 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:
-
not_
(q, **kwargs)¶ Adds a negative filter to a query.
Parameters: - q – solrq.Q object
- kwargs – Arguments to construct a solrq.Q with
Returns: QueryBuilder object
Return type:
-
or_
(q, **kwargs)¶ Adds a disjunctive filter to a query.
Parameters: - q – solrq.Q object
- kwargs – Arguments to construct a solrq.Q with
Returns: QueryBuilder object
Return type:
-
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:
-
-
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: - q – solrq.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: - q – solrq.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:
-
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
- q – Query string,
-
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.