Audit and Remediation Package

Base Module

Model and Query Classes for Audit and Remediation

class DeviceSummary(cb, initial_data)

Bases: UnrefreshableModel

Represents the summary of results from a single device during a single Audit and Remediation Run.

Parameters:

id – The result’s unique ID
total_results – Number of results returned for this particular device
device – Information associated with the device
time_received – The time at which this result was received
status – The result’s status
device_message – Placeholder
metrics – Metrics associated with the device

Initialize a DeviceSummary object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

class Metrics(cb, initial_data)

Bases: UnrefreshableModel

Represents the metrics for a result.

Initialize a DeviceSummary Metrics object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

property metrics_: Returns the reified DeviceSummary.Metrics for this result.

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class DeviceSummaryFacet(cb, initial_data)

Bases: ResultFacet

Represents the summary of results for a single device summary in an Audit and Remediation Run.

Initialize a DeviceSummaryFacet object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

class Values(cb, initial_data)

Bases: UnrefreshableModel

Represents the values associated with a field.

Initialize a ResultFacet Values object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

property values_: Returns the reified ResultFacet.Values for this result.

class FacetQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, IterableQueryMixin, CriteriaBuilderSupportMixin, AsyncQueryMixin

Represents a query that receives facet information from a LiveQuery run.

Initialize the FacetQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")

all()

Returns all the items of a query as a list.

Returns:: List of query items
Return type:: list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

execute_async()

Executes the current query in an asynchronous fashion.

Returns:: A future representing the query and its results.
Return type:: Future

facet_field(field)

Sets the facet fields to be received by this query.

Parameters:: field (str or [str]) – Field(s) to be received.
Returns:: FacetQuery that will receive field(s) facet_field.
Return type:: FacetQuery

Example

>>> cb.select(ResultFacet).run_id(my_run).facet_field(["device.policy_name", "device.os"])

first()

Returns the first item that would be returned as the result of a query.

Returns:: First query item
Return type:: obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

run_id(run_id)

Sets the run ID to query results for.

Parameters:: run_id (str) – The run ID to retrieve results for.
Returns:: FacetQuery object with specified run_id.
Return type:: FacetQuery

Example

>>> cb.select(ResultFacet).run_id(my_run)

set_device_ids(device_ids)

Sets the device.id criteria filter.

Parameters:: device_ids ([int]) – Device IDs to filter on.
Returns:: The FacetQuery with specified device.id.
Return type:: FacetQuery

set_device_names(device_names)

Sets the device.name criteria filter.

Parameters:: device_names ([str]) – Device names to filter on.
Returns:: The FacetQuery with specified device.name.
Return type:: FacetQuery

set_device_os(device_os)

Sets the device.os criteria.

Parameters:: device_os ([str]) – Device OS’s to filter on.
Returns:: The FacetQuery object with specified device_os.
Return type:: FacetQuery

Note

Device OS’s can be one or more of [“WINDOWS”, “MAC”, “LINUX”].

set_policy_ids(policy_ids)

Sets the device.policy_id criteria.

Parameters:: policy_ids ([int]) – Device policy ID’s to filter on.
Returns:: The FacetQuery object with specified policy_ids.
Return type:: FacetQuery

set_policy_names(policy_names)

Sets the device.policy_name criteria.

Parameters:: policy_names ([str]) – Device policy names to filter on.
Returns:: The FacetQuery object with specified policy_names.
Return type:: FacetQuery

set_statuses(statuses)

Sets the status criteria.

Parameters:: statuses ([str]) – Query statuses to filter on.
Returns:: The FacetQuery object with specified statuses.
Return type:: FacetQuery

update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

q (Any) – Query string, QueryBuilder, or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

MAX_RESULTS_LIMIT = 10000: Audit and Remediation Models

class Result(cb, initial_data)

Bases: UnrefreshableModel

Represents a single result from an Audit and Remediation Run.

Parameters:

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

Initialize a Result object with initial_data.

