Endpoint Standard Package

Base Module

Model and Query Classes for Endpoint Standard

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

Bases: UnrefreshableModel

Represents an enriched event retrieved by one of the Enterprise EDR endpoints.

Initialize the EnrichedEvent object.

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) – True to mark the object as fully initialized.

approve_process_sha256(description='')

Approves the application by adding the process_sha256 to the WHITE_LIST

Parameters:

description – The justification for why the application was added to the WHITE_LIST

Returns:

ReputationOverride object: created in the Carbon Black Cloud

Return type:

ReputationOverride (cbc_sdk.platform.ReputationOverride)

ban_process_sha256(description='')

Bans the application by adding the process_sha256 to the BLACK_LIST

Parameters:

description – The justification for why the application was added to the BLACK_LIST

Returns:

ReputationOverride object: created in the Carbon Black Cloud

Return type:

ReputationOverride (cbc_sdk.platform.ReputationOverride)

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) – Event details request timeout in milliseconds.
async_mode (bool) – True to request details in an asynchronous manner.

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.

property process_sha256

Returns a string representation of the SHA256 hash for this process.

Returns:: SHA256 hash of the process.
Return type:: hash (str)

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

class EnrichedEventFacet(cb, model_unique_id, initial_data)

Bases: UnrefreshableModel

Represents an enriched event retrieved by one of the Enterprise EDR endpoints.

Parameters:

job_id – The Job ID assigned to this query
terms – Contains the Enriched Event 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)

Bases: UnrefreshableModel

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

Initialize an EnrichedEventFacet Ranges object with initial_data.

property facets: Returns the reified EnrichedEventFacet.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)

Bases: UnrefreshableModel

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

Initialize an EnrichedEventFacet 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 EnrichedEventFacet.Ranges for this result.

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

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

class EnrichedEventQuery(doc_class, cb)

Bases: Query

Represents the query logic for an Enriched Event query.

This class specializes Query to handle the particulars of enriched events querying.

Initialize the EnrichedEventQuery 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")

aggregation(field)

Performs an aggregation search where results are grouped by an aggregation field

Parameters:: field (str) – The aggregation field, either ‘process_sha256’ or ‘device_id’

all()

Returns all the items of a query as a list.

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

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

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:

Query

one()

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

Returns:

Sole query return item

Return type:

obj

Raises:

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

or_(**kwargs)

or_() criteria are explicitly provided to EnrichedEvent 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.

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:

Query

Example

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

timeout(msecs)

Sets the timeout on a event query.

Parameters:

msecs (int) – Timeout duration, in milliseconds.

Returns:

The Query object with new milliseconds: parameter.

Return type:

Query (EnrichedEventQuery)

Example

>>> cb.select(EnrichedEvent).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:

Query

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

Bases: object

Represents an Endpoint Standard Event.

This functionality has been decommissioned. Please use EnrichedEvent instead. More information may be found here: https://community.carbonblack.com/t5/Developer-Relations/Migration-Guide-Carbon-Black-Cloud-Events-API/m-p/95915/thread-id/2519

This functionality has been decommissioned. Do not use.

Parameters:

cb (BaseAPI) – Unused.
model_unique_id (int) – Unused.
initial_data (dict) – Unused.

Raises:

FunctionalityDecommissioned – Always.

log = <Logger cbc_sdk.endpoint_standard.base (WARNING)>: Endpoint Standard Models

Standard Recommendation Module

Model and query APIs for Recommendations

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

Bases: NewBaseModel

Represents a recommended proposed policy change for the organization.

Parameters:

changed_by – Who made the last update to the workflow
create_time – The time the recommendation was created
ref_id – Reference id for an accepted Recommendation which is the id of the created Reputation Override
status – Status of the recommendation
update_time – The last time the recommendation was updated
comment – A comment added when the recommendation was updated

Initialize the Recommendation object.

Parameters:

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

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

Bases: UnrefreshableModel

Represents the rule application of a proposed change to an organization’s policies.

Parameters:

type – Application type
value – Application value

Initialize the RecommendationApplication object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – Should be None.
initial_data (dict) – Initial data used to populate the 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

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

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

Bases: UnrefreshableModel

