Platform Package 

dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:

fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information specified as dicts.

Return type:

list

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:

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:

set_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:: alert_ids (list) – List of string alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:: categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:

*args (list) – Not used.
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_device_ids(device_ids)

Restricts the alerts that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of integer device IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_names(device_names)

Restricts the alerts that this query is performed on to the specified device names.

Parameters:: device_names (list) – List of string device names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:: device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:: device_os_versions (list) – List of string operating system versions.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:: users (list) – List of string user names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:: do_group (bool) – True to group the results, False to not do so.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:: alert_ids (list) – List of string legacy alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:: severity (int) – The minimum severity level for alerts.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of integer policy IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:: policy_names (list) – List of string policy names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:: process_names (list) – List of string process names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:: shas (list) – List of string process SHA-256 hash values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:: reps (list) – List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”, and “COMPANY_BLACK_LIST”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:: tags (list) – List of string tag values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:: priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:: threats (list) – List of string threat ID values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:

key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:: alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.

set_workflows(workflow_vals)

Restricts the alerts that this query is performed on to the specified workflow status values.

Parameters:: workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(BaseAlert).sort_by("name")

Parameters:

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

Returns:

This instance.

Return type:

update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

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:

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

Bases: BaseAlert

Represents CB Analytics alerts.

Initialize the BaseAlert object.

Parameters:

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

class Note(cb, alert, model_unique_id, initial_data=None)

Bases: PlatformModel

Represents a note within an alert.

Parameters:

author – User who created the note
create_time – Time the note was created
id – Unique ID for this note
note – Note contents