Device, Fields, and Metrics objects are attached using initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

class Device(cb, initial_data)

Bases: UnrefreshableModel

Represents device information for a result.

Initialize a Device Result object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class Fields(cb, initial_data)

Bases: UnrefreshableModel

Represents the fields of a result.

Initialize a Result Fields object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class Metrics(cb, initial_data)

Bases: UnrefreshableModel

Represents the metrics of a result.

Initialize a Result Metrics object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

property device_: Returns the reified Result.Device for this result.

property fields_: Returns the reified Result.Fields for this result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

property metrics_: Returns the reified Result.Metrics for this result.

query_device_summaries()

Returns a ResultQuery for a DeviceSummary.

This represents the search for a summary of results from a single device of a Run. The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: The query object returned by this operation.
Return type:: ResultQuery

query_device_summary_facets()

Returns a ResultQuery for a DeviceSummaryFacet.

This represents the search for a summary of a single device summary of a Run. The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: The query object returned by this operation.
Return type:: ResultQuery

query_result_facets()

Returns a ResultQuery for a ResultFacet.

This represents the search for a summary of results from a single field of a Run. The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: The query object returned by this operation.
Return type:: ResultQuery

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The raw json Result.
Return type:: dict

class ResultFacet(cb, initial_data)

Bases: UnrefreshableModel

Represents the summary of results for a single field in an Audit and Remediation Run.

Parameters:: field – The name of the field being summarized

Initialize a ResultFacet object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

class Values(cb, initial_data)

Bases: UnrefreshableModel

Represents the values associated with a field.

Initialize a ResultFacet Values object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

property values_: Returns the reified ResultFacet.Values for this result.

class ResultQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, IterableQueryMixin, CriteriaBuilderSupportMixin, AsyncQueryMixin

Represents a query that retrieves results from a LiveQuery run.

Initialize the ResultQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")

all()

Returns all the items of a query as a list.

Returns:: List of query items
Return type:: list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

async_export()

Create an asynchronous job that exports the results from the run.

This is recommended if you are expecting a very large result set. Once the Job is created, wait for it to be completed, then get the results from the Job using one of the get_output methods on the cbc_sdk.platform.jobs() object. To wait asynchronously for the results, use the Job object’s await_completion() method.

Required Permissions:: livequery.manage(READ), jobs.status(READ)

Returns:: The Job object that represents the asynchronous job.
Return type:: Job

execute_async()

Executes the current query in an asynchronous fashion.

Returns:: A future representing the query and its results.
Return type:: Future

export_csv_as_file(filename)

Export the results from the run as CSV, writing the CSV to the named file.

Required Permissions:: livequery.manage(READ)

Parameters:: filename (str) – Name of the file to write the results to.

export_csv_as_lines()

Export the results from the run as CSV, returning the CSV data as iterated lines.

Required Permissions:: livequery.manage(READ)

Returns:: An iterable that can be used to get each line of CSV text in turn as a string.
Return type:: iterable

export_csv_as_stream(output, compressed=False)

Export the results from the run as CSV, writing the CSV to the given stream.

Required Permissions:: livequery.manage(READ)

Parameters:

output (RawIOBase) – Stream to write the CSV data from the request to.
compressed (bool) – True to download as a compressed ZIP file, False to download as CSV.

export_csv_as_string()

Export the results from the run as CSV, returning the CSV data as a string.

Required Permissions:: livequery.manage(READ)

Returns:: The CSV data as one big string.
Return type:: str

export_zipped_csv(filename)

Export the results from the run as a zipped CSV, writing the zip data to the named file.

Required Permissions:: livequery.manage(READ)

Parameters:: filename (str) – Name of the file to write the results to.

first()

Returns the first item that would be returned as the result of a query.

Returns:: First query item
Return type:: obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

run_id(run_id)

Sets the run ID to query results for.

Parameters:: run_id (str) – The run ID to retrieve results for.
Returns:: ResultQuery object with specified run_id.
Return type:: ResultQuery

Example