Represents metadata about a recommendation to be used in the decision to accept or reject it.

Parameters:

event_count – Number of alerts encountered for recommendation
impact_score – Impact score
impacted_devices – Number of devices impacted by the recommendation
org_adoption – Priority for adoption of this recommendation
update_time – The last time this impact was updated

Initialize the RecommendationImpact object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – Should be None.
initial_data (dict) – Initial data used to populate the 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

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

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

Bases: UnrefreshableModel

Represents the proposed change to an organization’s policies from a recommendation.

Parameters:

action – Rule action
application – Rule application
certificate_authority – Certificate authority
filename – File name
include_child_processes – Include child processes
operation – Operation
override_list – Override list
override_type – Override type
path – File path
sha256_hash – SHA256 hash
signed_by – Signed by

Initialize the RecommendationNewRule object.

Parameters:

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

property application_

Return the object representing the rule application of a proposed change to an organization’s policies.

Returns:: The object representing the rule application of a proposed change.
Return type:: RecommendationApplication

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 RecommendationWorkflow(cb, model_unique_id, initial_data=None)

Bases: UnrefreshableModel

Represents the lifecycle state of a recommendation.

Parameters:

changed_by – Who made the last update to the workflow
create_time – The time the recommendation was created
ref_id – Reference id for an accepted Recommendation which is the id of the created Reputation Override
status – Status of the recommendation
update_time – The last time the recommendation was updated
comment – A comment added when the recommendation was updated

Initialize the RecommendationWorkflow object.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
model_unique_id (str) – Should be None.
initial_data (dict) – Initial data used to populate the 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

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

accept(comment=None)

Accept this recommendation, converting it into a reputation override.

Parameters:: comment (str) – Optional comment associated with the action.
Returns:: True if we successfully refreshed this Recommendation’s 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 impact_

Return the object representing metadata about the recommendation.

Returns:: The object representing metadata about the recommendation.
Return type:: RecommendationImpact

property new_rule_

Return the object representing the proposed change to an organization’s policies from the recommendation.

Returns:: The object representing the proposed change to an organization’s policies.
Return type:: RecommendationNewRule

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

reject(comment=None)

Reject this recommendation.

Parameters:: comment (str) – Optional comment associated with the action.
Returns:: True if we successfully refreshed this Recommendation’s state, False if not.
Return type:: bool

reputation_override()

Returns the reputation override associated with the recommendation (if the recommendation was accepted).

Returns:: The associated reputation override, or None if there is none.
Return type:: ReputationOverride

reset(comment=None)

Reset the recommendation, undoing any created reputation override and setting it back to NEW state.

Parameters:: comment (str) – Optional comment associated with the action.
Returns:: True if we successfully refreshed this Recommendation’s state, False if not.
Return type:: bool

property workflow_

Returns the object representing the lifecycle state of the recommendation.

Returns:: The object representing the lifecycle state of the recommendation.
Return type:: RecommendationWorkflow

class RecommendationQuery(doc_class, cb)

Bases: BaseQuery, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

Query used to locate Recommendation objects.

Initialize the RecommendationQuery.

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

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_hashes(hashes)

Restricts the recommendations that this query is performed on to the specified hashes.

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

set_policy_types(policy_types)

Restricts the recommendations that this query is performed on to the specified policy types.

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

set_statuses(statuses)

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

