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:	`QueryBuilder`

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:	`QueryBuilder`

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:	`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.

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:	`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.