>>> cb.select(Result).run_id(my_run)

scroll(rows=10000)

Iteratively fetch results across Live Query Runs or paginate all results beyond the 10k search limits.

To fetch the next set of results repeatively call the scroll function until ResultQuery.num_remaining == 0 or no results are returned.

Note: You must specify either a set_time_received or a set_run_ids on the query before using scroll

Parameters:: rows (int) – The number of rows to fetch
Returns:: The list of results
Return type:: list[Result]

set_device_ids(device_ids)

Sets the device.id criteria filter.

Parameters:: device_ids ([int]) – Device IDs to filter on.
Returns:: The ResultQuery with specified device.id.
Return type:: ResultQuery

set_device_names(device_names)

Sets the device.name criteria filter.

Parameters:: device_names ([str]) – Device names to filter on.
Returns:: The ResultQuery with specified device.name.
Return type:: ResultQuery

set_device_os(device_os)

Sets the device.os criteria.

Parameters:: device_os ([str]) – Device OS’s to filter on.
Returns:: The ResultQuery object with specified device_os.
Return type:: ResultQuery

Note

Device OS’s can be one or more of [“WINDOWS”, “MAC”, “LINUX”].

set_policy_ids(policy_ids)

Sets the device.policy_id criteria.

Parameters:: policy_ids ([int]) – Device policy ID’s to filter on.
Returns:: The ResultQuery object with specified policy_ids.
Return type:: ResultQuery

set_policy_names(policy_names)

Sets the device.policy_name criteria.

Parameters:: policy_names ([str]) – Device policy names to filter on.
Returns:: The ResultQuery object with specified policy_names.
Return type:: ResultQuery

set_run_ids(run_ids)

Sets the run IDs to query results for.

Note

Only supported for scroll

Parameters:: run_ids (list[str]) – The run IDs to retrieve results for.
Returns:: ResultQuery object with specified run_id.
Return type:: ResultQuery

set_statuses(statuses)

Sets the status criteria.

Parameters:: statuses ([str]) – Query statuses to filter on.
Returns:: The ResultQuery object with specified statuses.
Return type:: ResultQuery

set_time_received(start=None, end=None, range=None)

Set the time received to query results for.

Note: If you are using scroll you may only specify range, or start and end. range supports max of 24hrs

Parameters:

start (str) – Start time in ISO8601 UTC format
end (str) – End time in ISO8601 UTC format
range (str) – Relative time window using the following allowed time units y years, w weeks, d days, h hours, m minutes, s seconds

Returns:

ResultQuery object with specified time_received.

Return type:

ResultQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Parameters:

key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.

Returns:

ResultQuery object with specified sorting key and order.

Return type:

ResultQuery

Example

>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")

update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

q (Any) – Query string, QueryBuilder, or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

class Run(cb, model_unique_id=None, initial_data=None)

Bases: NewBaseModel

Represents an Audit and Remediation run.

Example:

>>> run = cb.select(Run, run_id)
>>> print(run.name, run.sql, run.create_time)
>>> print(run.status, run.match_count)
>>> run.refresh()

Parameters:

org_key – The organization key for this run
name – The name of the Audit and Remediation run
id – The run’s unique ID
sql – The Audit and Remediation query
created_by – The user or API id that created the run
create_time – When this run was created
status_update_time – When the status of this run was last updated
timeout_time – The time at which the query will stop requesting results from any devices who have not responded
cancellation_time – The time at which a user or API id cancelled the run
cancelled_by – The user or API id that cancelled the run
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
last_result_time – When the most recent result for this run was reported
total_results – The number of results received
match_count – The number of devices which received a match to the query
no_match_count – The number of devices which did not received a match to the query
error_count – The number of devices which errored
not_supported_count – The number of devices which do not support a portion of the osquery
cancelled_count – The number of devices which were cancelled before they ran the query
not_started_count – The number of devices which have not run the query
success_count – The number of devices which succeeded in running the query
in_progress_count – The number of devices which were currently executing the query
recommended_query_id – The id of a query from the recommendedation route
template_id – The template that created the run