Parameters:: statuses (list) – List of status values to restrict the search to. If no statuses are specified, the search defaults to NEW only.
Returns:: This instance.
Return type:: RecommendationQuery
Raises:: ApiError – If invalid values are passed in the list.

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(USBDevice).sort_by("product_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:

USBDeviceQuery

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.

log = <Logger cbc_sdk.endpoint_standard.recommendation (WARNING)>: Recommendation models

USB Device Control Module

Model and Query Classes for USB Device Control

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

Bases: NewBaseModel

Represents a USB device.

Parameters:

created_at – the UTC date the external USB device configuration was created in ISO 8601 format
device_friendly_name – human readable name for the external USB device
device_name – name of the external USB device
device_type – type of external USB device
endpoint_count – number of endpoints that the external USB device has connected to
first_seen – first timestamp that the external USB device was seen
id – the id for this external USB device
interface_type – type of interface used by external USB device
last_endpoint_id – ID of the last endpoint the device accessed
last_endpoint_name – name of the last endpoint the device accessed
last_policy_id – ID of the last policy associated with the device
last_seen – last timestamp that the external USB device was seen
org_key – unique org key of the organization that the external USB device was connected to
product_id – product ID of the external USB device in decimal form
product_name – product name of the external USB device
serial_number – serial number of external device
status – Calculated status of device
updated_at – the UTC date the external USB device configuration was updated in ISO 8601 format
vendor_id – ID of the Vendor for the external USB device in decimal form
vendor_name – vendor name of the external USB device

Initialize the USBDevice 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.

approve(approval_name, notes)

Creates and saves an approval for this USB device, allowing it to be treated as approved from now on.

Required Permissions:: external-device.manage (CREATE)

Parameters:

approval_name (str) – The name for this new approval.
notes (str) – Notes to be added to this approval.

Returns:

The new approval.

Return type:

USBDeviceApproval

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

Returns the information about endpoints associated with this USB device.

Required Permissions:: external-device.manage (READ)

Returns:: List of information about USB endpoints, each item specified as a dict.
Return type:: list

classmethod get_vendors_and_products_seen(cb)

Returns all vendors and products that have been seen for the organization.

Required Permissions:: external-device.manage (READ)

Parameters:: cb (BaseAPI) – Reference to API object used to communicate with the server.
Returns:: A list of vendors and products seen for the organization, each vendor being represented by a dict.
Return type:: list

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

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

Bases: MutableBaseModel

Represents a USB device approval.

Parameters:

approval_name – the name of the approval
created_at – the UTC date the approval was created in ISO 8601 format
id – the id for this approval
notes – the notes for the approval
product_id – product ID of the approval’s external USB device in hex form
product_name – product name of the approval’s external USB device
serial_number – serial number of the approval’s external device
updated_at – the UTC date the approval was updated in ISO 8601 format
updated_by – the user who updated the record last
vendor_id – ID of the Vendor for the approval’s external USB device in hex form
vendor_name – vendor name of the approval’s external USB device

Initialize the USBDeviceApproval 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.

classmethod bulk_create(cb, approvals)

Creates multiple approvals and returns the USBDeviceApproval objects. Data is supplied as a list of dicts.

Required Permissions:: external-device.manage (CREATE)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
approvals (list) – List of dicts containing approval data to be created, formatted as shown below.

Example

>>> [
        {
            "approval_name": "string",
            "notes": "string",
            "product_id": "string",
            "serial_number": "string",
            "vendor_id": "string"
        }
    ]

Returns:: A list of USBDeviceApproval objects representing the approvals that were created.
Return type:: list

classmethod bulk_create_csv(cb, approval_data)

Creates multiple approvals and returns the USBDeviceApproval objects. Data is supplied as text in CSV format.

Required Permissions:: external-device.manage (CREATE)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
approval_data (str) – CSV data for the approvals to be created. Header line MUST be included as shown below.

Example

vendor_id,product_id,serial_number,approval_name,notes

string,string,string,string,string

Returns:: A list of USBDeviceApproval objects representing the approvals that were created.
Return type:: list

classmethod create_from_usb_device(usb_device)

Creates a new, unsaved approval object from a USBDeviceObject, filling in its basic fields.

Parameters:: usb_device (USBDevice) – The USB device to create the approval from.
Returns:: The new approval object.
Return type:: USBDeviceApproval

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.

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 USBDeviceApprovalQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

Represents a query that is used to locate USBDeviceApproval objects.

Initialize the USBDeviceApprovalQuery.

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:

Query

execute_async()

Executes the current query in an asynchronous fashion.

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

export(export_format)

Starts the process of exporting USB device approval data from the organization in a specified format.

Required Permissions:: external-device.manage (READ)

Parameters:: export_format (str) – The format to export USB device approval data in. Must be either “CSV” or “JSON”.
Returns:: The asynchronous job that will provide the export output when the server has prepared it.
Return type:: Job

first()

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

Returns:: First query item
Return type:: obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

one()

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

Returns:

Sole query return item

Return type:

obj

Raises:

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

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

set_device_ids(device_ids)

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

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

set_product_names(product_names)

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

Parameters:: product_names (list) – List of string product names.
Returns:: This instance.
Return type:: USBDeviceApprovalQuery

set_vendor_names(vendor_names)

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

Parameters:: vendor_names (list) – List of string vendor names.
Returns:: This instance.
Return type:: USBDeviceApprovalQuery

update_criteria(key, newlist)

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

Parameters:

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

Returns:

The query object with specified custom criteria.

Example

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

Note

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

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

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

Bases: NewBaseModel

Represents a USB device block.

Parameters:

created_at – the UTC date the block was created in ISO 8601 format
id – the id for this block
policy_id – policy id which is blocked
updated_at – the UTC date the block was updated in ISO 8601 format

Initialize the USBDeviceBlock 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.

classmethod bulk_create(cb, policy_ids)

Creates multiple blocks and returns the USBDeviceBlocks that were created.

Required Permissions:: org.policies (UPDATE), external-device.enforce (UPDATE)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
policy_ids (list) – List of policy IDs to have blocks created for.

Returns:

A list of USBDeviceBlock objects representing the approvals that were created.

Return type:

list

classmethod create(cb, policy_id)

Creates a USBDeviceBlock for a given policy ID.

Required Permissions:: org.policies (UPDATE), external-device.enforce (UPDATE)

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
policy_id (str/int) – Policy ID to create a USBDeviceBlock for.

Returns:

New USBDeviceBlock object representing the block.

Return type:

USBDeviceBlock

delete()

Delete this object.

Required Permissions:: org.policies (DELETE), external-device.enforce (UPDATE)

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 USBDeviceBlockQuery(doc_class, cb)

Bases: BaseQuery, IterableQueryMixin, AsyncQueryMixin

Represents a query that is used to locate USBDeviceBlock objects.

Initialize the USBDeviceBlockQuery.

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.

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

class USBDeviceQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

Represents a query that is used to locate USBDevice objects.

Initialize the USBDeviceQuery.

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:

Query

execute_async()

Executes the current query in an asynchronous fashion.

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

export(export_format)

Starts the process of exporting USB device data from the organization in a specified format.

Required Permissions:: external-device.manage (READ)

Parameters:: export_format (str) – The format to export USB device data in. Must be either “CSV” or “JSON”.
Returns:: The asynchronous job that will provide the export output when the server has prepared it.
Return type:: Job

facets(fieldlist, max_rows=0)

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

Required Permissions:: external-device.manage (READ)

Parameters:

fieldlist (list) – List of facet field names. Valid names are “vendor_name”, “product_name”, “endpoint.endpoint_name”, and “status”.
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:

Query

one()

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

Returns:

Sole query return item

Return type:

obj

Raises:

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

or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

set_endpoint_names(endpoint_names)

Restricts the devices that this query is performed on to the specified endpoint names.

Parameters:: endpoint_names (list) – List of string endpoint names.
Returns:: This instance.
Return type:: USBDeviceQuery

set_max_rows(max_rows)

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

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

set_product_names(product_names)

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

Parameters:: product_names (list) – List of string product names.
Returns:: This instance.
Return type:: USBDeviceQuery

set_serial_numbers(serial_numbers)

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

Parameters:: serial_numbers (list) – List of string serial numbers.
Returns:: This instance.
Return type:: USBDeviceQuery

set_statuses(statuses)

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

Parameters:: statuses (list) – List of string status values. Valid values are APPROVED and UNAPPROVED.
Returns:: This instance.
Return type:: USBDeviceQuery

set_vendor_names(vendor_names)

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

Parameters:: vendor_names (list) – List of string vendor names.
Returns:: This instance.
Return type:: USBDeviceQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(USBDevice).sort_by("product_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:

USBDeviceQuery

update_criteria(key, newlist)

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

Parameters:

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

Returns:

The query object with specified custom criteria.

Example

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

Note

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

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

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

Returns:

This Query object.

Return type:

Query

log = <Logger cbc_sdk.endpoint_standard.usb_device_control (WARNING)>: USB Device Control models