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.
-
api_json_request
(method, uri, **kwargs)¶ Submit a request to the server.
- Args:
- method (str): HTTP method to use. uri (str): URI to submit the request to. **kwargs (dict): Additional arguments.
- Returns:
- object: Result of the operation.
- Raises:
- ServerError: If there’s an error output from the server.
-
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)¶ Create a new object.
- Args:
- cls (class): The Model class (only some models can be created, for example, Feed, Notification, …) data (object): The data used to initialize the new object
- Returns:
- Model: An empty instance of the model class.
- Raises:
- ApiError: If the Model cannot be created.
-
delete_object
(uri)¶ Send a DELETE request to the specified URI.
- Args:
- uri (str): The URI to send the DELETE request to.
- Returns:
- object: The return data from the DELETE request.
-
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.
-
get_object
(uri, query_parameters=None, default=None)¶ Submit a GET request to the server and parse the result as JSON before returning.
- Args:
- uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response.
- Returns:
- object: Result of the GET request.
-
get_raw_data
(uri, query_parameters=None, default=None, **kwargs)¶ Submit a GET request to the server and return the result without parsing it.
- Args:
- uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response. **kwargs:
- Returns:
- object: Result of the GET request.
-
post_object
(uri, body, **kwargs)¶ Send a POST request to the specified URI.
- Args:
- uri (str): The URI to send the POST request to. body (object): The data to be sent in the body of the POST request. **kwargs:
- Returns:
- object: The return data from the POST request.
-
put_object
(uri, body, **kwargs)¶ Send a PUT request to the specified URI.
- Args:
- uri (str): The URI to send the PUT request to. body (object): The data to be sent in the body of the PUT request. **kwargs:
- Returns:
- object: The return data from the PUT request.
-
raise_unless_json
(ret, expected)¶ Raise a ServerError unless we got back an HTTP 200 response with JSON containing all the expected values.
- Args:
- ret (object): Return value to be checked. expected (dict): Expected keys and values that need to be found in the JSON response.
- Raises:
- ServerError: If the HTTP response is anything but 200, or if the expected values are not found.
-
select
(cls, unique_id=None, *args, **kwargs)¶ Prepare a query against the Carbon Black data store.
- Args:
- 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 *args: **kwargs:
- Returns:
- object: An instance of the Model class if a unique_id is provided, otherwise a Query object
-
url
¶ Return the connection URL.
- Returns:
- str: The connection URL.
-
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.