Initialize a Run object with initial_data.

Required Permissions:: livequery.manage(READ)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – ID of the query run represented.
initial_data (dict) – Initial data used to populate the query run.

delete()

Delete a query.

Required Permissions:: livequery.manage(DELETE)

Returns:: True if the query was deleted successfully, False otherwise.
Return type:: bool

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

query_device_summaries()

Create a DeviceSummary query that searches for all device summaries on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all device summaries for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_facets()

Create a ResultFacet query that searches for all result facets on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all result facets for this run.
Return type:: FacetQuery
Raises:: ApiError – If the query has been deleted.

query_results()

Create a Result query that searches for all results on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all results for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

refresh(): Reload this object from the server.

stop()

Stop a running query.

Required Permissions:: livequery.manage(UPDATE)

Returns:: True if query was stopped successfully, False otherwise.
Return type:: bool
Raises:: ServerError – If the server response cannot be parsed as JSON.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class RunHistory(cb, initial_data=None)

Bases: Run

Represents a historical Audit and Remediation Run.

Initialize a RunHistory object with initial_data.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the history object.

delete()

Delete a query.

Required Permissions:: livequery.manage(DELETE)

Returns:: True if the query was deleted successfully, False otherwise.
Return type:: bool

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

query_device_summaries()

Create a DeviceSummary query that searches for all device summaries on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all device summaries for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_facets()

Create a ResultFacet query that searches for all result facets on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all result facets for this run.
Return type:: FacetQuery
Raises:: ApiError – If the query has been deleted.

query_results()

Create a Result query that searches for all results on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all results for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

refresh(): Reload this object from the server.

stop()

Stop a running query.

Required Permissions:: livequery.manage(UPDATE)

Returns:: True if query was stopped successfully, False otherwise.
Return type:: bool
Raises:: ServerError – If the server response cannot be parsed as JSON.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class RunHistoryQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, IterableQueryMixin, CriteriaBuilderSupportMixin, AsyncQueryMixin

Represents a query that retrieves historic LiveQuery runs.

Initialize the RunHistoryQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")

all()

Returns all the items of a query as a list.

Returns:: List of query items
Return type:: list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

execute_async()

Executes the current query in an asynchronous fashion.

Returns:: A future representing the query and its results.
Return type:: Future

first()

Returns the first item that would be returned as the result of a query.

Returns:: First query item
Return type:: obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

set_template_ids(template_ids)

Sets the template_id criteria filter.

Parameters:: template_ids ([str]) – Template IDs to filter on.
Returns:: The RunHistoryQuery with specified template_id.
Return type:: RunHistoryQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Parameters:

key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.

Returns:

RunHistoryQuery object with specified sorting key and order.

Return type:

RunHistoryQuery

Example:

>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")

update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

q (Any) – Query string, QueryBuilder, or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

class RunQuery(doc_class, cb)

Bases: BaseQuery, AsyncQueryMixin

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

Initialize the RunQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

device_ids(device_ids)

Restricts the devices that this Audit and Remediation run is performed on to the given IDs.

Parameters:: device_ids ([int]) – Device IDs to perform the Run on.
Returns:: The RunQuery with specified device_ids.
Return type:: RunQuery

device_types(device_types)

Restricts the devices that this Audit and Remediation run is performed on to the given OS.

Parameters:: device_types ([str]) – Device types to perform the Run on.
Returns:: The RunQuery object with specified device_types.
Return type:: RunQuery

Note

Device type can be one of [“WINDOWS”, “MAC”, “LINUX”].

execute_async()

Executes the current query in an asynchronous fashion.

Returns:: A future representing the query and its results.
Return type:: Future

name(name)

Sets this Audit and Remediation run’s name.

If no name is explicitly set, the run is named after its SQL.

Parameters:: name (str) – The name for this Run.
Returns:: The RunQuery object with specified name.
Return type:: RunQuery

