Audit and Remediation¶
Submodules¶
cbc_sdk.audit_remediation.base module¶
Model and Query Classes for Audit and Remediation
-
class
DeviceSummary
(cb, initial_data)¶ Bases:
cbc_sdk.base.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:
cbc_sdk.base.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.
-
device
= {}¶
-
device_message
= None¶
-
id
= None¶
-
metrics
= []¶
-
metrics_
¶ Returns the reified DeviceSummary.Metrics for this result.
-
primary_key
= 'device_id'¶
-
status
= None¶
-
time_received
= None¶
-
total_results
= None¶
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/device_summaries/_search'¶
-
class
DeviceSummaryFacet
(cb, initial_data)¶ Bases:
cbc_sdk.audit_remediation.base.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.
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/device_summaries/_facet'¶
-
class
FacetQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.CriteriaBuilderSupportMixin
,cbc_sdk.base.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.
-
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"])
-
run_id
(run_id)¶ Sets the run ID to query results for.
Parameters: run_id (int) – 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
-
MAX_RESULTS_LIMIT
= 10000¶ Audit and Remediation Models
-
class
Result
(cb, initial_data)¶ Bases:
cbc_sdk.base.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:
cbc_sdk.base.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.
-
primary_key
= 'id'¶
-
class
Fields
(cb, initial_data)¶ Bases:
cbc_sdk.base.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.
-
class
Metrics
(cb, initial_data)¶ Bases:
cbc_sdk.base.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.
-
device
= {}¶
-
device_
¶ Returns the reified Result.Device for this result.
-
device_message
= None¶
-
fields
= {}¶
-
fields_
¶ Returns the reified Result.Fields for this result.
-
id
= None¶
-
metrics
= {}¶
-
metrics_
¶ Returns the reified Result.Metrics for this result.
-
primary_key
= 'id'¶
-
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
-
status
= None¶
-
time_received
= None¶
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/_search'¶
-
class
ResultFacet
(cb, initial_data)¶ Bases:
cbc_sdk.base.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:
cbc_sdk.base.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.
-
field
= None¶
-
primary_key
= 'field'¶
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/_facet'¶
-
values
= []¶
-
values_
¶ Returns the reified ResultFacet.Values for this result.
-
class
ResultQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.CriteriaBuilderSupportMixin
,cbc_sdk.base.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.
-
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
-
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.
-
run_id
(run_id)¶ Sets the run ID to query results for.
Parameters: run_id (int) – 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)
-
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_statuses
(statuses)¶ Sets the status criteria.
Parameters: statuses ([str]) – Query statuses to filter on. Returns: The ResultQuery object with specified statuses. 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: Example
>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")
-
class
Run
(cb, model_unique_id=None, initial_data=None)¶ Bases:
cbc_sdk.base.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.
-
active_org_devices
= None¶
-
cancellation_time
= None¶
-
cancelled_by
= None¶
-
cancelled_count
= None¶
-
create_time
= None¶
-
created_by
= None¶
-
delete
()¶ Delete a query.
- Required Permissions:
- livequery.manage(DELETE)
Returns: True if the query was deleted successfully, False otherwise. Return type: bool
-
device_filter
= {}¶
-
error_count
= None¶
-
id
= None¶
-
in_progress_count
= None¶
-
last_result_time
= None¶
-
match_count
= None¶
-
name
= None¶
-
no_match_count
= None¶
-
not_started_count
= None¶
-
not_supported_count
= None¶
-
notify_on_finish
= None¶
-
org_key
= None¶
-
primary_key
= 'id'¶
-
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.
-
recommended_query_id
= None¶
-
schedule
= {}¶
-
sql
= None¶
-
status
= None¶
-
status_update_time
= None¶
-
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.
-
success_count
= None¶
-
template_id
= None¶
-
timeout_time
= None¶
-
total_results
= None¶
-
urlobject
= '/livequery/v1/orgs/{}/runs'¶
-
urlobject_single
= '/livequery/v1/orgs/{}/runs/{}'¶
-
class
RunHistory
(cb, initial_data=None)¶ Bases:
cbc_sdk.audit_remediation.base.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.
-
urlobject_history
= '/livequery/v1/orgs/{}/runs/_search'¶
-
class
RunHistoryQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.CriteriaBuilderSupportMixin
,cbc_sdk.base.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.
-
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: Example:
>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")
-
class
RunQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.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”].
-
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:
-
class
Template
(cb, model_unique_id=None, initial_data=None)¶ Bases:
cbc_sdk.audit_remediation.base.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.
-
active_org_devices
= None¶
-
archive_time
= None¶
-
archived_by
= None¶
-
cancellation_time
= None¶
-
cancelled_by
= None¶
-
cancelled_count
= None¶
-
create_time
= None¶
-
created_by
= None¶
-
device_filter
= {}¶
-
error_count
= None¶
-
id
= None¶
-
in_progress_count
= None¶
-
last_result_time
= None¶
-
match_count
= None¶
-
name
= None¶
-
no_match_count
= None¶
-
not_started_count
= None¶
-
not_supported_count
= None¶
-
notify_on_finish
= None¶
-
org_key
= None¶
-
primary_key
= 'id'¶
-
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
-
recommended_query_id
= None¶
-
schedule
= {}¶
-
sql
= None¶
-
status
= None¶
-
status_update_time
= None¶
-
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.
-
success_count
= None¶
-
template_id
= None¶
-
timeout_time
= None¶
-
total_results
= None¶
-
urlobject
= '/livequery/v1/orgs/{}/templates'¶
-
urlobject_single
= '/livequery/v1/orgs/{}/templates/{}'¶
-
class
TemplateHistory
(cb, initial_data=None)¶ Bases:
cbc_sdk.audit_remediation.base.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.
-
urlobject_history
= '/livequery/v1/orgs/{}/templates/_search'¶
-
class
TemplateHistoryQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.CriteriaBuilderSupportMixin
,cbc_sdk.base.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.
-
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: Example:
>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")
cbc_sdk.audit_remediation.differential module¶
Model and Query Classes for Differential Analysis
-
ASYNC_RATE_LIMIT
= 100¶ Differential Analysis Models
-
class
Differential
(cb, initial_data=None)¶ Bases:
cbc_sdk.base.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.
-
diff_processed_time
= None¶
-
diff_results
= {}¶
-
newer_run_create_time
= None¶
-
newer_run_id
= None¶
-
newer_run_not_responded_devices
= []¶
-
older_run_create_time
= None¶
-
older_run_id
= None¶
-
older_run_not_responded_devices
= []¶
-
urlobject
= '/livequery/v1/orgs/{}/differential/runs/_search'¶
-
class
DifferentialQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.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.
-
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.
-
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.
-
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.