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")
-
alert_search_suggestions
(query)¶ Returns suggestions for keys and field values that can be used in a search.
Parameters: str (query) – A search query to use. Returns: A list of search suggestions expressed as dict objects.
-
bulk_threat_dismiss
(threat_ids, remediation=None, comment=None)¶ Dismiss the alerts associated with multiple threat IDs. The alerts will be left in a DISMISSED state after this request.
Parameters: - list (threat_ids) – List of string threat IDs.
- str (comment) – The remediation state to set for all alerts.
- str – The comment to set for all alerts.
Returns: The request ID, which may be used to select a WorkflowStatus object.
-
bulk_threat_update
(threat_ids, remediation=None, comment=None)¶ Update the alert status of alerts associated with multiple threat IDs. The alerts will be left in an OPEN state after this request.
Parameters: - list (threat_ids) – List of string threat IDs.
- str (comment) – The remediation state to set for all alerts.
- str – The comment to set for all alerts.
Returns: The request ID, which may be used to select a WorkflowStatus object.
-
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
-
device_background_scan
(device_ids, scan)¶ Set the background scan option for the specified devices.
Parameters: - device_ids (list) – List of IDs of devices to be set.
- scan (boolean) – True to turn background scan on, False to turn it off.
-
device_bypass
(device_ids, enable)¶ Set the bypass option for the specified devices.
Parameters: - device_ids (list) – List of IDs of devices to be set.
- enable (boolean) – True to enable bypass, False to disable it.
-
device_delete_sensor
(device_ids)¶ Delete the specified sensor devices.
Parameters: device_ids (list) – List of IDs of devices to be deleted.
-
device_quarantine
(device_ids, enable)¶ Set the quarantine option for the specified devices.
Parameters: - device_ids (list) – List of IDs of devices to be set.
- enable (boolean) – True to enable quarantine, False to disable it.
-
device_uninstall_sensor
(device_ids)¶ Uninstall the specified sensor devices.
Parameters: device_ids (list) – List of IDs of devices to be uninstalled.
-
device_update_policy
(device_ids, policy_id)¶ Set the current policy for the specified devices.
Parameters: - device_ids (list) – List of IDs of devices to be changed.
- policy_id (int) – ID of the policy to set for the devices.
-
device_update_sensor_version
(device_ids, sensor_version)¶ Update the sensor version for the specified devices.
Parameters: - device_ids (list) – List of IDs of devices to be changed.
- sensor_version (dict) – New version properties for the sensor.
-
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 PSC backend.
This object can be instantiated directly, or can be managed implicitly through the
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.
-
all
()¶ Returns all the items of a query as a list.
Returns: List of query items
-
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])
-
first
()¶ Returns the first item that would be returned as the result of a query.
Returns: First query item
-
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
-
one
()¶ Returns the only item that would be returned by a query.
Returns: Sole query return item Raises: MoreThanOneResultError – If the query returns zero items, or more than one item
-
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.