notify_on_finish()

Sets the notify-on-finish flag on this Audit and Remediation run.

Returns:: The RunQuery object with notify_on_finish set to True.
Return type:: RunQuery

policy_id(policy_id)

Restricts this Audit and Remediation run to the given policy ID.

Parameters:: policy_id (int) or (list[int]) – Policy ID to perform the Run on.
Returns:: The RunQuery object with specified policy_id.
Return type:: RunQuery

schedule(rrule, timezone)

Sets a schedule for the SQL Query to recur

A schedule requires an rrule and a timezone to determine the time to rerun the SQL query. rrule is defined in RFC 2445 however only a subset of the functionality is supported here. If a Run is created with a schedule then the Run will contain a template_id to the corresponding template and a new Run will be created each time the schedule is met.

Example RRule, Daily

Field

Values

BYSECOND

0

BYMINUTE

0 or 30

BYHOUR

0 to 23

Daily at 1:30PM

RRULE:FREQ=DAILY;BYHOUR=13;BYMINUTE=30;BYSECOND=0

Example RRule, Weekly

Field

Values

BYSECOND

0

BYMINUTE

0

BYHOUR

0 to 23

BYDAY

One or more: SU, MO, TU, WE, TH, FR, SA

Monday and Friday of the week at 2:30 AM

RRULE:FREQ=WEEKLY;BYDAY=MO,FR;BYHOUR=13;BYMINUTE=30;BYSECOND=0

Example RRule, Monthly

Note: Either (BYDAY and BYSETPOS) or BYMONTHDAY is required.

Field

Values

BYSECOND

0

BYMINUTE

0 or 30

BYHOUR

0 to 23

BYDAY

One or more: SU, MO, TU, WE, TH, FR, SA

BYSETPOS

-1, 1, 2, 3, 4

BYMONTHDAY

One or more: 1 to 28

Last Monday of the Month at 2:30 AM

RRULE:FREQ=MONTHLY;BYDAY=MO;BYSETPOS=-1;BYHOUR=2;BYMINUTE=30;BYSECOND=0

1st and 15th of the Month at 2:30 AM

RRULE:FREQ=DAILY;BYMONTHDAY=1,15;BYHOUR=2;BYMINUTE=30;BYSECOND=0

Parameters:

rrule (string) – A recurrence rule (RFC 2445) specifying the frequency and time at which the query will recur
timezone (string) – The timezone database name to use as a base for the rrule

Returns:

The RunQuery with a recurrence schedule.

Return type:

RunQuery

submit()

Submits this Audit and Remediation run.

Returns:: A new Run instance containing the run’s status.
Return type:: Run
Raises:: ApiError – If the Run does not have SQL set, or if the Run has already been submitted.

where(sql)

Sets this Audit and Remediation run’s underlying SQL.

Parameters:: sql (str) – The SQL to execute for the Run.
Returns:: The RunQuery object with specified sql.
Return type:: RunQuery

class Template(cb, model_unique_id=None, initial_data=None)

Bases: Run

Represents an Audit and Remediation Live Query Template.

Example:

>>> template = cb.select(Template, template_id)
>>> print(template.name, template.sql, template.create_time)
>>> print(template.status, template.match_count, template.schedule)
>>> template.refresh()

Parameters:

org_key – The organization key for this run
name – The name of the Audit and Remediation run
id – The run’s unique ID
sql – The Audit and Remediation query
created_by – The user or API id that created the run
create_time – When this run was created
status_update_time – When the status of this run was last updated
timeout_time – The time at which the query will stop requesting results from any devices who have not responded
cancellation_time – The time at which a user or API id cancelled the run
cancelled_by – The user or API id that cancelled the run
archive_time – The time at which a user or API id cancelled the run
archived_by – The user or API id that archived the run
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
last_result_time – When the most recent result for this run was reported
total_results – The number of results received
match_count – The number of devices which received a match to the query
no_match_count – The number of devices which did not received a match to the query
error_count – The number of devices which errored
not_supported_count – The number of devices which do not support a portion of the osquery
cancelled_count – The number of devices which were cancelled before they ran the query
not_started_count – The number of devices which have not run the query
success_count – The number of devices which succeeded in running the query
in_progress_count – The number of devices which were currently executing the query
recommended_query_id – The id of a query from the recommendedation route
template_id – The template that created the run