Initialize the Note object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (BaseAlert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
initial_data (dict) – Initial data used to populate the note.

delete(): Deletes a note from an alert.

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.

create_note(note): Creates a new note.

dismiss(remediation=None, comment=None)

Dismisses this alert.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

dismiss_threat(remediation=None, comment=None)

Dismisses all alerts with the same threat ID, past or future.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

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

get_events(timeout=0, async_mode=False)

Requests enriched events detailed results.

Parameters:

timeout (int) – Event details request timeout in milliseconds.
async_mode (bool) – True to request details in an asynchronous manner.

Returns:

EnrichedEvents matching the legacy_alert_id

Return type:

list

Note

When using asynchronous mode, this method returns a python future. You can call result() on the future object to wait for completion and get the results.

notes_(): Retrieves all notes for an alert.

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

static search_suggestions(cb, query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
query (str) – A search query to use.

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

update(remediation=None, comment=None)

Updates this alert while leaving it open.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

update_threat(remediation=None, comment=None)

Updates the status of all alerts with the same threat ID, past or future, while leaving them in OPEN state.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

property workflow_

Returns the workflow associated with this alert.

Returns:: The workflow associated with this alert.
Return type:: Workflow

class CBAnalyticsAlertSearchQuery(doc_class, cb)

Represents a query that is used to locate CBAnalyticsAlert objects.

Initialize the CBAnalyticsAlertSearchQuery.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

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:

dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:

fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information specified as dicts.

Return type:

list

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:

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:

set_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:: alert_ids (list) – List of string alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_blocked_threat_categories(categories)

Restricts the alerts that this query is performed on to the specified threat categories that were blocked.

Parameters:: categories (list) – List of threat categories to look for. Valid values are “UNKNOWN”, “NON_MALWARE”, “NEW_MALWARE”, “KNOWN_MALWARE”, and “RISKY_PROGRAM”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:: categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:

*args (list) – Not used.
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_device_ids(device_ids)

Restricts the alerts that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of integer device IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_locations(locations)

Restricts the alerts that this query is performed on to the specified device locations.

Parameters:: locations (list) – List of device locations to look for. Valid values are “ONSITE”, “OFFSITE”, and “UNKNOWN”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_device_names(device_names)

Restricts the alerts that this query is performed on to the specified device names.

Parameters:: device_names (list) – List of string device names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:: device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:: device_os_versions (list) – List of string operating system versions.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:: users (list) – List of string user names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:: do_group (bool) – True to group the results, False to not do so.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_kill_chain_statuses(statuses)

Restricts the alerts that this query is performed on to the specified kill chain statuses.

Parameters:: statuses (list) – List of kill chain statuses to look for. Valid values are “RECONNAISSANCE”, “WEAPONIZE”, “DELIVER_EXPLOIT”, “INSTALL_RUN”,”COMMAND_AND_CONTROL”, “EXECUTE_GOAL”, and “BREACH”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:: alert_ids (list) – List of string legacy alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:: severity (int) – The minimum severity level for alerts.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_not_blocked_threat_categories(categories)

Restricts the alerts that this query is performed on to the specified threat categories that were NOT blocked.

Parameters:: categories (list) – List of threat categories to look for. Valid values are “UNKNOWN”, “NON_MALWARE”, “NEW_MALWARE”, “KNOWN_MALWARE”, and “RISKY_PROGRAM”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_policy_applied(applied_statuses)

Restricts the alerts that this query is performed on to the specified policy status values.

Parameters:: applied_statuses (list) – List of status values to look for. Valid values are “APPLIED” and “NOT_APPLIED”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of integer policy IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:: policy_names (list) – List of string policy names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:: process_names (list) – List of string process names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:: shas (list) – List of string process SHA-256 hash values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_reason_code(reason)

Restricts the alerts that this query is performed on to the specified reason codes (enum values).

Parameters:: reason (list) – List of string reason codes to look for.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:: reps (list) – List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”, and “COMPANY_BLACK_LIST”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_run_states(states)

Restricts the alerts that this query is performed on to the specified run states.

Parameters:: states (list) – List of run states to look for. Valid values are “DID_NOT_RUN”, “RAN”, and “UNKNOWN”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_sensor_actions(actions)

Restricts the alerts that this query is performed on to the specified sensor actions.

Parameters:: actions (list) – List of sensor actions to look for. Valid values are “POLICY_NOT_APPLIED”, “ALLOW”, “ALLOW_AND_LOG”, “TERMINATE”, and “DENY”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:: tags (list) – List of string tag values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:: priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_threat_cause_vectors(vectors)

Restricts the alerts that this query is performed on to the specified threat cause vectors.

Parameters:: vectors (list) – List of threat cause vectors to look for. Valid values are “EMAIL”, “WEB”, “GENERIC_SERVER”, “GENERIC_CLIENT”, “REMOTE_DRIVE”, “REMOVABLE_MEDIA”, “UNKNOWN”, “APP_STORE”, and “THIRD_PARTY”.
Returns:: This instance.
Return type:: CBAnalyticsAlertSearchQuery

set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:: threats (list) – List of string threat ID values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:

key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:: alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.

set_workflows(workflow_vals)

Restricts the alerts that this query is performed on to the specified workflow status values.

Parameters:: workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(BaseAlert).sort_by("name")

Parameters:

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

Returns:

This instance.

Return type:

update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

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:

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

Bases: BaseAlert

Represents Container Runtime alerts.

Initialize the BaseAlert object.

Parameters:

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

class Note(cb, alert, model_unique_id, initial_data=None)

Bases: PlatformModel

Represents a note within an alert.

Parameters:

author – User who created the note
create_time – Time the note was created
id – Unique ID for this note
note – Note contents

Initialize the Note object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (BaseAlert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
initial_data (dict) – Initial data used to populate the note.

delete(): Deletes a note from an alert.

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.

create_note(note): Creates a new note.

dismiss(remediation=None, comment=None)

Dismisses this alert.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

dismiss_threat(remediation=None, comment=None)

Dismisses all alerts with the same threat ID, past or future.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

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

notes_(): Retrieves all notes for an alert.

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

static search_suggestions(cb, query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
query (str) – A search query to use.

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

update(remediation=None, comment=None)

Updates this alert while leaving it open.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

update_threat(remediation=None, comment=None)

Updates the status of all alerts with the same threat ID, past or future, while leaving them in OPEN state.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

property workflow_

Returns the workflow associated with this alert.

Returns:: The workflow associated with this alert.
Return type:: Workflow

class ContainerRuntimeAlertSearchQuery(doc_class, cb)

Represents a query that is used to locate ContainerRuntimeAlert objects.

Initialize the ContainerRuntimeAlertSearchQuery.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

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:

dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:

fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information specified as dicts.

Return type:

list

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:

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:

set_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:: alert_ids (list) – List of string alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:: categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_cluster_names(names)

Restricts the alerts that this query is performed on to the specified Kubernetes cluster names.

Parameters:: names (list) – List of Kubernetes cluster names to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:

*args (list) – Not used.
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_device_ids(device_ids)

Restricts the alerts that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of integer device IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_names(device_names)

Restricts the alerts that this query is performed on to the specified device names.

Parameters:: device_names (list) – List of string device names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:: device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:: device_os_versions (list) – List of string operating system versions.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:: users (list) – List of string user names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_egress_group_ids(ids)

Restricts the alerts that this query is performed on to the specified egress group IDs.

Parameters:: ids (list) – List of egress group IDs to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_egress_group_names(names)

Restricts the alerts that this query is performed on to the specified egress group names.

Parameters:: names (list) – List of egress group names to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:: do_group (bool) – True to group the results, False to not do so.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_ip_reputations(reputations)

Restricts the alerts that this query is performed on to the specified IP reputation values.

Parameters:: reputations (list) – List of IP reputation values to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:: alert_ids (list) – List of string legacy alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:: severity (int) – The minimum severity level for alerts.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_namespaces(namespaces)

Restricts the alerts that this query is performed on to the specified Kubernetes namespaces.

Parameters:: namespaces (list) – List of Kubernetes namespaces to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of integer policy IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:: policy_names (list) – List of string policy names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_ports(ports)

Restricts the alerts that this query is performed on to the specified listening ports.

Parameters:: ports (list) – List of listening ports to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:: process_names (list) – List of string process names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:: shas (list) – List of string process SHA-256 hash values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_protocols(protocols)

Restricts the alerts that this query is performed on to the specified protocols.

Parameters:: protocols (list) – List of protocols to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_remote_domains(domains)

Restricts the alerts that this query is performed on to the specified remote domains.

Parameters:: domains (list) – List of remote domains to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_remote_ips(addrs)

Restricts the alerts that this query is performed on to the specified remote IP addresses.

Parameters:: addrs (list) – List of remote IP addresses to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_replica_ids(ids)

Restricts the alerts that this query is performed on to the specified pod names.

Parameters:: ids (list) – List of pod names to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:: reps (list) – List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”, and “COMPANY_BLACK_LIST”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_rule_ids(ids)

Restricts the alerts that this query is performed on to the specified Kubernetes policy rule IDs.

Parameters:: ids (list) – List of Kubernetes policy rule IDs to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_rule_names(names)

Restricts the alerts that this query is performed on to the specified Kubernetes policy rule names.

Parameters:: names (list) – List of Kubernetes policy rule names to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:: tags (list) – List of string tag values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:: priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:: threats (list) – List of string threat ID values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:

key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:: alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.

set_workflows(workflow_vals)

Restricts the alerts that this query is performed on to the specified workflow status values.

Parameters:: workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_workload_ids(ids)

Restricts the alerts that this query is performed on to the specified workload IDs.

Parameters:: ids (list) – List of workload IDs to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_workload_kinds(kinds)

Restricts the alerts that this query is performed on to the specified workload types.

Parameters:: kinds (list) – List of workload types to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

set_workload_names(names)

Restricts the alerts that this query is performed on to the specified workload names.

Parameters:: names (list) – List of workload names to look for.
Returns:: This instance.
Return type:: ContainerRuntimeAlertSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(BaseAlert).sort_by("name")

Parameters:

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

Returns:

This instance.

Return type:

update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

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:

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

Bases: BaseAlert

Represents Device Control alerts.

Initialize the BaseAlert object.

Parameters:

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

class Note(cb, alert, model_unique_id, initial_data=None)

Bases: PlatformModel

Represents a note within an alert.

Parameters:

author – User who created the note
create_time – Time the note was created
id – Unique ID for this note
note – Note contents

Initialize the Note object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (BaseAlert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
initial_data (dict) – Initial data used to populate the note.

delete(): Deletes a note from an alert.

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.

create_note(note): Creates a new note.

dismiss(remediation=None, comment=None)

Dismisses this alert.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

dismiss_threat(remediation=None, comment=None)

Dismisses all alerts with the same threat ID, past or future.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

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

notes_(): Retrieves all notes for an alert.

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

static search_suggestions(cb, query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
query (str) – A search query to use.

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

update(remediation=None, comment=None)

Updates this alert while leaving it open.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

update_threat(remediation=None, comment=None)

Updates the status of all alerts with the same threat ID, past or future, while leaving them in OPEN state.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

property workflow_

Returns the workflow associated with this alert.

Returns:: The workflow associated with this alert.
Return type:: Workflow

class DeviceControlAlertSearchQuery(doc_class, cb)

Represents a query that is used to locate DeviceControlAlert objects.

Initialize the DeviceControlAlertSearchQuery.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

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:

dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:

fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information specified as dicts.

Return type:

list

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:

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:

set_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:: alert_ids (list) – List of string alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:: categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:

*args (list) – Not used.
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_device_ids(device_ids)

Restricts the alerts that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of integer device IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_names(device_names)

Restricts the alerts that this query is performed on to the specified device names.

Parameters:: device_names (list) – List of string device names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:: device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:: device_os_versions (list) – List of string operating system versions.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:: users (list) – List of string user names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_external_device_friendly_names(names)

Restricts the alerts that this query is performed on to the specified external device friendly names.

Parameters:: names (list) – List of external device friendly names to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_external_device_ids(ids)

Restricts the alerts that this query is performed on to the specified external device IDs.

Parameters:: ids (list) – List of external device IDs to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:: do_group (bool) – True to group the results, False to not do so.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:: alert_ids (list) – List of string legacy alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:: severity (int) – The minimum severity level for alerts.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of integer policy IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:: policy_names (list) – List of string policy names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:: process_names (list) – List of string process names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:: shas (list) – List of string process SHA-256 hash values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_product_ids(ids)

Restricts the alerts that this query is performed on to the specified product IDs.

Parameters:: ids (list) – List of product IDs to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_product_names(names)

Restricts the alerts that this query is performed on to the specified product names.

Parameters:: names (list) – List of product names to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:: reps (list) – List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”, and “COMPANY_BLACK_LIST”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_serial_numbers(serial_numbers)

Restricts the alerts that this query is performed on to the specified serial numbers.

Parameters:: serial_numbers (list) – List of serial numbers to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:: tags (list) – List of string tag values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:: priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:: threats (list) – List of string threat ID values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:

key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:: alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.

set_vendor_ids(ids)

Restricts the alerts that this query is performed on to the specified vendor IDs.

Parameters:: ids (list) – List of vendor IDs to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_vendor_names(names)

Restricts the alerts that this query is performed on to the specified vendor names.

Parameters:: names (list) – List of vendor names to look for.
Returns:: This instance.
Return type:: DeviceControlAlertSearchQuery

set_workflows(workflow_vals)

Restricts the alerts that this query is performed on to the specified workflow status values.

Parameters:: workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(BaseAlert).sort_by("name")

Parameters:

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

Returns:

This instance.

Return type:

update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

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:

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

Bases: BaseAlert

Represents watch list alerts.

Initialize the BaseAlert object.

Parameters:

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

class Note(cb, alert, model_unique_id, initial_data=None)

Bases: PlatformModel

Represents a note within an alert.

Parameters:

author – User who created the note
create_time – Time the note was created
id – Unique ID for this note
note – Note contents

Initialize the Note object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (BaseAlert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
initial_data (dict) – Initial data used to populate the note.

delete(): Deletes a note from an alert.

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.

create_note(note): Creates a new note.

dismiss(remediation=None, comment=None)

Dismisses this alert.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

dismiss_threat(remediation=None, comment=None)

Dismisses all alerts with the same threat ID, past or future.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

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

get_process(async_mode=False)

Gets the process corresponding with the alert.

Parameters:: async_mode – True to request process in an asynchronous manner.
Returns:: The process corresponding to the alert.
Return type:: Process

notes_(): Retrieves all notes for an alert.

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

static search_suggestions(cb, query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
query (str) – A search query to use.

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

update(remediation=None, comment=None)

Updates this alert while leaving it open.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

update_threat(remediation=None, comment=None)

Updates the status of all alerts with the same threat ID, past or future, while leaving them in OPEN state.

Parameters:

remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.

property workflow_

Returns the workflow associated with this alert.

Returns:: The workflow associated with this alert.
Return type:: Workflow

class WatchlistAlertSearchQuery(doc_class, cb)

Represents a query that is used to locate WatchlistAlert objects.

Initialize the WatchlistAlertSearchQuery.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

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:

dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:

fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information specified as dicts.

Return type:

list

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:

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:

set_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:: alert_ids (list) – List of string alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:: categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:

*args (list) – Not used.
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_device_ids(device_ids)

Restricts the alerts that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of integer device IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_names(device_names)

Restricts the alerts that this query is performed on to the specified device names.

Parameters:: device_names (list) – List of string device names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:: device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:: device_os_versions (list) – List of string operating system versions.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:: users (list) – List of string user names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:: do_group (bool) – True to group the results, False to not do so.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:: alert_ids (list) – List of string legacy alert IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:: severity (int) – The minimum severity level for alerts.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of integer policy IDs.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:: policy_names (list) – List of string policy names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:: process_names (list) – List of string process names.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:: shas (list) – List of string process SHA-256 hash values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:: reps (list) – List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”, and “COMPANY_BLACK_LIST”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:: tags (list) – List of string tag values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:: priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:: threats (list) – List of string threat ID values.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:

key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
**kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.

Returns:

This instance.

Return type:

set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:: alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.

set_watchlist_ids(ids)

Restricts the alerts that this query is performed on to the specified watchlist ID values.

Parameters:: ids (list) – List of string watchlist ID values.
Returns:: This instance.
Return type:: WatchlistAlertSearchQuery

set_watchlist_names(names)

Restricts the alerts that this query is performed on to the specified watchlist name values.

Parameters:: names (list) – List of string watchlist name values.
Returns:: This instance.
Return type:: WatchlistAlertSearchQuery

set_workflows(workflow_vals)

Restricts the alerts that this query is performed on to the specified workflow status values.

Parameters:: workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:: This instance.
Return type:: BaseAlertSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(BaseAlert).sort_by("name")

Parameters:

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

Returns:

This instance.

Return type:

update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:

remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID, which may be used to select a WorkflowStatus object.

Return type:

str

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:

class Workflow(cb, initial_data=None)

Represents the workflow associated with alerts.

Parameters:

changed_by – Username of the user who changed the workflow
comment – Comment when updating the workflow
last_update_time – When the workflow was last updated
remediation – Alert remediation code. Indicates the result of the investigation into the alert
state – State of the workflow

Initialize the Workflow object.

Parameters:

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

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.

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

Bases: PlatformModel

Represents the current workflow status of a request.

Parameters:

errors – Errors for dismiss alerts or threats, if no errors it won’t be included in response
failed_ids – Failed ids
id – Time based id for async job, it’s not unique across the orgs
num_hits – Total number of alerts to be operated on
num_success – Successfully operated number of alerts
status – Status for the async progress
workflow – Requested workflow change

Initialize the BaseAlert object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – ID of the request being processed.
initial_data (dict) – Initial data used to populate the status.

property finished

Returns whether this request has been completed.

Returns:: True if the request is in “finished” state, False if not.
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

property id_

Returns the request ID of the associated request.

Returns:: The request ID of the associated request.
Return type:: str

property in_progress

Returns whether this request is currently in progress.

Returns:: True if the request is in “in progress” state, False if not.
Return type:: bool

property queued

Returns whether this request has been queued.

Returns:: True if the request is in “queued” state, False if not.
Return type:: bool

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

property workflow_

Returns the current workflow associated with this request.

Returns:: The current workflow associated with this request.
Return type:: Workflow

Audit Module

Model and Query Classes for Platform Auditing

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

Model class which represents audit log events. Mostly for future implementation.

Creation of AuditLog objects is not yet implemented.

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

static get_auditlogs(cb)

Retrieve queued audit logs from the Carbon Black Cloud server.

Required Permissions:: org.audits (READ)

Parameters:: cb (BaseAPI) – Reference to API object used to communicate with the server.
Returns:: List of dictionary objects representing the audit logs, or an empty list if none available.
Return type:: list[dict]

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

Devices Module

Model and Query Classes for Platform Devices

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

Bases: PlatformModel

Represents a device (endpoint).

Parameters:

activation_code – Device activation code
activation_code_expiry_time – When the expiration code expires and cannot be used to register a device
ad_group_id – Device’s AD group
av_ave_version – AVE version (part of AV Version)
av_engine – Current AV version
av_last_scan_time – Last AV scan time
av_master – Whether the device is an AV Master (?)
av_pack_version – Pack version (part of AV Version)
av_product_version – AV Product version (part of AV Version)
av_status – AV Statuses
av_update_servers – Device’s AV servers
av_vdf_version – VDF version (part of AV Version)
current_sensor_policy_name – Current MSM policy name
deregistered_time – When the device was deregistered with the PSC backend
device_id – ID of the device
device_meta_data_item_list – MSM Device metadata
device_owner_id – ID of the user who owns the device
email – Email of the user who owns the device
encoded_activation_code – Encoded device activation code
first_name – First name of the user who owns the device
id – ID of the device
last_contact_time – Time the device last checked into the PSC backend
last_device_policy_changed_time – Last time the device’s policy was changed
last_device_policy_requested_time – Last time the device requested policy updates
last_external_ip_address – Device’s external IP
last_internal_ip_address – Device’s internal IP
last_location – Location of the device (on-/off-premises)
last_name – Last name of the user who owns the device
last_policy_updated_time – Last time the device was MSM processed
last_reported_time – Time when device last reported an event to PSC backend
last_reset_time – When the sensor was last reset
last_shutdown_time – When the device last shut down
linux_kernel_version – Linux kernel version
login_user_name – Last acive logged in username
mac_address – Device’s hardware MAC address
middle_name – Middle name of the user who owns the device
name – Device Hostname
organization_id – Org ID to which the device belongs
organization_name – Name of the org that owns this device
os – Device type
os_version – Version of the OS
passive_mode – Whether the device is in passive mode (bypass?)
policy_id – ID of the policy this device is using
policy_name – Name of the policy this device is using
policy_override – Manually assigned policy (overrides mass sensor management)
quarantined – Whether the device is quarantined
registered_time – When the device was registered with the PSC backend
scan_last_action_time – Not used. Intended for when the background scan was last active
scan_last_complete_time – Not Used. Intended for when the background scan was last completed
scan_status – Not Used. Intended for Background scan status
sensor_out_of_date – Whether the device is out of date
sensor_states – Active sensor states
sensor_version – Version of the PSC sensor
status – Device status
target_priority_type – Priority of the device
uninstall_code – Code to enter to uninstall this device
vdi_base_device – VDI Base device
virtual_machine – Whether this device is a Virtual Machine (VMware AppDefense integration
virtualization_provider – VM Virtualization Provider
windows_platform – Type of windows platform (client/server, x86/x64)
deployment_type – Classification determined by the device lifecycle management policy

Initialize the Device object.

Parameters:

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

background_scan(flag)

Set the background scan option for this device.

Required Permissions:: device.bg-scan (EXECUTE)

Parameters:: flag (bool) – True to turn background scan on, False to turn it off.
Returns:: The JSON output from the request.
Return type:: str

bypass(flag)

Set the bypass option for this device.

Required Permissions:: device.bypass (EXECUTE)

Parameters:: flag (bool) – True to enable bypass, False to disable it.
Returns:: The JSON output from the request.
Return type:: str

delete_sensor()

Delete this sensor device.

Required Permissions:: device.deregistered (DELETE)

Returns:: The JSON output from the request.
Return type:: str

property deviceId

Warn user that Platform Devices use ‘id’, not ‘device_id’.

Platform Device API’s return ‘id’ in API responses, where Endpoint Standard API’s return ‘deviceId’.

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

get_vulnerability_summary(category=None)

Get the vulnerabilities associated with this device

Required Permissions:: vulnerabilityAssessment.data (READ)

Parameters:: category (string) – (optional) vulnerabilty category (OS, APP)
Returns:: summary for the vulnerabilities for this device
Return type:: dict

get_vulnerabilties()

Get an Operating System or Application Vulnerability List for a specific device.

Returns:: vulnerabilities for this device
Return type:: dict

lr_session(async_mode=False)

Retrieve a Live Response session object for this Device.

Required Permissions:: org.liveresponse.session (CREATE)

Returns:: Live Response session for the Device.
Return type:: LiveResponseSession
Raises:: ApiError – If there is an error establishing a Live Response session for this Device.

property nsx_available

Returns whether NSX actions are available on this device.

Returns:: True if NSX actions are available, False if not.
Return type:: bool

nsx_remediation(tag, set_tag=True)

Start an NSX Remediation job on this device to change the tag.

Required Permissions:: appliances.nsx.remediation(EXECUTE)

Parameters:

tag (str) – The NSX tag to apply to this device. Valid values are “CB-NSX-Quarantine”, “CB-NSX-Isolate”, and “CB-NSX-Custom”.
set_tag (bool) – True to toggle the specified tag on, False to toggle it off. Default True.

Returns:

The object representing all running jobs. None if the operation is a no-op.

Return type:

NSXRemediationJob

quarantine(flag)

Set the quarantine option for this device.

Required Permissions:: device.quarantine (EXECUTE)

Parameters:: flag (bool) – True to enable quarantine, False to disable it.
Returns:: The JSON output from the request.
Return type:: str

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

uninstall_sensor()

Uninstall this sensor device.

Required Permissions:: device.uninstall (EXECUTE)

Returns:: The JSON output from the request.
Return type:: str

update_policy(policy_id)

Set the current policy for this device.

Required Permissions:: device.policy (UPDATE)

Parameters:: policy_id (int) – ID of the policy to set for the devices.
Returns:: The JSON output from the request.
Return type:: str

update_sensor_version(sensor_version)

Update the sensor version for this device.

Required Permissions:: org.kits (EXECUTE)

Parameters:: sensor_version (dict) – New version properties for the sensor.
Returns:: The JSON output from the request.
Return type:: str

vulnerability_refresh()

Perform an action on a specific device. Only REFRESH is supported.

Required Permissions:: vulnerabilityAssessment.data (EXECUTE)

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

Represents a device field in a facet search.

Parameters:

field – Name of the field being faceted
values – The values of the faceted field.

Initialize the DeviceFacet object.

Parameters:

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

class DeviceFacetValue(cb, outer, model_unique_id, initial_data)

Represents a value of a particular field.

Initialize the DeviceFacetValue object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
outer (DeviceFacet) – Reference to outer facet object.
model_unique_id (str) – Value ID.
initial_data (dict) – Initial data used to populate the facet value.

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_devices()

Set up a device query to find all devices that match this facet value.

Example

>>> facets = api.select(Device).where('').facets(['policy_id'])
>>> for value in facets[0].values_:
...     print(f"Policy ID = {value.id}:")
...     for dev in value.query_devices():
...         print(f"    {dev.name} ({dev.last_external_ip_address})")

Returns:: A new DeviceQuery set with the criteria, which may have additional criteria added to it.
Return type:: DeviceQuery

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

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.

property values_

Return the list of facet values for this facet.

Returns:: The list of values for this facet.
Return type:: list[DeviceFacetValue]

class DeviceSearchQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

Represents a query that is used to locate Device objects.

Initialize the DeviceSearchQuery.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

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:

background_scan(scan)

Set the background scan option for the specified devices.

Required Permissions:: device.bg-scan (EXECUTE)

Parameters:: scan (bool) – True to turn background scan on, False to turn it off.
Returns:: The JSON output from the request.
Return type:: str

bypass(enable)

Set the bypass option for the specified devices.

Required Permissions:: device.bypass (EXECUTE)

Parameters:: enable (bool) – True to enable bypass, False to disable it.
Returns:: The JSON output from the request.
Return type:: str

delete_sensor()

Delete the specified sensor devices.

Required Permissions:: device.deregistered (DELETE)

Returns:: The JSON output from the request.
Return type:: str

download()

Uses the query parameters that have been set to download all device listings in CSV format.

Example

>>> cb.select(Device).set_status(["ALL"]).download()

Required Permissions:: device (READ)

Returns:: The CSV raw data as returned from the server.
Return type:: str
Raises:: ApiError – If status values have not been set before calling this function.

execute_async()

Executes the current query in an asynchronous fashion.

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

facets(fieldlist, max_rows=0)

Return information about the facets for all known evices, using the defined criteria.

Example

>>> query = api.select(Device).where('')
>>> facets = query.facets(['policy_id', 'status', 'os', 'ad_group_id'])
>>> for f in facets:
...     print(f"Field {f.field} - {len(f.values_)} distinct values")

Required Permissions:: device (READ)

Parameters:

fieldlist (list[str]) – List of facet field names. Valid names are “policy_id”, “status”, “os”, “ad_group_id”, “cloud_provider_account_id”, “auto_scaling_group_name”, and “virtual_private_cloud_id”.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.

Returns:

A list of facet information.

Return type:

list[DeviceFacet]

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:

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:

quarantine(enable)

Set the quarantine option for the specified devices.

Required Permissions:: device.quarantine (EXECUTE)

Parameters:: enable (bool) – True to enable quarantine, False to disable it.
Returns:: The JSON output from the request.
Return type:: str

set_ad_group_ids(ad_group_ids)

Restricts the devices that this query is performed on to the specified AD group IDs.

Parameters:: ad_group_ids (list) – List of AD group IDs to restrict the search to.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid (non-int) values are passed in the list.

set_auto_scaling_group_name(group_names)

Restricts the devices that this query is performed on to the specified auto scaling group names.

Parameters:: group_names (list) – List of group names to restrict search to.
Returns:: This instance.
Return type:: DeviceSearchQuery

set_cloud_provider_account_id(account_ids)

Restricts the devices that this query is performed on to the specified cloud provider account IDs.

Parameters:: account_ids (list) – List of account IDs to restrict search to.
Returns:: This instance.
Return type:: DeviceSearchQuery

set_deployment_type(deployment_type)

Restricts the devices that this query is performed on to the specified deployment types.

Parameters:: deployment_type (list) – List of deployment types to restrict search to.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid deployment type values are passed in the list.

set_device_ids(device_ids)

Restricts the devices that this query is performed on to the specified device IDs.

Parameters:: device_ids (list) – List of device IDs to restrict the search to.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid (non-int) values are passed in the list.

set_exclude_sensor_versions(sensor_versions)

Restricts the devices that this query is performed on to exclude specified sensor versions.

Parameters:: sensor_versions (list) – List of sensor versions to be excluded.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid (non-string) values are passed in the list.

set_last_contact_time(*args, **kwargs)

Restricts the devices that this query is performed on to the specified last contact time.

Parameters:

*args (list) – Not used, retained for compatibility.
**kwargs (dict) – Keyword arguments to this function. The critical ones are “start” (the start time), “end” (the end time), and “range” (the range value).

Returns:

This instance.

Return type:

DeviceSearchQuery

Raises:

ApiError – If an invalid combination of keyword parameters are specified.

set_max_rows(max_rows)

Sets the max number of devices to fetch in a singular query

Parameters:: max_rows (integer) – Max number of devices
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If rows is negative or greater than 10000

set_os(operating_systems)

Restricts the devices that this query is performed on to the specified operating systems.

Parameters:: operating_systems (list) – List of operating systems to restrict search to. Valid values in this list are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER”.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid operating system values are passed in the list.

set_policy_ids(policy_ids)

Restricts the devices that this query is performed on to the specified policy IDs.

Parameters:: policy_ids (list) – List of policy IDs to restrict the search to.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid (non-int) values are passed in the list.

set_status(statuses)

Restricts the devices that this query is performed on to the specified status values.

Parameters:: statuses (list) – List of statuses to restrict search to. Valid values in this list are “PENDING”, “REGISTERED”, “UNINSTALLED”, “DEREGISTERED”, “ACTIVE”, “INACTIVE”, “ERROR”, “ALL”, “BYPASS_ON”, “BYPASS”, “QUARANTINE”, “SENSOR_OUTOFDATE”, “DELETED”, and “LIVE”.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid status values are passed in the list.

set_target_priorities(target_priorities)

Restricts the devices that this query is performed on to the specified target priority values.

Parameters:: target_priorities (list) – List of priorities to restrict search to. Valid values in this list are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:: This instance.
Return type:: DeviceSearchQuery
Raises:: ApiError – If invalid priority values are passed in the list.

set_virtual_private_cloud_id(cloud_ids)

Restricts the devices that this query is performed on to the specified virtual private cloud IDs.

Parameters:: cloud_ids (list) – List of cloud IDs to restrict search to.
Returns:: This instance.
Return type:: DeviceSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(Device).sort_by("status")

Parameters:

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

Returns:

This instance.

Return type:

DeviceSearchQuery

Raises:

ApiError – If an invalid direction value is passed.

uninstall_sensor()

Uninstall the specified sensor devices.

Required Permissions:: device.uninstall (EXECUTE)

Returns:: The JSON output from the request.
Return type:: str

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.

update_policy(policy_id)

Set the current policy for the specified devices.

Required Permissions:: device.policy (UPDATE)

Parameters:: policy_id (int) – ID of the policy to set for the devices.
Returns:: The JSON output from the request.
Return type:: str

update_sensor_version(sensor_version)

Update the sensor version for the specified devices.

Required Permissions:: org.kits (EXECUTE)

Parameters:: sensor_version (dict) – New version properties for the sensor.
Returns:: The JSON output from the request.
Return type:: str

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:

Events Module

Model and Query Classes for Events

class Event(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)

Events can be queried for via CBCloudAPI.select or an already selected process with Process.events().

Examples

>>> events_query = (api.select(Event).where(process_guid=
                    "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb"))
# retrieve results synchronously
>>> events = [event for event in events_query]
# retrieve results asynchronously
>>> future = events_query.execute_async()
>>> events = future.result()
# use an already selected process
>>> process = api.select(Process, "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")
>>> events_query = process.events()
>>> events = [event for event in events_query]

Initialize the Event object.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
model_unique_id (str) – The unique ID for this particular instance of the model object.
initial_data (dict) – The data to use when initializing the model object.
force_init (bool) – True to force object initialization.
full_doc (bool) – True to mark the object as fully initialized.

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.

class EventFacet(cb, model_unique_id, initial_data)

Represents the results of an EventFacetQuery.

EventFacet objects contain both Terms and Ranges. Each of those contain facet fields and values.

Access all of the Terms facet data with EventFacet.Terms.facets() or see just the field names with EventFacet.Terms.fields().

Access all of the Ranges facet data with EventFacet.Ranges.facets() or see just the field names with EventFacet.Ranges.fields().

Event Facets can be queried for via CBCloudAPI.select(EventFacet). Specify a Process GUID with `.where(process_guid=”example_guid”), and facet field(s) with .add_facet_field(“my_facet_field”).

Examples

>>> event_facet_query = (api.select(EventFacet).where(process_guid=
"WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb"))
>>> event_facet_query.add_facet_field("event_type")
# retrieve results synchronously
>>> facet = event_facet_query.results
# retrieve results asynchronously
>>> future = event_facet_query.execute_async()
>>> result = future.result()
# result is a list with one item, so access the first item
>>> facet = result[0]

Initialize an EventFacet object with initial_data.

class Ranges(cb, initial_data)

Represents the range (bucketed) facet fields and values associated with an Event Facet query.

Initialize a ProcessFacet Ranges object with initial_data.

property facets: Returns the reified EventFacet.Terms._facets for this result.

property fields: Returns the ranges 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

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

class Terms(cb, initial_data)

Represents the facet fields and values associated with an Event Facet query.

Initialize a ProcessFacet Terms object with initial_data.

property facets: Returns the terms’ facets for this result.

property fields: Returns the terms facets’ 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

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

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 ranges_: Returns the reified EventFacet.Ranges for this result.

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

property terms_: Returns the reified EventFacet.Terms for this result.

class EventFacetQuery(cls, cb, query=None)

Bases: FacetQuery

Represents the logic for an Event Facet query.

Initialize the FacetQuery object.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

add_exclusions(key, newlist)

Add to the excluions on this query with a custom exclusion key.

Parameters:

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

Returns:

The ResultQuery with specified custom exclusion.

Example

>>> query = api.select(Event).add_exclusions("netconn_domain", ["www.google.com"])
>>> query = api.select(Event).add_exclusions("netconn_domain", "www.google.com")

add_facet_field(field)

Sets the facet fields to be received by this query.

Parameters:: field (str or [str]) – Field(s) to be received.
Returns:: The Query object that will receive the specified field(s).
Return type:: Query (AsyncQuery)

Example

>>> cb.select(ProcessFacet).add_facet_field(["process_name", "process_username"])

add_range(range)

Sets the facet ranges to be received by this query.

Parameters:: range (dict or [dict]) – Range(s) to be received.
Returns:: The Query object that will receive the specified range(s).
Return type:: Query (AsyncQuery)

Note

The range parameter must be in this dictionary format:

{

“bucket_size”: “<object>”,

“start”: “<object>”,

“end”: “<object>”,

“field”: “<string>”

},

where “bucket_size”, “start”, and “end” can be numbers or ISO 8601 timestamps.

Examples

>>> cb.select(ProcessFacet).add_range({"bucket_size": 5, "start": 0, "end": 10, "field": "netconn_count"})
>>> cb.select(ProcessFacet).add_range({"bucket_size": "+1DAY", "start": "2020-11-01T00:00:00Z",
... "end": "2020-11-12T00:00:00Z", "field": "backend_timestamp"})

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:

execute_async()

Executes the current query in an asynchronous fashion.

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

limit(limit)

Sets the maximum number of facets per category (i.e. any Process Search Fields in self._fields).

The default limit for Process Facet searches in the Carbon Black Cloud backend is 100.

Parameters:: limit (int) – Maximum number of facets per category.
Returns:: The Query object with new limit parameter.
Return type:: Query (AsyncQuery)

Example

>>> cb.select(ProcessFacet).where(process_name="foo.exe").limit(50)

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:

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:

property results: Save query results to self._results with self._search() method.

set_rows(rows)

Sets the number of facet results to return with the query.

Parameters:: rows (int) – Number of rows to return.
Returns:: The Query object with the new rows parameter.
Return type:: Query (AsyncQuery)

Example

>>> cb.select(ProcessFacet).set_rows(50)

set_time_range(start=None, end=None, window=None)

Sets the ‘time_range’ query body parameter, determining a time window based on ‘device_timestamp’.

Parameters:

start (str in ISO 8601 timestamp) – When to start the result search.
end (str in ISO 8601 timestamp) – When to end the result search.
window (str) – Time window to execute the result search, ending on the current time.
"-2w" (Should be in the form) –
y=year (where) –
w=week –
d=day –
h=hour –
m=minute –
s=second. –

Note

window will take precendent over start and end if provided.

Examples

>>> query = api.select(Event).set_time_range(start="2020-10-20T20:34:07Z")
>>> second_query = api.select(Event).
...     set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z")
>>> third_query = api.select(Event).set_time_range(window='-3d')

timeout(msecs)

Sets the timeout on an AsyncQuery. By default, there is no timeout.

Parameters:: msecs (int) – Timeout duration, in milliseconds.
Returns:: The Query object with new milliseconds parameter.
Return type:: Query (AsyncQuery)

Example

>>> cb.select(ProcessFacet).where(process_name="foo.exe").timeout(5000)

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:

class EventQuery(doc_class, cb)

Bases: Query

Represents the logic for an Event query.

Initialize the Query object.

Parameters:

doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the CBCloudAPI object.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

add_exclusions(key, newlist)

Add to the excluions on this query with a custom exclusion key.

Parameters:

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

Returns:

The ResultQuery with specified custom exclusion.

Example

>>> query = api.select(Event).add_exclusions("netconn_domain", ["www.google.com"])
>>> query = api.select(Event).add_exclusions("netconn_domain", "www.google.com")

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:

batch_size(new_batch_size)

Set the batch size of the paginated query.

Parameters:: new_batch_size (int) – The new batch size.
Returns:: A new query with the updated batch size.
Return type:: PaginatedQuery

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:

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:

set_fields(fields)

Sets the fields to be returned with the response.

Parameters:: fields (str or list[str]) – Field or list of fields to be returned.

set_rows(rows)

Sets the ‘rows’ query body parameter, determining how many rows of results to request.

Parameters:: rows (int) – How many rows to request.

set_start(start)

Sets the ‘start’ query body parameter, determining where to begin retrieving results from.

Parameters:: start (int) – Where to start results from.

set_time_range(start=None, end=None, window=None)

Sets the ‘time_range’ query body parameter, determining a time window based on ‘device_timestamp’.

Parameters:

start (str in ISO 8601 timestamp) – When to start the result search.
end (str in ISO 8601 timestamp) – When to end the result search.
window (str) – Time window to execute the result search, ending on the current time. Should be in the form “-2w”, where y=year, w=week, d=day, h=hour, m=minute, s=second.

Note

window will take precendent over start and end if provided.

Examples

>>> query = api.select(Event).set_time_range(start="2020-10-20T20:34:07Z")
>>> second_query = api.select(Event).
...     set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z")
>>> third_query = api.select(Event).set_time_range(window='-3d')

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:

The query with sorting parameters.

Return type:

Example

>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")

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:

Grants Module

Model and Query Classes for Administrative Grants and Profiles

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

Represents a grant of access to the Carbon Black Cloud.

Parameters:

principal – URN of principal
expires – Date and time the grant expires
roles – URNs of roles assigned to grant (obsolete)
profiles – Profiles assigned to this grant
org_ref – URN of org that this grant references
principal_name – Name of principal
created_by – URN of user that created this grant
updated_by – URN of user that last updated this grant
create_time – Date and time the grant was created
update_time – Date and time the grant was last updated
can_manage – True if can manage (TBD)

Initialize the Grant object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – URN of the principal associated with this grant.
initial_data (dict) – Initial data used to populate the grant.

class GrantBuilder(cb, principal)

Bases: object

Auxiliary object used to construct a new grant.

Creates the empty GrantBuilder object.

Parameters:

cb (CBCloudAPI) – The reference to the API object that accesses the server.
principal (str) – The URN for the principal.

add_role(role)

Adds a role to be associated with the new grant.

Parameters:: role (str) – URN of the role to be added.
Returns:: This object.
Return type:: GrantBuilder

build()

Builds the new Grant object from the entered data.

Returns:: The new Grant object.
Return type:: Grant

create_profile(template=None)

Returns either a new Profile, or a ProfileBuilder to begin the process of adding profile to the new grant.

Parameters:

template (dict) – Optional template to use for creating the profile object.

Returns:

If a template was specified, return the new Profile object.

ProfileBuilder: If template was None, returns a ProfileBuilder object. Call methods on it to set up the new profile, and then call build() to create the new profile.

Return type:

Profile

set_org(org)

Sets the organization reference to be associated with the new grant.

Parameters:: org (str) – Organization key or URN of the organization.
Returns:: This object.
Return type:: GrantBuilder

set_principal_name(name)

Sets the principal name to be associated with the new object.

Parameters:: name (str) – Principal name to be used.
Returns:: This object.
Return type:: GrantBuilder

set_roles(roles)

Sets the roles to be associated with the new grant.

Parameters:: roles (list) – List of role URNs.
Returns:: This object.
Return type:: GrantBuilder

class Profile(cb, grant, model_unique_id, initial_data=None)

Represents an access profile assigned to a grant.

Parameters:

profile_uuid – UUID identifying this profile
orgs – Organization references for this profile
org_groups – Organization groups added to this grant (TBD)
roles – URNs of roles assigned to profile
conditions – Access conditions to be imposed on this profile
can_manage – True if can manage (TBD)

Initialize the Profile object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
grant (Grant) – Reference to the Grant containing this Profile.
model_unique_id (str) – UUID of this profile.
initial_data (dict) – Initial data used to populate the profile.

property allowed_orgs: Returns the list of organization URNs allowed by this profile.

delete(): Delete this object.

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

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

matches_template(template)

Returns whether or not the profile matches the given template.

Parameters:: template (dict) – The profile template to match against.
Returns:: True if this profile matches the template, False if not.
Return type:: bool

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

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

set_disabled(flag)

Sets the “disabled” flag on a profile.

Parameters:: flag (bool) – True to disable the profile, False to enable it.

set_expiration(expiration)

Sets the expiration time on a profile.

Parameters:: expiration (str) – Expiration time to set on the profile (ISO 8601 format).

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this object.

Returns:: True if the object is validated.
Return type:: bool
Raises:: InvalidObjectError – If the object has missing fields.

class ProfileBuilder(grant)

Bases: object

Auxiliary object used to construct a new profile on a grant.

Create the empty ProfileBuilder object.

Parameters:: grant (Grant/GrantBuilder) – The grant or GrantBuilder the new profile will be attached to.

add_org(org)

Adds the specified organization to the list of organizations for which the new profile is allowed.

Parameters:: org (str) – Organization key or URN of the organization to be added.
Returns:: This object.
Return type:: ProfileBuilder

add_role(role)

Adds a role identifier to the list of roles associated with the new profile.

Parameters:: role (str) – URN of the role to add.
Returns:: This object.
Return type:: ProfileBuilder

build()

Builds the new Profile object from the entered data.

Returns:: The new Profile object.
Return type:: Profile

set_conditions(conditions_structure)

Sets the access conditions associated with the new profile.

Parameters:: conditions_structure (dict) – The conditions associated with the new profile, with ‘cidr’, ‘expiration’, and ‘disabled’ members.
Returns:: This object.
Return type:: ProfileBuilder

set_disabled(flag)

Sets whether or not the new profile is disabled.

Parameters:: flag (bool) – True if this profile is disabled, False if noe.
Returns:: This object.
Return type:: ProfileBuilder

set_expiration(expiration)

Sets the expiration time on the new profile.

Parameters:: expiration (str) – The expiration time, specified as ISO 8601.
Returns:: This object.
Return type:: ProfileBuilder

set_orgs(orgs_list)

Set the list of organizations to which the new profile is allowed access.

Parameters:: orgs_list (list) – List of organization keys or URNs.
Returns:: This object.
Return type:: ProfileBuilder

set_roles(roles_list)

Sets the list of roles associated with the new profile.

Parameters:: roles_list (list) – A list of role URNs.
Returns:: This object.
Return type:: ProfileBuilder

classmethod create(cb, template=None, **kwargs)

Returns either a new Grant, or a GrantBuilder to begin the process of creating a new grant.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
template (dict) – Optional template to use for creating the grant object.
kwargs (dict) – Additional arguments to be used to specify the principal, if template is None.
ID. (The arguments to be used are 'org_key' and 'userid' for the two parts of the) –

Returns:

The new grant object, if the template is specified.

GrantBuilder: If template was None, returns a GrantBuilder object. Call methods on it to set up the new grant, and then call build() to create the new grant.

Return type:

Grant

Raises:

ApiError – If the principal is inadequately specified (whether for the Grant or GrantBuilder).

create_profile(template=None)

Returns either a new Profile, or a ProfileBuilder to begin the process of adding a new profile to this grant.

Parameters:

template (dict) – Optional template to use for creating the profile object.

Returns:

If a template was specified, return the new Profile object.

ProfileBuilder: If template was None, returns a ProfileBuilder object. Call methods on it to set up the new profile, and then call build() to create the new profile.

Return type:

Profile

delete(): Delete this object.

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

classmethod get_permitted_role_urns(cb)

Returns a list of the URNs of all permitted roles that we can assign to a user.

Parameters:: cb (CBCloudAPI) – A reference to the CBCloudAPI object.
Returns:: A list of string role URNs that we are permitted to manage (assign to users).
Return type:: list

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

property profiles_

Return the profiles associated with this grant.

Returns:: The profiles associated with this grant, each represented as a Profile object.
Return type:: list

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

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this object.

Returns:: True if the object is validated.
Return type:: bool
Raises:: InvalidObjectError – If the object has missing fields.

class GrantQuery(doc_class, cb)

Bases: BaseQuery, IterableQueryMixin, AsyncQueryMixin

Query for retrieving grants in bulk.

Initialize the Query object.

Parameters:

doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the CBCloudAPI object.

add_principal(principal_urn, org_urn)

Add a new principal to the query.

Parameters:

principal_urn (str) – URN of the principal to search for grants on.
org_urn (str) – URN of the organization to which the principal belongs.

Returns:

This object.

Return type:

GrantQuery

all()

Returns all the items of a query as a list.

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

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

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

log = <Logger cbc_sdk.platform.grants (WARNING)>: Grant and Profile Models

normalize_org(org): Internal function to normalize an org reference to a URN.

Jobs Module

Model and Query Classes for Jobs API

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

Bases: NewBaseModel

Represents a job currently executing in the background.

Parameters:

connector_id – Connector ID for the job
create_time – Time this job was created
errors – Errors for the job
id – ID of the job
job_parameters – Parameters that were used for this job
last_update_time – Last time this job was updated
org_key – Organization key of the org this job is being run against
owner_id – ID of the job owner
status – Current job status
type – Type of job this is

Initialize the Job object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (int) – ID of the job.
initial_data (dict) – Initial data used to populate the job.

await_completion()

Create a Python Future to check for job completion and return results when available.

Returns a Future object which can be used to await results that are ready to fetch. This function call does not block.

Required Permissions:: jobs.status(READ)

Returns:

A future which can be used to wait for this job’s completion. When complete, the result of the: Future will be this object.

Return type:

Future

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

get_output_as_file(filename)

Export the results from the job, writing the results to the given file.

Required Permissions:: jobs.status(READ)

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

get_output_as_lines()

Export the results from the job, returning the data as iterated lines of text.

This is only intended for output that can reasonably be represented as lines of text, such as plain text or CSV. If a job outputs structured text like JSON or XML, this method should not be used.

Required Permissions:: jobs.status(READ)

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

get_output_as_stream(output)

Export the results from the job, writing the results to the given stream.

Required Permissions:: jobs.status(READ)

Parameters:: output (RawIOBase) – Stream to write the CSV data from the request to.

get_output_as_string()

Export the results from the job, returning the results as a string.

Required Permissions:: jobs.status(READ)

Returns:: The results from the job.
Return type:: str

get_progress()

Get and return the current progress information for the job.

Required Permissions:: jobs.status(READ)

Returns:: Total number of items to be operated on by this job. int: Total number of items for which operation has been completed. str: Current status message for the job.
Return type:: int

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

class JobQuery(doc_class, cb)

Bases: BaseQuery, IterableQueryMixin, AsyncQueryMixin

Query for retrieving current jobs.

Initialize the Query object.

Parameters:

doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the CBCloudAPI object.

all()

Returns all the items of a query as a list.

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

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

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

Network Threat Metadata Module

Model Class for NetworkThreatMetadata

class NetworkThreatMetadata(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)

Bases: NewBaseModel

Represents a NetworkThreatMetadata

Parameters:

detector_abstract – Abstract or description of the detector
detector_goal – Description of what the detector is achieving
false_negatives – Highlights why detector could not have been triggered
false_positives – Highlights why detector could have been triggered
threat_public_comment – Public comment of the threat

Initialize the NetworkThreatMetadata object.

Required Permissions:: org.xdr.metadata (READ)

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
model_unique_id (Any) – The unique ID for this particular instance of the model object.
initial_data (dict) – Not used, retained for compatibility.
force_init (bool) – False to not force object initialization.
full_doc (bool) – True to mark the object as fully initialized.

Raises:

ApiError – if model_unique_id is not provided

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.

Observations Module

Model and Query Classes for Observations

class Observation(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: NewBaseModel

Represents an Observation

Initialize the Observation object.

Required Permissions:: org.search.events (READ)

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
model_unique_id (Any) – The unique ID for this particular instance of the model object.
initial_data (dict) – The data to use when initializing the model object.
force_init (bool) – True to force object initialization.
full_doc (bool) – False to mark the object as not fully initialized.

static bulk_get_details(cb, alert_id=None, observation_ids=None, timeout=0)

Bulk get details

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
alert_id (str) – An alert id to fetch associated observations
observation_ids (list) – A list of observation ids to fetch
timeout (int) – Observations details request timeout in milliseconds.

Returns:

list of Observations

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

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

get_details(timeout=0, async_mode=False)

Requests detailed results.

Parameters:

timeout (int) – Observations details request timeout in milliseconds.
async_mode (bool) – True to request details in an asynchronous manner.

Returns:

Observation object enriched with the details fields

Return type:

Observation

Note

When using asynchronous mode, this method returns a python future. You can call result() on the future object to wait for completion and get the results.

Examples

>>> observation = api.select(Observation, observation_id)
>>> observation.get_details()

>>> observations = api.select(Observation).where(process_pid=2000)
>>> observations[0].get_details()

get_network_threat_metadata()

Requests Network Threat Metadata.

Returns:: Get the metadata for a given detector (rule).
Return type:: NetworkThreatMetadata
Raises:: ApiError – when rule_id is not returned for the Observation

Examples

>>> observation = api.select(Observation, observation_id)
>>> threat_metadata = observation.get_network_threat_metadata()

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

static search_suggestions(cb, query, count=None)

Returns suggestions for keys and field values that can be used in a search.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
query (str) – A search query to use.
count (int) – (optional) Number of suggestions to be returned

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

class ObservationFacet(cb, model_unique_id, initial_data)

Represents an observation facet retrieved.

Parameters:

terms – Contains the Observations Facet search results
ranges – Groupings for search result properties that are ISO 8601 timestamps or numbers
contacted – The number of searchers contacted for this query
completed – The number of searchers that have reported their results

Initialize the Terms object with initial data.

class Ranges(cb, initial_data)

Represents the range (bucketed) facet fields and values associated with an Observation Facet query.

Initialize an ObservationFacet Ranges object with initial_data.

property facets: Returns the reified ObservationFacet.Terms._facets for this result.

property fields: Returns the ranges 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

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

class Terms(cb, initial_data)

Represents the facet fields and values associated with an Observation Facet query.

Initialize an ObservationFacet Terms object with initial_data.

property facets: Returns the terms’ facets for this result.

property fields: Returns the terms facets’ 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

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

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 ranges_: Returns the reified ObservationFacet.Ranges for this result.

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

property terms_: Returns the reified ObservationFacet.Terms for this result.

class ObservationGroup(cb, initial_data=None)

Bases: object

Represents ObservationGroup

Initialize ObservationGroup object

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.
initial_data (dict) – The data to use when initializing the model object.

Notes

The constructed object will have the following data: - group_start_timestamp - group_end_timestamp - group_key - group_value

class ObservationQuery(doc_class, cb)

Bases: Query

Represents the query logic for an Observation query.

This class specializes Query to handle the particulars of observations querying.

Initialize the ObservationQuery object.

Parameters:

doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the CBCloudAPI object.

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(Event).add_criteria("event_type", ["filemod", "scriptload"])
>>> query = api.select(Event).add_criteria("event_type", "filemod")

add_exclusions(key, newlist)

Add to the excluions on this query with a custom exclusion key.

Parameters:

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

Returns:

The ResultQuery with specified custom exclusion.

Example

>>> query = api.select(Event).add_exclusions("netconn_domain", ["www.google.com"])
>>> query = api.select(Event).add_exclusions("netconn_domain", "www.google.com")

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:

batch_size(new_batch_size)

Set the batch size of the paginated query.

Parameters:: new_batch_size (int) – The new batch size.
Returns:: A new query with the updated batch size.
Return type:: PaginatedQuery

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

get_group_results(fields, max_events_per_group=None, rows=500, start=None, range_duration=None, range_field=None, range_method=None)

Get group results grouped by provided fields.

Parameters:

fields (str / list) – field or fields by which to perform the grouping
max_events_per_group (int) – Maximum number of events in a group, if not provided, all events will be returned
rows (int) – Number of rows to request, can be paginated
start (int) – First row to use for pagination
ranges (dict) – dict with information about duration, field, method

Returns:

grouped results

Return type:

dict

Examples

>>> for group in api.select(Observation).where(process_pid=2000).get_group_results("device_name"):
>>>     ...

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:

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_(**kwargs)

or_() criteria are explicitly provided to Observation queries.

This method overrides the base class in order to provide or_() functionality rather than raising an exception.

set_fields(fields)

Sets the fields to be returned with the response.

Parameters:: fields (str or list[str]) – Field or list of fields to be returned.

set_rows(rows)

Sets the ‘rows’ query body parameter to the ‘start search’ API call, determining how many rows to request.

Parameters:: rows (int) – How many rows to request.
Returns:: ObservationQuery object
Return type:: Query

Example

>>> cb.select(Observation).where(process_name="foo.exe").set_rows(50)

set_start(start)

Sets the ‘start’ query body parameter, determining where to begin retrieving results from.

Parameters:: start (int) – Where to start results from.

set_time_range(start=None, end=None, window=None)

Sets the ‘time_range’ query body parameter, determining a time window based on ‘device_timestamp’.

Parameters:

start (str in ISO 8601 timestamp) – When to start the result search.
end (str in ISO 8601 timestamp) – When to end the result search.
window (str) – Time window to execute the result search, ending on the current time. Should be in the form “-2w”, where y=year, w=week, d=day, h=hour, m=minute, s=second.

Note

window will take precendent over start and end if provided.

Examples

>>> query = api.select(Event).set_time_range(start="2020-10-20T20:34:07Z")
>>> second_query = api.select(Event).
...     set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z")
>>> third_query = api.select(Event).set_time_range(window='-3d')

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:

The query with sorting parameters.

Return type:

Example

>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")

timeout(msecs)

Sets the timeout on a observation query.

Parameters:

msecs (int) – Timeout duration, in milliseconds.

Returns:

The Query object with new milliseconds: parameter.

Return type:

Query (ObservationQuery)

Example

>>> cb.select(Observation).where(process_name="foo.exe").timeout(5000)

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:

Policies Module

Policy implementation as part of Platform API

class Policy(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Represents a policy within the organization.

Create one of these objects (either directly or with the CBCloudAPI.create() method) and set its properties, then call its save() method to create the policy on the server. This requires the org.policies(CREATE) permission.

Alternatively, you may call Policy.create() to get a PolicyBuilder, use its methods to set the properties of the new policy, call its build() method to build the populated Policy, then call the policy save() method.

To update a Policy, change the values of its property fields, then call the policy’s save() method. This requires the org.policies(UPDATE) permission.

To delete an existing Policy, call its delete() method. This requires the org.policies(DELETE) permission.

For information on values for policy settings including enumeration values, see the Policy Service API page: https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/policy-service/#fields

Parameters:

id – The policy identifier
name – Defined name for the policy
org_key – The organization key associated with the console instance
priority_level – The priority level designated for policy
is_system – Indicates that the policy was created by VMware
description – The description of the policy
auto_deregister_inactive_vdi_interval_ms – The time in milliseconds to wait after a VDI is inactive before setting the VDI to a DEREGISTERED state
auto_delete_known_bad_hashes_delay – Enables the Carbon Black Cloud to automatically delete known malware after a specified time in milliseconds
av_settings – Anti-Virus settings for endpoints and workloads assigned to the policy
rules – Permission or prevention rules
directory_action_rules – Rules to deny or allow the deployed sensors to send uploads from specific paths
sensor_settings – Settings to configure sensor behavior and capabilities
managed_detection_response_permissions – Permissions for Managed Detection and Response analysts to perform remediations on endpoints and workloads assigned to the policy
version – Version of the policy

Initialize the Policy object.

Required Permissions:: org.policies (READ)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (int) – ID of the policy.
initial_data (dict) – Initial data used to populate the policy.
force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
full_doc (bool) – If True, object is considered “fully” initialized. Default False.

class PolicyBuilder(cb)

Bases: object

Builder object to simplify the creation of new Policy objects.

To use, call Policy.create() to get a PolicyBuilder, use its methods to set the properties of the new policy, call its build() method to build the populated Policy, then call the policy save() method. The org.policy(CREATE) permission is required.

Examples

>>> builder = Policy.create(api)
>>> builder.set_name("New Policy").set_priority("MEDIUM").set_description("New policy description")
>>> # more calls here to set up rules, sensor settings, etc.
>>> policy = builder.build()
>>> policy.save()

Initialize the PolicyBuilder object.

Parameters:: cb (BaseAPI) – Reference to API object used to communicate with the server.

add_directory_action_rule(path, file_upload, protection)

Add a directory action rule to the new policy.

Parameters:

path (str) – Path to the file or directory.
file_upload (bool) – True to allow the deployed sensor to upload from that path.
protection (bool) – True to deny the deployed sensor to upload from that path.

Returns:

This object.

Return type:

add_rule(app_type, app_value, operation, action, required=True)

Add a new rule as discrete data elements to the new policy.

Parameters:

app_type (str) – Specifies “NAME_PATH”, “SIGNED_BY”, or “REPUTATION”.
app_value (str) – Value of the attribute specified by app_type to be matched.
operation (str) – The type of behavior the application is performing.
action (str) – The action the sensor will take when the application performs the specified action.
required (bool) – True if this rule is required, False if not.

Returns:

This object.

Return type:

Raises:

InvalidObjectError – If the rule data passed in is not valid.

add_rule_config(config_id, name, category, **kwargs)

Add a new rule configuration as discrete data elements to the new policy.

Parameters:

config_id (str) – ID of the rule configuration object (a GUID).
name (str) – Name of the rule configuration object.
category (str) – Category of the rule configuration object.
**kwargs (dict) – Parameter values for the rule configuration object.

Returns:

This object.

Return type:

Raises:

InvalidObjectError – If the rule configuration data passed in is not valid.

add_rule_config_copy(rule_config)

Adds a copy of an existing rule configuration to this new policy.

Parameters:: rule_config (PolicyRuleConfig) – The rule configuration to copy and add to this object.
Returns:: This object.
Return type:: PolicyBuilder
Raises:: InvalidObjectError – If the rule configuration data passed in is not valid.

add_rule_copy(rule)

Adds a copy of an existing rule to this new policy.

Parameters:: rule (PolicyRule) – The rule to copy and add to this object.
Returns:: This object.
Return type:: PolicyBuilder
Raises:: InvalidObjectError – If the rule data passed in is not valid.

add_sensor_setting(name, value)

Add a sensor setting to the policy.

Parameters:

name (str) – Sensor setting name.
value (str) – Sensor setting value.

Returns:

This object.

Return type:

Raises:

ApiError – If the sensor setting name is not a valid one.

build()

Build a new Policy object using the contents of this builder.

The new policy must have save() called on it to be saved to the server.

Returns:: The new Policy object.
Return type:: Policy

set_auto_delete_bad_hash_delay(delay)

Set the delay in milliseconds after which known malware will be deleted.

Parameters:: delay (int) – The desired delay interval in milliseconds.
Returns:: This object.
Return type:: PolicyBuilder

set_auto_deregister_interval(interval)

Set the time in milliseconds after a VDI goes inactive to deregister it.

Parameters:: interval (int) – The desired interval in milliseconds.
Returns:: This object.
Return type:: PolicyBuilder

set_avira_protection_cloud(enabled, max_exe_delay=None, max_file_size=None, risk_level=None)

Set the settings for third-party unknown binary reputation analysis.

Parameters:

enabled (bool) – True to enable unknown binary reputation analysis.
max_exe_delay (int) – Time before sending unknown binary for analysis, in seconds.
max_file_size (int) – Maximum size of file to send for analysis, in megabytes.
risk_level (int) – Risk level to send for analysis (0-7).

Returns:

This object.

Return type:

set_description(descr)

Set the new policy description.

Parameters:: descr (str) – The new policy description.
Returns:: This object.
Return type:: PolicyBuilder

set_managed_detection_response_permissions(policy_mod, quarantine)

Set the permissions for managed detection and response.

Parameters:

policy_mod (bool) – True to allow MDR team to modify the policy.
quarantine (bool) – True to allow MDR team to quarantine endpoints/workloads associated with the policy.

Returns:

This object.

Return type:

set_name(name)

Set the new policy name.

Parameters:: name (str) – The new policy name.
Returns:: This object.
Return type:: PolicyBuilder

set_on_access_scan(enabled, mode='NORMAL')

Sets the local scan settings.

Parameters:

enabled (bool) – True to enable local scan.
mode (str) – The mode to operate in, either “NORMAL” or “AGGRESSIVE”.

Returns:

This object.

Return type:

Raises:

ApiError – If an invalid value is passed for the “mode” parameter.

set_on_demand_scan(enabled, profile='NORMAL', scan_usb='AUTOSCAN', scan_cd_dvd='AUTOSCAN')

Sets the background scan settings.

Parameters:

enabled (bool) – True to enable background scan.
profile (str) – The background scan mode, either “NORMAL” or “AGGRESSIVE”.
scan_usb (str) – Either “AUTOSCAN” to scan USB devices, or “DISABLED” to not do so.
scan_cd_dvd (str) – Either “AUTOSCAN” to scan CDs and DVDs, or “DISABLED” to not do so.

Returns:

This object.

Return type:

Raises:

ApiError – If an invalid value is passed for any parameter.

set_on_demand_scan_schedule(days, start_hour, range_hours, recover_if_missed=True)

Sets the schedule for when background scans will be performed.

Parameters:

days (list[str]) – The days on which to perform background scans.
start_hour (int) – The hour of the day at which to perform the scans.
range_hours (int) – The range of hours over which to perform the scans.
recover_if_missed (bool) – True if the background scan should be performed ASAP if it’s been missed.

Returns:

This object.

Return type:

Raises:

ApiError – If an invalid value is passed for a day of the week.

set_priority(priority)

Set the new policy’s priority. Default is MEDIUM.

Parameters:: priority (str) – The priority, either “LOW”, “MEDIUM”, “HIGH”, or “MISSION_CRITICAL”.
Returns:: This object.
Return type:: PolicyBuilder
Raises:: ApiError – If an invalid priority value is passed in.

set_signature_update(enabled)

Set the enable status for signature updates.

Parameters:: enabled (bool) – True to enable signature updates.
Returns:: This object.
Return type:: PolicyBuilder

set_signature_update_schedule(full_interval_hours, initial_random_delay_hours, interval_hours)

Set the signature update schedule.

Parameters:

full_interval_hours (int) – The interval in hours between signature updates.
initial_random_delay_hours (int) – The initial delay in hours before the first signature update.
interval_hours (int) – The interval in hours between signature updates.

Returns:

This object.

Return type:

set_update_servers_offsite(names)

Sets the list of update servers for offsite devices.

Parameters:: names (list[str]) – The list of update servers, as URIs.
Returns:: This object.
Return type:: PolicyBuilder

set_update_servers_onsite(names, preferred_servers=None)

Sets the list of update servers for internal devices.

Parameters:

names (list[str]) – The list of available update servers, as URIs.
preferred_servers (list[str]) – The list of update servers to be considered “preferred,” as URIs.

Returns:

This object.

Return type:

set_update_servers_override(names)

Sets the list of update servers to override offsite/onsite settings.

Parameters:: names (list[str]) – The server names to use, as a list of URIs.
Returns:: This object.
Return type:: PolicyBuilder

add_rule(new_rule)

Adds a rule to this Policy.

Parameters:: new_rule (dict(str,str)) – The new rule to add to this Policy.

Notes

The new rule must conform to this dictionary format:

{“action”: “ACTION”, “application”: {“type”: “TYPE”, “value”: “VALUE”}, “operation”: “OPERATION”, “required”: “REQUIRED”}
The dictionary keys have these possible values:

“action”: [“IGNORE”, “ALLOW”, “DENY”, “TERMINATE_PROCESS”, “TERMINATE_THREAD”, “TERMINATE”]

“type”: [“NAME_PATH”, “SIGNED_BY”, “REPUTATION”]

“value”: Any string value to match on

“operation”: [“BYPASS_ALL”, “INVOKE_SCRIPT”, “INVOKE_SYSAPP”, “POL_INVOKE_NOT_TRUSTED”, “INVOKE_CMD_INTERPRETER”, “RANSOM”, “NETWORK”, “PROCESS_ISOLATION”, “CODE_INJECTION”, “MEMORY_SCRAPE”, “RUN_INMEMORY_CODE”, “ESCALATE”, “RUN”]

“required”: [True, False]

property core_prevention_rule_configs

Returns a dictionary of core prevention rule configuration IDs and objects for this Policy.

Returns:

A dictionary with core prevention rule configuration IDs as keys and CorePreventionRuleConfig objects: as values.

Return type:

dict

property core_prevention_rule_configs_list

Returns a list of core prevention rule configuration objects for this Policy.

Returns:: A list of CorePreventionRuleConfig objects.
Return type:: list

classmethod create(cb)

Begins creating a policy by returning a PolicyBuilder.

Parameters:: cb (BaseAPI) – Reference to API object used to communicate with the server.
Returns:: The new policy builder object.
Return type:: PolicyBuilder

property data_collection_rule_configs

Returns a dictionary of data collection rule configuration IDs and objects for this Policy.

Returns:

A dictionary with data collection rule configuration IDs as keys and DataCollectionRuleConfig objects: as values.

Return type:

dict

property data_collection_rule_configs_list

Returns a list of data collection rule configuration objects for this Policy.

Returns:: A list of DataCollectionRuleConfig objects.
Return type:: list

delete(): Delete this object.

delete_rule(rule_id)

Deletes a rule from this Policy.

Parameters:: rule_id (int) – The ID of the rule to be deleted.
Raises:: ApiError – If the rule ID does not exist in this policy.

delete_rule_config(rule_config_id)

Deletes a rule configuration from this Policy.

Parameters:: rule_config_id (str) – The ID of the rule configuration to be deleted.
Raises:: ApiError – If the rule configuration ID does not exist in this policy.

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

get_ruleconfig_parameter_schema(ruleconfig_id)

Returns the parameter schema for a specified rule configuration.

Uses cached rule configuration presentation data if present.

Parameters:: ruleconfig_id (str) – The rule configuration ID (UUID).
Returns:: The parameter schema for this particular rule configuration (a JSON schema).
Return type:: dict
Raises:: InvalidObjectError – If the rule configuration ID is not valid.

property host_based_firewall_rule_config

Returns the host-based firewall rule configuration for this policy.

Returns:: The host-based firewall rule configuration, or None.
Return type:: HostBasedFirewallRuleConfig
Raises:: InvalidObjectError – If there’s more than one host-based firewall rule configuration (should not happen).

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

property latestRevision: Returns the latest revision of this policy (compatibility method).

property object_rule_configs

Returns a dictionary of rule configuration IDs and objects for this Policy.

Returns:: A dictionary with rule configuration IDs as keys and PolicyRuleConfig objects as values.
Return type:: dict

property object_rule_configs_list

Returns a list of rule configuration objects for this Policy.

Returns:: A list of PolicyRuleConfig objects.
Return type:: list

property object_rules

Returns a dictionary of rule objects and rule IDs for this Policy.

Returns:: A dictionary with rule IDs as keys and PolicyRule objects as values.
Return type:: dict

property policy: Returns the contents of this policy [compatibility method].

property priorityLevel: Returns the priority level of this policy (compatibility method).

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

replace_rule(rule_id, new_rule)

Replaces a rule in this policy.

Parameters:

rule_id (int) – The ID of the rule to be replaced.
new_rule (dict) – The data for the new rule.

Raises:

ApiError – If the rule ID does not exist in this policy.

replace_rule_config(rule_config_id, new_rule_config)

Replaces a rule configuration in this policy.

Parameters:

rule_config_id (str) – The ID of the rule configuration to be replaced.
new_rule_config (dict) – The data for the new rule configuration.

Raises:

ApiError – If the rule configuration ID does not exist in this policy.

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

property systemPolicy: Returns whether or not this is a systsem policy (compatibility method).

touch(fulltouch=False): Force this object to be considered as changed.

valid_rule_configs()

Returns a dictionary identifying all valid rule configurations for this policy.

Returns:

A dictionary mapping string ID values (UUIDs) to dicts containing entries for name, description,: and category.

Return type:

dict

validate()

Validates this object.

Returns:: True if the object is validated.
Return type:: bool
Raises:: InvalidObjectError – If the object has missing fields.

class PolicyQuery(doc_class, cb)

Bases: BaseQuery, IterableQueryMixin, AsyncQueryMixin

Query for retrieving policies (summary info only).

Initialize the Query object.

Parameters:

doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the CBCloudAPI object.

add_descriptions(descrs)

Add policy description(s) to the list to search for.

Parameters:: descrs (str/list) – Either a single policy description or a list of descriptions.
Returns:: This object instance.
Return type:: PolicyQuery
Raises:: ApiError – If not supplied with a string or a list of strings.

add_names(names)

Add policy name(s) to the list to search for.

Parameters:: names (str/list) – Either a single policy name or a list of names.
Returns:: This object instance.
Return type:: PolicyQuery
Raises:: ApiError – If not supplied with a string or a list of strings.

add_policy_ids(ids)

Add policy ID(s) to the list to search for.

Parameters:: ids (int/list) – Either a single policy ID or a list of IDs.
Returns:: This object instance.
Return type:: PolicyQuery
Raises:: ApiError – If not supplied with an int or a list of ints.

add_priorities(priorities)

Add policy priority/priorities to the list to search for.

Parameters:: priorities (str/list) – Either a single policy priority value or a list of priority values.
Returns:: This object instance.
Return type:: PolicyQuery
Raises:: ApiError – If not supplied with a string priority value or a list of string priority values.

all()

Returns all the items of a query as a list.

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

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

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_system(system)

Set to look for either system or non-system policies.

Parameters:: system (bool) – True to look for system policies, False to look for non-system policies.
Returns:: This object instance.
Return type:: PolicyQuery
Raises:: ApiError – If not supplied with a Boolean.

class PolicyRule(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Represents a rule in the policy.

Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule to the policy. This requires the org.policies(UPDATE) permission.

To update a PolicyRule, change the values of its property fields, then call the rule’s save() method. This requires the org.policies(UPDATE) permission.

To delete an existing PolicyRule, call its delete() method. This requires the org.policies(UPDATE) permission.

Parameters:

id – The identifier of the rule
action – The action the sensor will take when an application attempts to perform the selected operation
application – The path, signature or reputation of the application
operation – The type of behavior an application is performing

Initialize the PolicyRule object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
parent (Policy) – The “parent” policy of this rule.
model_unique_id (int) – ID of the rule.
initial_data (dict) – Initial data used to populate the rule.
force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
full_doc (bool) – If True, object is considered “fully” initialized. Default False.

delete(): Delete this object.

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 is_deleted: Returns True if this rule object has been deleted.

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

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

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this rule against its constraints.

Raises:: InvalidObjectError – If the rule object is not valid.

RuleConfigs Module

Policy rule configuration implementation as part of Platform API

class CorePreventionRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: PolicyRuleConfig

Represents a core prevention rule configuration in the policy.

Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule configuration to the policy. This requires the org.policies(UPDATE) permission.

To update a CorePreventionRuleConfig, change the values of its property fields, then call its save() method. This requires the org.policies(UPDATE) permission.

To delete an existing CorePreventionRuleConfig, call its delete() method. This requires the org.policies(DELETE) permission.

Parameters:

id – The ID of this rule config
name – The name of this rule config
description – The description of this rule config
inherited_from – Indicates where the rule config was inherited from
category – The category for this rule config
parameters – The parameters associated with this rule config

Initialize the CorePreventionRuleConfig object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
parent (Policy) – The “parent” policy of this rule configuration.
model_unique_id (str) – ID of the rule configuration.
initial_data (dict) – Initial data used to populate the rule configuration.
force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
full_doc (bool) – If True, object is considered “fully” initialized. Default False.

delete(): Delete this object.

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

get_assignment_mode()

Returns the assignment mode of this core prevention rule configuration.

Returns:: The assignment mode, either “REPORT” or “BLOCK”.
Return type:: str

get_parameter(name, default_value=None)

Returns a parameter value from the rule configuration.

Parameters:

name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.

Returns:

The parameter value, or None if there is no value.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

property parameter_names

Returns a list of parameter names in this rule configuration.

Returns:: A list of parameter names in this rule configuration.
Return type:: list[str]

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

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

set_assignment_mode(mode)

Sets the assignment mode of this core prevention rule configuration.

Parameters:: mode (str) – The new mode to set, either “REPORT” or “BLOCK”. The default is “BLOCK”.

set_parameter(name, value)

Sets a parameter value into the rule configuration.

Parameters:

name (str) – The parameter name.
value (Any) – The new value to be set.

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this rule configuration against its constraints.

Raises:: InvalidObjectError – If the rule object is not valid.

class DataCollectionRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: PolicyRuleConfig

Represents a data collection rule configuration in the policy.

Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule configuration to the policy. This requires the org.policies(UPDATE) permission.

To update a DataCollectionRuleConfig, change the values of its property fields, then call its save() method. This requires the org.policies(UPDATE) permission.

To delete an existing CorePreventionRuleConfig, call its delete() method. This requires the org.policies(DELETE) permission.

Parameters:

id – The ID of this rule config
name – The name of this rule config
description – The description of this rule config
inherited_from – Indicates where the rule config was inherited from
category – The category for this rule config
parameters – The parameters associated with this rule config

Initialize the CorePreventionRuleConfig object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
parent (Policy) – The “parent” policy of this rule configuration.
model_unique_id (str) – ID of the rule configuration.
initial_data (dict) – Initial data used to populate the rule configuration.
force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
full_doc (bool) – If True, object is considered “fully” initialized. Default False.

delete(): Delete this object.

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

get_parameter(name, default_value=None)

Returns a parameter value from the rule configuration.

Parameters:

name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.

Returns:

The parameter value, or None if there is no value.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

property parameter_names

Returns a list of parameter names in this rule configuration.

Returns:: A list of parameter names in this rule configuration.
Return type:: list[str]

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

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

set_parameter(name, value)

Sets a parameter value into the rule configuration.

Parameters:

name (str) – The parameter name.
value (Any) – The new value to be set.

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this rule configuration against its constraints.

Raises:: InvalidObjectError – If the rule object is not valid.

class HostBasedFirewallRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: PolicyRuleConfig

Represents a host-based firewall rule configuration in the policy.

Parameters:

id – The ID of this rule config
name – The name of this rule config
description – The description of this rule config
inherited_from – Indicates where the rule config was inherited from
category – The category for this rule config
parameters – The parameters associated with this rule config

Initialize the CorePreventionRuleConfig object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
parent (Policy) – The “parent” policy of this rule configuration.
model_unique_id (str) – ID of the rule configuration.
initial_data (dict) – Initial data used to populate the rule configuration.
force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
full_doc (bool) – If True, object is considered “fully” initialized. Default False.

class FirewallRule(cb, parent, initial_data)

Represents a single firewall rule.

Parameters:

action – The action to take when rule is hit
application_path – The application path to limit the rule
direction – The direction the network request is being made from
enabled – Whether the rule is enabled
protocol – The type of network request
local_ip_address – IPv4 address of the local side of the network connection (stored as dotted decimal)
local_port_ranges – TCP or UDP port used by the local side of the network connection
remote_ip_address – IPv4 address of the remote side of the network connection (stored as dotted decimal)
remote_port_ranges – TCP or UDP port used by the remote side of the network connection
test_mode – Enables host-based firewall hits without blocking network traffic or generating alerts

Initialize the FirewallRule object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the firewall rule.
parent (HostBasedFirewallRuleConfig) – The parent rule configuration.

delete(): Delete this object.

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

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:: True if any fields of this object have been changed, False if not.
Return type:: bool

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

remove(): Removes this rule from the rule group that contains it.

reset(): Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:: This object.
Return type:: MutableBaseModel

touch(fulltouch=False): Force this object to be considered as changed.

validate()

Validates this object.

Returns:: True if the object is validated.
Return type:: bool
Raises:: InvalidObjectError – If the object has missing fields.

class FirewallRuleGroup(cb, parent, initial_data)