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.base.BaseQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.CriteriaBuilderSupportMixin

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.

MAX_RESULTS_LIMIT = 10000¶: Audit and Remediation Models

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 ResultQuery(doc_class, cb)¶

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.CriteriaBuilderSupportMixin

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")

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.base.BaseQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.CriteriaBuilderSupportMixin

Represents a query that retrieves historic LiveQuery runs.

Initialize a RunHistoryQuery object.

set_template_ids(template_ids)¶

Sets the template_id criteria filter.

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

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.base.BaseQuery

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.

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

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/{}'¶

class TemplateHistory(cb, initial_data=None)¶

Bases: cbc_sdk.audit_remediation.base.Template

Represents a TemplateHistory object in the Carbon Black server.

Initialize a TemplateHistory object with initial_data.

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

Represents a query that retrieves historic LiveQuery templates.

Initialize a TemplateHistoryQuery 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")

Audit and Remediation¶

Submodules¶

cbc_sdk.audit_remediation.base module¶

Module contents¶