Initialize a Template object with initial_data.

Required Permissions:: livequery.manage(READ)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – ID of the query run represented.
initial_data (dict) – Initial data used to populate the query run.

delete()

Delete a query.

Required Permissions:: livequery.manage(DELETE)

Returns:: True if the query was deleted successfully, False otherwise.
Return type:: bool

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

query_device_summaries()

Create a DeviceSummary query that searches for all device summaries on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all device summaries for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_facets()

Create a ResultFacet query that searches for all result facets on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all result facets for this run.
Return type:: FacetQuery
Raises:: ApiError – If the query has been deleted.

query_results()

Create a Result query that searches for all results on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all results for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_runs()

Create a RunHistory query that searches for all runs created by this template ID.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all runs based on this template.
Return type:: RunHistoryQuery

refresh(): Reload this object from the server.

stop()

Stop a template.

Required Permissions:: livequery.manage(UPDATE)

Returns:: True if query was stopped successfully, False otherwise.
Return type:: bool
Raises:: ServerError – If the server response cannot be parsed as JSON.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class TemplateHistory(cb, initial_data=None)

Bases: Template

Represents a historical Audit and Remediation Template.

Initialize a Template object with initial_data.

Required Permissions:: livequery.manage(READ)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the query run.

delete()

Delete a query.

Required Permissions:: livequery.manage(DELETE)

Returns:: True if the query was deleted successfully, False otherwise.
Return type:: bool

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

query_device_summaries()

Create a DeviceSummary query that searches for all device summaries on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all device summaries for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_facets()

Create a ResultFacet query that searches for all result facets on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all result facets for this run.
Return type:: FacetQuery
Raises:: ApiError – If the query has been deleted.

query_results()

Create a Result query that searches for all results on this run.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all results for this run.
Return type:: ResultQuery
Raises:: ApiError – If the query has been deleted.

query_runs()

Create a RunHistory query that searches for all runs created by this template ID.

The query may be further augmented with additional criteria prior to enumerating its results.

Returns:: A query object which will search for all runs based on this template.
Return type:: RunHistoryQuery

refresh(): Reload this object from the server.

stop()

Stop a template.

Required Permissions:: livequery.manage(UPDATE)

Returns:: True if query was stopped successfully, False otherwise.
Return type:: bool
Raises:: ServerError – If the server response cannot be parsed as JSON.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class TemplateHistoryQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, IterableQueryMixin, CriteriaBuilderSupportMixin, AsyncQueryMixin

Represents a query that retrieves historic LiveQuery templates.

Initialize the TemplateHistoryQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")

all()

Returns all the items of a query as a list.

Returns:: List of query items
Return type:: list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

execute_async()

Executes the current query in an asynchronous fashion.

Returns:: A future representing the query and its results.
Return type:: Future

first()

Returns the first item that would be returned as the result of a query.

Returns:: First query item
Return type:: obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Parameters:

key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.

Returns:

object with specified sorting key and order.

Return type:

TemplateHistoryQuery

Example:

>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")

update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

q (Any) – Query string, QueryBuilder, or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

Differential Module

Model and Query Classes for Differential Analysis

ASYNC_RATE_LIMIT = 100: Differential Analysis Models

class Differential(cb, initial_data=None)

Bases: NewBaseModel

Represents a Differential Analysis run.

Example:

>>> query = cb.select(Differential).newer_run_id(newer_run_id)
>>> run = query.submit()
>>> print(run)
>>> print(run.diff_results)

Parameters:

