Endpoint Standard

Decommissioned Functionality

The Endpoint Standard events (cbc_sdk.endpoint_standard.Event) have been decommissioned and should no longer be used. Any attempt to use them will raise a FunctionalityDecommissioned exception. Please use cbc_sdk.endpoint_standard.EnrichedEvent instead. Refer to this migration guide on the Carbon Black Developer Network Community for more information.

Submodules

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

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

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 the facet fields and values associated with an Enriched Event Facet query.

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.

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: 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.
info_key = 'eventInfo'
primary_key = 'eventId'
urlobject = '/integrationServices/v3/event'
log = <Logger cbc_sdk.endpoint_standard.base (WARNING)>

Endpoint Standard Models

cbc_sdk.endpoint_standard.recommendation module

Model and query APIs for Recommendations

class Recommendation(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.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: cbc_sdk.base.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.
type = None
value = None
class RecommendationImpact(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.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.
event_count = None
impact_score = None
impacted_devices = None
org_adoption = None
update_time = None
class RecommendationNewRule(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.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.
action = None
application = {}
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
certificate_authority = None
filename = None
include_child_processes = None
operation = None
override_list = None
override_type = None
path = None
sha256_hash = None
signed_by = None
class RecommendationWorkflow(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.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.
changed_by = None
comment = None
create_time = None
ref_id = None
status = None
update_time = None
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
changed_by = None
comment = None
create_time = None
impact_

Return the object representing metadata about the recommendation.

Returns:The object representing metadata about the recommendation.
Return type:RecommendationImpact
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
primary_key = 'recommendation_id'
ref_id = None
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
status = None
update_time = None
urlobject = '/recommendation-service/v1/orgs/{0}/recommendation'
urlobject_single = '/recommendation-service/v1/orgs/{0}/recommendation/{1}'
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: cbc_sdk.base.BaseQuery, cbc_sdk.base.CriteriaBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.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.
VALID_POLICY_TYPES = ['reputation_override', 'sensor_policy']
VALID_STATUSES = ['NEW', 'REJECTED', 'ACCEPTED']
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
log = <Logger cbc_sdk.endpoint_standard.recommendation (WARNING)>

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

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

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_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
log = <Logger cbc_sdk.endpoint_standard.usb_device_control (WARNING)>

USB Device Control models

Module contents