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. This value can never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.

  • 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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
add_exclusions(key, newlist)

Add to the exclusions on this query with a custom exclusions key.

Will overwrite any existing exclusion for the specified 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 query object with specified custom exclusion.

Example

>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"])
>>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
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:
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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required")
>>> second_query = api.select(Process).
...     set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required")
>>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
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. This value can cever be greater than the configured default timeout. If this value is 0, the configured default timeout is used.

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.

update_exclusions(key, newlist)

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

Parameters:

  • key (str) – The key for the exclusion item to be set.

  • newlist (list) – List of values to be set for the exclusion item.

Returns:

The query object with specified custom exclusion.

Example

>>> query = api.select(Alert).update_exclusions("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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
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:
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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
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:
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.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

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:
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(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
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:
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