newer_run_id – id against which the older run id results will be compared
newer_run_create_time – Timestamp of the primary run in ISO 8601 UTC format
older_run_id – This can be optional. If not specified, the previous run as compared to the primary will be chosen. This can be optional if you are comparing reccuring runs only.
older_run_create_time – Timestamp of the older run in ISO 8601 UTC format
diff_processed_time – The time it took to process the results in seconds and milliseconds
newer_run_not_responded_devices – Array of device IDs that have not responded
older_run_not_responded_devices – Array of device IDs that have not responded
diff_results – An object containing either count of changes only or count and actual diff results

Initialize a Differential object with initial_data.

Required Permissions for CBC:: livequery.manage(READ)
Required Permissions for CSP:: _API.Live.Query:livequery.Manage.read

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the query run.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh(): Reload this object from the server.

to_json()

Return a json object of the response.

Returns:: The response dictionary representation.
Return type:: Any

class DifferentialQuery(doc_class, cb)

Bases: BaseQuery, IterableQueryMixin, CriteriaBuilderSupportMixin

Query used to compare two Live Query runs.

Initialize the DifferentialQuery.

Parameters:

doc_class (class) – The model class that will be returned by this query.
cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")

all()

Returns all the items of a query as a list.

Returns:: List of query items
Return type:: list

async_export()

Create an asynchronous job that exports the results from the run.

This is recommended if you are expecting a very large result set. Once the Job is created, wait for it to be completed, then get the results from the Job using one of the get_output methods on the cbc_sdk.platform.jobs object. To wait for the results, use the Job object’s await_completion() method.

Example

>>> # Get the differential
>>> query = cb.select(Differential).newer_run_id(newer_run_id)
>>> export = query.async_export()
>>> # wait for the export to finish
>>> export.await_completion()
>>> # write the results to a file
>>> export.get_output_as_file("example_data.json")

Required CBC Permissions:: livequery.manage(READ), jobs.status(READ)
Required CSP Permissions:: _API.Live.Query:livequery.Manage.read, _API.Background_Tasks.jobs.status.read

Returns:: The Job object that represents the asynchronous job.
Return type:: Job

count_only(count_only)

Return only count of diff results per device or complete diff metadata result.

The default value is true, which means only the count will be returned.

Example

>>> query = cb.select(Differential).newer_run_id(newer_run_id).count_only(True)
>>> run = query.submit()

Parameters:: count_only (string) – Boolean that indicates whether to return actual metadata or return just the count of differances
Returns:: This instance.
Return type:: DifferentialQuery
Raises:: ApiError – If invalid values are passed in the list.

first()

Returns the first item that would be returned as the result of a query.

Returns:: First query item
Return type:: obj

newer_run_id(newer_run_id)

Set the id against which the older_run_id results will be compared.

Example

>>> query = cb.select(Differential).newer_run_id(newer_run_id)
>>> run = query.submit()

Parameters:: newer_run_id (string) – id against which the older_run_id results will be compared.
Returns:: This instance.
Return type:: DifferentialQuery
Raises:: ApiError – If invalid values are passed.

older_run_id(older_run_id)

This can be optional.

If not specified, the previous run as compared to the primary will be chosen if it is a recurring one. If comparing two individual runs, this is required.

Example

>>> query = cb.select(Differential).newer_run_id(newer_run_id).older_run_id(older_run_id)
>>> run = query.submit()

Parameters:: older_run_id (string) – id against which the newer_run_id results will be compared.
Returns:: This instance.
Return type:: DifferentialQuery
Raises:: ApiError – If invalid values are passed.

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

set_device_ids(device_ids)

Restricts the query on to the specified devices only.

Example

>>> query = cb.select(Differential).newer_run_id(newer_run_id).set_device_ids([12345, 56789])
>>> run = query.submit()

Parameters:: device_ids (list) – List of device id(s)
Returns:: This instance.
Return type:: DifferentialQuery
Raises:: ApiError – If invalid values are passed in the list.

submit()

Submits this Differential Analysis run.

Returns:: A new Differential instance containing the run’s content.
Return type:: Run

update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.