Endpoint Standard

Submodules

cbc_sdk.endpoint_standard.base module

Model and Query Classes for Endpoint Standard

class Device(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.endpoint_standard.base.EndpointStandardMutableModel

Represents a Device object in the Carbon Black server.

Initialize a Device object with model_unique_id and initial_data.

activationCode = None

activationCodeExpiryTime = datetime.datetime(1970, 1, 1, 0, 0)

assignedToId = None

assignedToName = None

avEngine = None

avLastScanTime = datetime.datetime(1970, 1, 1, 0, 0)

avMaster = None

avStatus = []

avUpdateServers = []

createTime = datetime.datetime(1970, 1, 1, 0, 0)

deregisteredTime = datetime.datetime(1970, 1, 1, 0, 0)

deviceGuid = None

deviceId = None

deviceOwnerId = None

deviceSessionId = None

deviceType = None

email = None

firstName = None

firstVirusActivityTime = datetime.datetime(1970, 1, 1, 0, 0)

info_key = 'deviceInfo'

lastContact = datetime.datetime(1970, 1, 1, 0, 0)

lastExternalIpAddress = None

lastInternalIpAddress = None

lastLocation = None

lastName = None

lastReportedTime = datetime.datetime(1970, 1, 1, 0, 0)

lastResetTime = datetime.datetime(1970, 1, 1, 0, 0)

lastShutdownTime = datetime.datetime(1970, 1, 1, 0, 0)

lastVirusActivityTime = datetime.datetime(1970, 1, 1, 0, 0)

linuxKernelVersion = None

lr_session()

Retrieve a Live Response session object for this Device.

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

messages = []

middleName = None

name = None

organizationId = None

organizationName = None

osVersion = None

passiveMode = None

policyId = None

policyName = None

primary_key = 'deviceId'

quarantined = None

registeredTime = datetime.datetime(1970, 1, 1, 0, 0)

rootedByAnalytics = None

rootedByAnalyticsTime = datetime.datetime(1970, 1, 1, 0, 0)

rootedBySensor = None

rootedBySensorTime = datetime.datetime(1970, 1, 1, 0, 0)

scanLastActionTime = datetime.datetime(1970, 1, 1, 0, 0)

scanLastCompleteTime = datetime.datetime(1970, 1, 1, 0, 0)

scanStatus = None

sensorStates = []

sensorVersion = None

status = None

targetPriorityType = None

testId = None

uninstalledTime = datetime.datetime(1970, 1, 1, 0, 0)

urlobject = '/integrationServices/v3/device'

urlobject_single = '/integrationServices/v3/device/{}'

vdiBaseDevice = None

windowsPlatform = None

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

Module contents