Endpoint Standard¶

Submodules¶

cbc_sdk.endpoint_standard.base module¶

Model and Query Classes for Endpoint Standard

class EndpointStandardMutableModel(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶

Bases: cbc_sdk.base.MutableBaseModel

Represents a EndpointStandardMutableModel object in the Carbon Black server.

Initialize an EndpointStandardMutableModel with model_unique_id and initial_data.

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

Bases: cbc_sdk.base.UnrefreshableModel

Represents a EnrichedEvent object in the Carbon Black server.

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)

default_sort = 'device_timestamp'¶

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.

primary_key = 'event_id'¶

process_sha256¶

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

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

class EnrichedEventFacet(cb, model_unique_id, initial_data)¶

Bases: cbc_sdk.base.UnrefreshableModel

Represents a EnrichedEventFacet object in the Carbon Black server.

Variables:	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: cbc_sdk.base.UnrefreshableModel

Represents a Ranges object in the Carbon Black server.

Initialize an EnrichedEventFacet Ranges object with initial_data.

facets¶: Returns the reified EnrichedEventFacet.Terms._facets for this result.

fields¶: Returns the ranges fields for this result.

class Terms(cb, initial_data)¶

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Terms object in the Carbon Black server.

Initialize an EnrichedEventFacet Terms object with initial_data.

facets¶: Returns the terms’ facets for this result.

fields¶: Returns the terms facets’ fields for this result.

completed = None¶

contacted = None¶

job_id = None¶

num_found = None¶

primary_key = 'job_id'¶

ranges = []¶

ranges_¶: Returns the reified EnrichedEventFacet.Ranges for this result.

result_url = '/api/investigate/v2/orgs/{}/enriched_events/facet_jobs/{}/results'¶

submit_url = '/api/investigate/v2/orgs/{}/enriched_events/facet_jobs'¶

terms = {}¶

terms_¶: Returns the reified EnrichedEventFacet.Terms for this result.

class EnrichedEventQuery(doc_class, cb)¶

Bases: cbc_sdk.base.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.

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’

or_(**kwargs)¶

or_ criteria are explicitly provided to EnrichedEvent queries although they are endpoint_standard.

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

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.

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)

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

Bases: cbc_sdk.base.NewBaseModel

Represents a Event object in the Carbon Black server.

Initialize an Event with model_unique_id and initial_data.

info_key = 'eventInfo'¶

primary_key = 'eventId'¶

urlobject = '/integrationServices/v3/event'¶

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

Bases: cbc_sdk.endpoint_standard.base.EndpointStandardMutableModel, cbc_sdk.base.CreatableModelMixin

Represents a Policy object in the Carbon Black server.

Initialize an EndpointStandardMutableModel with model_unique_id and initial_data.

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]

delete_rule(rule_id)¶: Deletes a rule from this Policy.

description = None¶

id = None¶

info_key = 'policyInfo'¶

latestRevision = None¶

name = None¶

policy = {}¶

priorityLevel = None¶

replace_rule(rule_id, new_rule)¶: Replaces a rule in this policy.

rules¶: Returns a dictionary of rules and rule IDs for this Policy.

systemPolicy = None¶

urlobject = '/integrationServices/v3/policy'¶

version = None¶

class Query(doc_class, cb, query=None)¶

Bases: cbc_sdk.base.PaginatedQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin

Represents a prepared query to the Cb Endpoint Standard server.

This object is returned as part of a CBCloudAPI.select operation on models requested from the Cb Endpoint Standard server. You should not have to create this class yourself.

The query is not executed on the server until it’s accessed, either as an iterator (where it will generate values on demand as they’re requested) or as a list (where it will retrieve the entire result set and save to a list). You can also call the Python built-in `len() on this object to retrieve the total number of items matching the query.

Example: >>> from cbc_sdk import CBCloudAPI >>> cb = CBCloudAPI()

Notes

The slicing operator only supports start and end parameters, but not step. [1:-1] is legal, but [1:2:-1] is not.
You can chain where clauses together to create AND queries; only objects that match all where clauses will be returned. - Device Queries with multiple search parameters only support AND operations, not OR. Use of Query.or_(myParameter=’myValue’) will add ‘AND myParameter:myValue’ to the search query.

Initialize a Query object.

or_(**kwargs)¶

Unsupported. Will raise if called.

Raises:	`ApiError` – .or_() cannot be called on Endpoint Standard queries.

prepare_query(args)¶: Adds query parameters that are part of a select().where() clause to the request.

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

cbc_sdk.endpoint_standard.usb_device_control module¶

Model and Query Classes for USB Device Control

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

Bases: cbc_sdk.base.NewBaseModel

Represents a USBDevice object in the Carbon Black server.

Variables:

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.

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

created_at = None¶

device_friendly_name = None¶

device_name = None¶

device_type = None¶

endpoint_count = None¶

first_seen = None¶

get_endpoints()¶

Returns the information about endpoints associated with this USB device.

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.

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

id = None¶

interface_type = None¶

last_endpoint_id = None¶

last_endpoint_name = None¶

last_policy_id = None¶

last_seen = None¶

org_key = None¶

primary_key = 'id'¶

product_id = None¶

product_name = None¶

serial_number = None¶

status = None¶

updated_at = None¶

urlobject = '/device_control/v3/orgs/{0}/devices'¶

urlobject_single = '/device_control/v3/orgs/{0}/devices/{1}'¶

vendor_id = None¶

vendor_name = None¶

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

Bases: cbc_sdk.base.MutableBaseModel

Represents a USBDeviceApproval object in the Carbon Black server.

Variables:

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.

approval_name = None¶

classmethod bulk_create(cb, approvals)¶

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

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.

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

created_at = None¶

id = None¶

notes = None¶

primary_key = 'id'¶

product_id = None¶

product_name = None¶

serial_number = None¶

updated_at = None¶

updated_by = None¶

urlobject = '/device_control/v3/orgs/{0}/approvals'¶

urlobject_single = '/device_control/v3/orgs/{0}/approvals/{1}'¶

vendor_id = None¶

vendor_name = None¶

class USBDeviceApprovalQuery(doc_class, cb)¶

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

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

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

Bases: cbc_sdk.base.NewBaseModel

Represents a USBDeviceBlock object in the Carbon Black server.

Variables:	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.

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.

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

created_at = None¶

delete()¶: Delete this object.

id = None¶

policy_id = None¶

primary_key = 'id'¶

updated_at = None¶

urlobject = '/device_control/v3/orgs/{0}/blocks'¶

urlobject_single = '/device_control/v3/orgs/{0}/blocks/{1}'¶

class USBDeviceBlockQuery(doc_class, cb)¶

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.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.

class USBDeviceQuery(doc_class, cb)¶

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

VALID_FACET_FIELDS = ['vendor_name', 'product_name', 'endpoint.endpoint_name', 'status']¶

VALID_STATUSES = ['APPROVED', 'UNAPPROVED']¶

facets(fieldlist, max_rows=0)¶

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

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

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_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

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

Endpoint Standard¶

Submodules¶

cbc_sdk.endpoint_standard.base module¶

cbc_sdk.endpoint_standard.usb_device_control module¶

Module contents¶