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 a DeviceSummary object in the Carbon Black server.
Variables: - 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.
-
class
Metrics
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a Metrics object in the Carbon Black server.
Initialize a DeviceSummary Metrics object with initial_data.
-
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 a DeviceSummaryFacet object in the Carbon Black server.
Initialize a DeviceSummaryFacet object with initial_data.
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/device_summaries/_facet'¶
-
-
class
FacetQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.base.PlatformQueryBase
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
Represents a query that receives facet information from a LiveQuery run.
Initialize a FacetQuery object.
-
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. 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. 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.
-
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.
-
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. 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.
-
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.
-
set_statuses
(statuses)¶ Sets the status criteria.
Parameters: statuses ([str]) – Query statuses to filter on. Returns: The FacetQuery object with specified statuses.
-
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 FacetQuery with specified custom criteria.
Example
query = api.select(ResultFacet).update_criteria(“my.criteria.key”, [“criteria_value”])
Note: Use this method if there is no implemented method for your desired criteria.
-
-
class
Result
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
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
Initialize a Result object with initial_data.
Device, Fields, and Metrics objects are attached using initial_data.
-
class
Device
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a Device object in the Carbon Black server.
Initialize a Device Result object with initial_data.
-
primary_key
= 'id'¶
-
-
class
Fields
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a Fields object in the Carbon Black server.
Initialize a Result Fields object with initial_data.
-
class
Metrics
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a Metrics object in the Carbon Black server.
Initialize a Result Metrics object with initial_data.
-
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.
-
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.
-
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.
-
status
= None¶
-
time_received
= None¶
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/_search'¶
-
class
ResultFacet
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a ResultFacet object in the Carbon Black server.
Variables: field – The name of the field being summarized Initialize a ResultFacet object with initial_data.
-
class
Values
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a Values object in the Carbon Black server.
Initialize a ResultFacet Values object with initial_data.
-
field
= None¶
-
primary_key
= 'field'¶
-
urlobject
= '/livequery/v1/orgs/{}/runs/{}/results/_facet'¶
-
values
= []¶
-
values_
¶ Returns the reified ResultFacet.Values for this result.
-
class
-
class
ResultQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.base.PlatformQueryBase
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
Represents a query that retrieves results from a LiveQuery run.
Initialize a ResultQuery object.
-
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. 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.
-
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.
-
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. 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.
-
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.
-
set_statuses
(statuses)¶ Sets the status criteria.
Parameters: statuses ([str]) – Query statuses to filter on. Returns: The ResultQuery object with specified statuses.
-
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.
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 ResultQuery 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.
-
-
class
Run
(cb, model_unique_id=None, initial_data=None)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents a Run object in the Carbon Black server.
Variables: - 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.
-
active_org_devices
= None¶
-
cancellation_time
= None¶
-
cancelled_by
= None¶
-
cancelled_count
= None¶
-
create_time
= None¶
-
created_by
= None¶
-
delete
()¶ Delete a query.
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'¶
-
recommended_query_id
= None¶
-
schedule
= {}¶
-
sql
= None¶
-
status
= None¶
-
status_update_time
= None¶
-
stop
()¶ Stop a running query.
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 RunHistory object in the Carbon Black server.
Initialize a RunHistory object with initial_data.
-
urlobject_history
= '/livequery/v1/orgs/{}/runs/_search'¶
-
-
class
RunHistoryQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.base.PlatformQueryBase
,cbc_sdk.base.QueryBuilderSupportMixin
,cbc_sdk.base.IterableQueryMixin
Represents a query that retrieves historic LiveQuery runs.
Initialize a RunHistoryQuery object.
-
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.
Example:
>>> cb.select(Result).run_id(my_run).where(username="foobar").sort_by("uid")
-
-
class
RunQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.base.PlatformQueryBase
Represents a query that either creates or retrieves the status of a LiveQuery run.
Initialize a RunQuery object.
-
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.
-
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. 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.
-
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.
-
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.
-
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.
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
WEEKLY
Field | Values |——– | ————————————— |BYSECOND | 0 |BYMINUTE | 0 or 30 |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
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.
-
submit
()¶ Submits this Audit and Remediation run.
Returns: A new Run instance containing the run’s status. 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.
-
-
class
Template
(cb, model_unique_id=None, initial_data=None)¶ Bases:
cbc_sdk.audit_remediation.base.Run
Represents a Template object in the Carbon Black server.
Variables: - 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.
-
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'¶
-
recommended_query_id
= None¶
-
schedule
= {}¶
-
sql
= None¶
-
status
= None¶
-
status_update_time
= None¶
-
stop
()¶ Stop a template.
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/{}'¶
-
log
= <Logger cbc_sdk.audit_remediation.base (WARNING)>¶ Audit and Remediation Models