Platform

Submodules

cbc_sdk.platform.alerts module

Model and Query Classes for Platform Alerts and Workflows

class BaseAlert(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.base.PlatformModel

Represents a BaseAlert object in the Carbon Black server.

Variables:
  • category – Alert category - Monitored vs Threat
  • create_time – Time the alert was created
  • device_id – ID of the device
  • device_name – Device name
  • device_os – Device OS
  • device_os_version – Device OS Version
  • device_username – Logged on user during the alert. This is filled on a best-effort approach. If the user is not available it may be populated with the device owner
  • first_event_time – Time of the first event in an alert
  • group_details – Group details for when alert grouping is on
  • id – Unique ID for this alert
  • last_event_time – Time of the last event in an alert
  • last_update_time – Time the alert was last updated
  • legacy_alert_id – Unique short ID for this alert. This is deprecated and only available on alerts stored in the old schema.
  • notes_present – Are notes present for this threatId
  • org_key – Unique identifier for the organization to which the alert belongs
  • policy_id – ID of the policy the device was in at the time of the alert
  • policy_name – Name of the policy the device was in at the time of the alert
  • severity – Threat ranking
  • tags – Tags for the alert
  • target_value – Device priority as assigned via the policy
  • threat_id – ID of the threat to which this alert belongs. Threats are comprised of a combination of factors that can be repeated across devices.
  • type – Type of the alert
  • workflow – User-updatable status of the alert

Initialize the BaseAlert 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.
category = None
create_time = None
device_id = None
device_name = None
device_os = None
device_os_version = None
device_username = None
dismiss(remediation=None, comment=None)

Dismisses this alert.

Parameters:
  • remediation (str) – The remediation status to set for the alert.
  • comment (str) – The comment to set for the alert.
dismiss_threat(remediation=None, comment=None)

Dismisses all alerts with the same threat ID, past or future.

Parameters:
  • remediation (str) – The remediation status to set for the alert.
  • comment (str) – The comment to set for the alert.
first_event_time = None
group_details = {}
id = None
last_event_time = None
last_update_time = None
legacy_alert_id = None
notes_present = None
org_key = None
policy_id = None
policy_name = None
primary_key = 'id'
severity = None
tags = []
target_value = None
threat_id = None
type = None
update(remediation=None, comment=None)

Updates this alert while leaving it open.

Parameters:
  • remediation (str) – The remediation status to set for the alert.
  • comment (str) – The comment to set for the alert.
update_threat(remediation=None, comment=None)

Updates the status of all alerts with the same threat ID, past or future, while leaving them in OPEN state.

Parameters:
  • remediation (str) – The remediation status to set for the alert.
  • comment (str) – The comment to set for the alert.
urlobject = '/appservices/v6/orgs/{0}/alerts'
urlobject_single = '/appservices/v6/orgs/{0}/alerts/{1}'
workflow = {}
workflow_

Returns the workflow associated with this alert.

Returns:The workflow associated with this alert.
Return type:Workflow
class BaseAlertSearchQuery(doc_class, cb)

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.CriteriaBuilderSupportMixin

Represents a query that is used to locate BaseAlert objects.

Initialize the BaseAlertSearchQuery.

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_ALERT_TYPES = ['CB_ANALYTICS', 'DEVICE_CONTROL', 'WATCHLIST']
VALID_CATEGORIES = ['THREAT', 'MONITORED', 'INFO', 'MINOR', 'SERIOUS', 'CRITICAL']
VALID_FACET_FIELDS = ['ALERT_TYPE', 'CATEGORY', 'REPUTATION', 'WORKFLOW', 'TAG', 'POLICY_ID', 'POLICY_NAME', 'DEVICE_ID', 'DEVICE_NAME', 'APPLICATION_HASH', 'APPLICATION_NAME', 'STATUS', 'RUN_STATE', 'POLICY_APPLIED_STATE', 'POLICY_APPLIED', 'SENSOR_ACTION']
VALID_REPUTATIONS = ['KNOWN_MALWARE', 'SUSPECT_MALWARE', 'PUP', 'NOT_LISTED', 'ADAPTIVE_WHITE_LIST', 'COMMON_WHITE_LIST', 'TRUSTED_WHITE_LIST', 'COMPANY_BLACK_LIST']
VALID_WORKFLOW_VALS = ['OPEN', 'DISMISSED']
dismiss(remediation=None, comment=None)

Dismiss all alerts matching the given query. The alerts will be left in a DISMISSED state after this request.

Parameters:
  • remediation (str) – The remediation state to set for all alerts.
  • comment (str) – The comment to set for all alerts.
Returns:

The request ID, which may be used to select a WorkflowStatus object.
Return type:

str
facets(fieldlist, max_rows=0)

Return information about the facets for this alert by search, using the defined criteria.

Parameters:
  • fieldlist (list) – List of facet field names. Valid names are “ALERT_TYPE”, “CATEGORY”, “REPUTATION”, “WORKFLOW”, “TAG”, “POLICY_ID”, “POLICY_NAME”, “DEVICE_ID”, “DEVICE_NAME”, “APPLICATION_HASH”, “APPLICATION_NAME”, “STATUS”, “RUN_STATE”, “POLICY_APPLIED_STATE”, “POLICY_APPLIED”, and “SENSOR_ACTION”.
  • 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_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified alert IDs.

Parameters:alert_ids (list) – List of string alert IDs.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_categories(categories)

Restricts the alerts that this query is performed on to the specified categories.

Parameters:categories (list) – List of categories to be restricted to. Valid categories are “THREAT”, “MONITORED”, “INFO”, “MINOR”, “SERIOUS”, and “CRITICAL.”
Returns:This instance.
Return type:BaseAlertSearchQuery
set_create_time(*args, **kwargs)

Restricts the alerts that this query is performed on to the specified creation time.

The time may either be specified as a start and end point or as a range.

Parameters:
  • *args (list) – Not used.
  • **kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.
Returns:

This instance.
Return type:

BaseAlertSearchQuery
set_device_ids(device_ids)

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

Parameters:device_ids (list) – List of integer device IDs.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_device_names(device_names)

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

Parameters:device_names (list) – List of string device names.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_device_os(device_os)

Restricts the alerts that this query is performed on to the specified device operating systems.

Parameters:device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
Returns:This instance.
Return type:BaseAlertSearchQuery
set_device_os_versions(device_os_versions)

Restricts the alerts that this query is performed on to the specified device operating system versions.

Parameters:device_os_versions (list) – List of string operating system versions.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_device_username(users)

Restricts the alerts that this query is performed on to the specified user names.

Parameters:users (list) – List of string user names.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_group_results(do_group)

Specifies whether or not to group the results of the query.

Parameters:do_group (bool) – True to group the results, False to not do so.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_legacy_alert_ids(alert_ids)

Restricts the alerts that this query is performed on to the specified legacy alert IDs.

Parameters:alert_ids (list) – List of string legacy alert IDs.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_minimum_severity(severity)

Restricts the alerts that this query is performed on to the specified minimum severity level.

Parameters:severity (int) – The minimum severity level for alerts.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_policy_ids(policy_ids)

Restricts the alerts that this query is performed on to the specified policy IDs.

Parameters:policy_ids (list) – List of integer policy IDs.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_policy_names(policy_names)

Restricts the alerts that this query is performed on to the specified policy names.

Parameters:policy_names (list) – List of string policy names.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_process_names(process_names)

Restricts the alerts that this query is performed on to the specified process names.

Parameters:process_names (list) – List of string process names.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_process_sha256(shas)

Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.

Parameters:shas (list) – List of string process SHA-256 hash values.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_reputations(reps)

Restricts the alerts that this query is performed on to the specified reputation values.

Parameters:reps (list) –

List of string reputation values. Valid values are “KNOWN_MALWARE”, “SUSPECT_MALWARE”, “PUP”, “NOT_LISTED”, “ADAPTIVE_WHITE_LIST”, “COMMON_WHITE_LIST”, “TRUSTED_WHITE_LIST”,

and “COMPANY_BLACK_LIST”.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_tags(tags)

Restricts the alerts that this query is performed on to the specified tag values.

Parameters:tags (list) – List of string tag values.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_target_priorities(priorities)

Restricts the alerts that this query is performed on to the specified target priority values.

Parameters:priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_threat_ids(threats)

Restricts the alerts that this query is performed on to the specified threat ID values.

Parameters:threats (list) – List of string threat ID values.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_time_range(key, **kwargs)

Restricts the alerts that this query is performed on to the specified time range.

The time may either be specified as a start and end point or as a range.

Parameters:
  • key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time, or last_update_time
  • **kwargs (dict) – Used to specify start= for start time, end= for end time, and range= for range.
Returns:

This instance.
Return type:

BaseAlertSearchQuery
set_types(alerttypes)

Restricts the alerts that this query is performed on to the specified alert type values.

Parameters:alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, and “WATCHLIST”.
Returns:This instance.
Return type:BaseAlertSearchQuery
set_workflows(workflow_vals)

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

Parameters:workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
Returns:This instance.
Return type:BaseAlertSearchQuery
sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

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

BaseAlertSearchQuery
update(remediation=None, comment=None)

Update all alerts matching the given query. The alerts will be left in an OPEN state after this request.

Parameters:
  • remediation (str) – The remediation state to set for all alerts.
  • comment (str) – The comment to set for all alerts.
Returns:

The request ID, which may be used to select a WorkflowStatus object.
Return type:

str
class CBAnalyticsAlert(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.alerts.BaseAlert

Represents a CBAnalyticsAlert object in the Carbon Black server.

Initialize the BaseAlert 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.
get_events(timeout=0, async_mode=False)

Requests enriched events detailed results.

Parameters:
  • timeout (int) – Event details request timeout in milliseconds.
  • async_mode (bool) – True to request details in an asynchronous manner.
Returns:

EnrichedEvents matching the legacy_alert_id
Return type:

list

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.
urlobject = '/appservices/v6/orgs/{0}/alerts/cbanalytics'
class CBAnalyticsAlertSearchQuery(doc_class, cb)

Bases: cbc_sdk.platform.alerts.BaseAlertSearchQuery

Represents a query that is used to locate CBAnalyticsAlert objects.

Initialize the CBAnalyticsAlertSearchQuery.

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_KILL_CHAIN_STATUSES = ['RECONNAISSANCE', 'WEAPONIZE', 'DELIVER_EXPLOIT', 'INSTALL_RUN', 'COMMAND_AND_CONTROL', 'EXECUTE_GOAL', 'BREACH']
VALID_LOCATIONS = ['ONSITE', 'OFFSITE', 'UNKNOWN']
VALID_POLICY_APPLIED = ['APPLIED', 'NOT_APPLIED']
VALID_RUN_STATES = ['DID_NOT_RUN', 'RAN', 'UNKNOWN']
VALID_SENSOR_ACTIONS = ['POLICY_NOT_APPLIED', 'ALLOW', 'ALLOW_AND_LOG', 'TERMINATE', 'DENY']
VALID_THREAT_CATEGORIES = ['UNKNOWN', 'NON_MALWARE', 'NEW_MALWARE', 'KNOWN_MALWARE', 'RISKY_PROGRAM']
VALID_THREAT_CAUSE_VECTORS = ['EMAIL', 'WEB', 'GENERIC_SERVER', 'GENERIC_CLIENT', 'REMOTE_DRIVE', 'REMOVABLE_MEDIA', 'UNKNOWN', 'APP_STORE', 'THIRD_PARTY']
set_blocked_threat_categories(categories)

Restricts the alerts that this query is performed on to the specified threat categories that were blocked.

Parameters:categories (list) – List of threat categories to look for. Valid values are “UNKNOWN”, “NON_MALWARE”, “NEW_MALWARE”, “KNOWN_MALWARE”, and “RISKY_PROGRAM”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_device_locations(locations)

Restricts the alerts that this query is performed on to the specified device locations.

Parameters:locations (list) – List of device locations to look for. Valid values are “ONSITE”, “OFFSITE”, and “UNKNOWN”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_kill_chain_statuses(statuses)

Restricts the alerts that this query is performed on to the specified kill chain statuses.

Parameters:statuses (list) – List of kill chain statuses to look for. Valid values are “RECONNAISSANCE”, “WEAPONIZE”, “DELIVER_EXPLOIT”, “INSTALL_RUN”,”COMMAND_AND_CONTROL”, “EXECUTE_GOAL”, and “BREACH”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_not_blocked_threat_categories(categories)

Restricts the alerts that this query is performed on to the specified threat categories that were NOT blocked.

Parameters:categories (list) – List of threat categories to look for. Valid values are “UNKNOWN”, “NON_MALWARE”, “NEW_MALWARE”, “KNOWN_MALWARE”, and “RISKY_PROGRAM”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_policy_applied(applied_statuses)

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

Parameters:applied_statuses (list) – List of status values to look for. Valid values are “APPLIED” and “NOT_APPLIED”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_reason_code(reason)

Restricts the alerts that this query is performed on to the specified reason codes (enum values).

Parameters:reason (list) – List of string reason codes to look for.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_run_states(states)

Restricts the alerts that this query is performed on to the specified run states.

Parameters:states (list) – List of run states to look for. Valid values are “DID_NOT_RUN”, “RAN”, and “UNKNOWN”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_sensor_actions(actions)

Restricts the alerts that this query is performed on to the specified sensor actions.

Parameters:actions (list) – List of sensor actions to look for. Valid values are “POLICY_NOT_APPLIED”, “ALLOW”, “ALLOW_AND_LOG”, “TERMINATE”, and “DENY”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
set_threat_cause_vectors(vectors)

Restricts the alerts that this query is performed on to the specified threat cause vectors.

Parameters:vectors (list) – List of threat cause vectors to look for. Valid values are “EMAIL”, “WEB”, “GENERIC_SERVER”, “GENERIC_CLIENT”, “REMOTE_DRIVE”, “REMOVABLE_MEDIA”, “UNKNOWN”, “APP_STORE”, and “THIRD_PARTY”.
Returns:This instance.
Return type:CBAnalyticsAlertSearchQuery
class DeviceControlAlert(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.alerts.BaseAlert

Represents a DeviceControlAlert object in the Carbon Black server.

Initialize the BaseAlert 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.
urlobject = '/appservices/v6/orgs/{0}/alerts/devicecontrol'
class DeviceControlAlertSearchQuery(doc_class, cb)

Bases: cbc_sdk.platform.alerts.BaseAlertSearchQuery

Represents a query that is used to locate DeviceControlAlert objects.

Initialize the CBAnalyticsAlertSearchQuery.

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_external_device_friendly_names(names)

Restricts the alerts that this query is performed on to the specified external device friendly names.

Parameters:names (list) – List of external device friendly names to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_external_device_ids(ids)

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

Parameters:ids (list) – List of external device IDs to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_product_ids(ids)

Restricts the alerts that this query is performed on to the specified product IDs.

Parameters:ids (list) – List of product IDs to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_product_names(names)

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

Parameters:names (list) – List of product names to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_serial_numbers(serial_numbers)

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

Parameters:serial_numbers (list) – List of serial numbers to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_vendor_ids(ids)

Restricts the alerts that this query is performed on to the specified vendor IDs.

Parameters:ids (list) – List of vendor IDs to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
set_vendor_names(names)

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

Parameters:names (list) – List of vendor names to look for.
Returns:This instance.
Return type:DeviceControlAlertSearchQuery
class WatchlistAlert(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.alerts.BaseAlert

Represents a WatchlistAlert object in the Carbon Black server.

Initialize the BaseAlert 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.
urlobject = '/appservices/v6/orgs/{0}/alerts/watchlist'
class WatchlistAlertSearchQuery(doc_class, cb)

Bases: cbc_sdk.platform.alerts.BaseAlertSearchQuery

Represents a query that is used to locate WatchlistAlert objects.

Initialize the WatchlistAlertSearchQuery.

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_watchlist_ids(ids)

Restricts the alerts that this query is performed on to the specified watchlist ID values.

Parameters:ids (list) – List of string watchlist ID values.
Returns:This instance.
Return type:WatchlistAlertSearchQuery
set_watchlist_names(names)

Restricts the alerts that this query is performed on to the specified watchlist name values.

Parameters:names (list) – List of string watchlist name values.
Returns:This instance.
Return type:WatchlistAlertSearchQuery
class Workflow(cb, initial_data=None)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Workflow object in the Carbon Black server.

Variables:
  • changed_by – Username of the user who changed the workflow
  • comment – Comment when updating the workflow
  • last_update_time – When the workflow was last updated
  • remediation – Alert remediation code. Indicates the result of the investigation into the alert
  • state – State of the workflow

Initialize the Workflow object.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • initial_data (dict) – Initial data used to populate the workflow.
changed_by = None
comment = None
last_update_time = None
remediation = None
state = None
class WorkflowStatus(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.base.PlatformModel

Represents a WorkflowStatus object in the Carbon Black server.

Variables:
  • errors – Errors for dismiss alerts or threats, if no errors it won’t be included in response
  • failed_ids – Failed ids
  • id – Time based id for async job, it’s not unique across the orgs
  • num_hits – Total number of alerts to be operated on
  • num_success – Successfully operated number of alerts
  • status – Status for the async progress
  • workflow – Requested workflow change

Initialize the BaseAlert object.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • model_unique_id (str) – ID of the request being processed.
  • initial_data (dict) – Initial data used to populate the status.
errors = []
failed_ids = []
finished

Returns whether this request has been completed.

Returns:True if the request is in “finished” state, False if not.
Return type:bool
id = None
id_

Returns the request ID of the associated request.

Returns:The request ID of the associated request.
Return type:str
in_progress

Returns whether this request is currently in progress.

Returns:True if the request is in “in progress” state, False if not.
Return type:bool
num_hits = None
num_success = None
primary_key = 'id'
queued

Returns whether this request has been queued.

Returns:True if the request is in “queued” state, False if not.
Return type:bool
status = None
urlobject_single = '/appservices/v6/orgs/{0}/workflow/status/{1}'
workflow = {}
workflow_

Returns the current workflow associated with this request.

Returns:The current workflow associated with this request.
Return type:Workflow

cbc_sdk.platform.base module

Model and Query Classes for Platform

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

Bases: cbc_sdk.base.NewBaseModel

Represents a PlatformModel object in the Carbon Black server.

Initialize the PlatformModel 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.
log = <Logger cbc_sdk.platform.base (WARNING)>

Platform Models

cbc_sdk.platform.devices module

Model and Query Classes for Platform Devices

class Device(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.base.PlatformModel

Represents a Device object in the Carbon Black server.

Variables:

Initialize the Device 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.
activation_code = None
activation_code_expiry_time = None
ad_group_id = None
av_ave_version = None
av_engine = None
av_last_scan_time = None
av_master = None
av_pack_version = None
av_product_version = None
av_status = []
av_update_servers = []
av_vdf_version = None
background_scan(flag)

Set the background scan option for this device.

Parameters:flag (bool) – True to turn background scan on, False to turn it off.
Returns:The JSON output from the request.
Return type:str
bypass(flag)

Set the bypass option for this device.

Parameters:flag (bool) – True to enable bypass, False to disable it.
Returns:The JSON output from the request.
Return type:str
current_sensor_policy_name = None
delete_sensor()

Delete this sensor device.

Returns:The JSON output from the request.
Return type:str
deployment_type = None
deregistered_time = None
deviceId

Warn user that Platform Devices use ‘id’, not ‘device_id’.

Platform Device API’s return ‘id’ in API responses, where Endpoint Standard API’s return ‘deviceId’.

device_id = None
device_meta_data_item_list = []
device_owner_id = None
email = None
encoded_activation_code = None
first_name = None
get_vulnerability_summary(category=None)

Get the vulnerabilities associated with this device

Parameters:category (string) – (optional) vulnerabilty category (OS, APP)
Returns:summary for the vulnerabilities for this device
Return type:dict
get_vulnerabilties()

Get an Operating System or Application Vulnerability List for a specific device.

Returns:vulnerabilities for this device
Return type:dict
id = None
last_contact_time = None
last_device_policy_changed_time = None
last_device_policy_requested_time = None
last_external_ip_address = None
last_internal_ip_address = None
last_location = None
last_name = None
last_policy_updated_time = None
last_reported_time = None
last_reset_time = None
last_shutdown_time = None
linux_kernel_version = None
login_user_name = None
lr_session()

Retrieve a Live Response session object for this Device.

Returns:Live Response session for the Device.
Return type:LiveResponseSession
Raises:ApiError – If there is an error establishing a Live Response session for this Device.
mac_address = None
middle_name = None
name = None
organization_id = None
organization_name = None
os = None
os_version = None
passive_mode = None
policy_id = None
policy_name = None
policy_override = None
primary_key = 'id'
quarantine(flag)

Set the quarantine option for this device.

Parameters:flag (bool) – True to enable quarantine, False to disable it.
Returns:The JSON output from the request.
Return type:str
quarantined = None
registered_time = None
scan_last_action_time = None
scan_last_complete_time = None
scan_status = None
sensor_out_of_date = None
sensor_states = []
sensor_version = None
status = None
target_priority_type = None
uninstall_code = None
uninstall_sensor()

Uninstall this sensor device.

Returns:The JSON output from the request.
Return type:str
update_policy(policy_id)

Set the current policy for this device.

Parameters:policy_id (int) – ID of the policy to set for the devices.
Returns:The JSON output from the request.
Return type:str
update_sensor_version(sensor_version)

Update the sensor version for this device.

Parameters:sensor_version (dict) – New version properties for the sensor.
Returns:The JSON output from the request.
Return type:str
urlobject = '/appservices/v6/orgs/{0}/devices'
urlobject_single = '/appservices/v6/orgs/{0}/devices/{1}'
vdi_base_device = None
virtual_machine = None
virtualization_provider = None
vulnerability_refresh()

Perform an action on a specific device. Only REFRESH is supported.

windows_platform = None
class DeviceSearchQuery(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 Device objects.

Initialize the DeviceSearchQuery.

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_DEPLOYMENT_TYPES = ['ENDPOINT', 'WORKLOAD']
VALID_DIRECTIONS = ['ASC', 'DESC']
VALID_OS = ['WINDOWS', 'ANDROID', 'MAC', 'IOS', 'LINUX', 'OTHER']
VALID_PRIORITIES = ['LOW', 'MEDIUM', 'HIGH', 'MISSION_CRITICAL']
VALID_STATUSES = ['PENDING', 'REGISTERED', 'UNINSTALLED', 'DEREGISTERED', 'ACTIVE', 'INACTIVE', 'ERROR', 'ALL', 'BYPASS_ON', 'BYPASS', 'QUARANTINE', 'SENSOR_OUTOFDATE', 'DELETED', 'LIVE']
background_scan(scan)

Set the background scan option for the specified devices.

Parameters:scan (bool) – True to turn background scan on, False to turn it off.
Returns:The JSON output from the request.
Return type:str
bypass(enable)

Set the bypass option for the specified devices.

Parameters:enable (bool) – True to enable bypass, False to disable it.
Returns:The JSON output from the request.
Return type:str
delete_sensor()

Delete the specified sensor devices.

Returns:The JSON output from the request.
Return type:str
download()

Uses the query parameters that have been set to download all device listings in CSV format.

Example

>>> cb.select(Device).set_status(["ALL"]).download()
Returns:The CSV raw data as returned from the server.
Return type:str
Raises:ApiError – If status values have not been set before calling this function.
quarantine(enable)

Set the quarantine option for the specified devices.

Parameters:enable (bool) – True to enable quarantine, False to disable it.
Returns:The JSON output from the request.
Return type:str
set_ad_group_ids(ad_group_ids)

Restricts the devices that this query is performed on to the specified AD group IDs.

Parameters:ad_group_ids (list) – List of AD group IDs to restrict the search to.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid (non-int) values are passed in the list.
set_deployment_type(deployment_type)

Restricts the devices that this query is performed on to the specified deployment types.

Parameters:deployment_type (list) – List of deployment types to restrict search to.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid deployment type values are passed in the list.
set_device_ids(device_ids)

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

Parameters:device_ids (list) – List of device IDs to restrict the search to.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid (non-int) values are passed in the list.
set_exclude_sensor_versions(sensor_versions)

Restricts the devices that this query is performed on to exclude specified sensor versions.

Parameters:sensor_versions (list) – List of sensor versions to be excluded.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid (non-string) values are passed in the list.
set_last_contact_time(*args, **kwargs)

Restricts the devices that this query is performed on to the specified last contact time.

Parameters:
  • *args (list) – Not used, retained for compatibility.
  • **kwargs (dict) – Keyword arguments to this function. The critical ones are “start” (the start time), “end” (the end time), and “range” (the range value).
Returns:

This instance.
Return type:

DeviceSearchQuery
Raises:

ApiError – If an invalid combination of keyword parameters are specified.
set_max_rows(max_rows)

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

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

Restricts the devices that this query is performed on to the specified operating systems.

Parameters:operating_systems (list) – List of operating systems to restrict search to. Valid values in this list are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER”.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid operating system values are passed in the list.
set_policy_ids(policy_ids)

Restricts the devices that this query is performed on to the specified policy IDs.

Parameters:policy_ids (list) – List of policy IDs to restrict the search to.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid (non-int) values are passed in the list.
set_status(statuses)

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

Parameters:statuses (list) – List of statuses to restrict search to. Valid values in this list are “PENDING”, “REGISTERED”, “UNINSTALLED”, “DEREGISTERED”, “ACTIVE”, “INACTIVE”, “ERROR”, “ALL”, “BYPASS_ON”, “BYPASS”, “QUARANTINE”, “SENSOR_OUTOFDATE”, “DELETED”, and “LIVE”.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid status values are passed in the list.
set_target_priorities(target_priorities)

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

Parameters:target_priorities (list) – List of priorities to restrict search to. Valid values in this list are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
Returns:This instance.
Return type:DeviceSearchQuery
Raises:ApiError – If invalid priority values are passed in the list.
sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

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

DeviceSearchQuery
Raises:

ApiError – If an invalid direction value is passed.
uninstall_sensor()

Uninstall the specified sensor devices.

Returns:The JSON output from the request.
Return type:str
update_policy(policy_id)

Set the current policy for the specified devices.

Parameters:policy_id (int) – ID of the policy to set for the devices.
Returns:The JSON output from the request.
Return type:str
update_sensor_version(sensor_version)

Update the sensor version for the specified devices.

Parameters:sensor_version (dict) – New version properties for the sensor.
Returns:The JSON output from the request.
Return type:str

cbc_sdk.platform.events module

Model and Query Classes for Events

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

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Event object in the Carbon Black server.

Initialize the Event object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – 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.
default_sort = 'last_update desc'
primary_key = 'process_guid'
urlobject = '/api/investigate/v2/orgs/{}/events/{}/_search'
validation_url = '/api/investigate/v1/orgs/{}/events/search_validation'
class EventFacet(cb, model_unique_id, initial_data)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a EventFacet object in the Carbon Black server.

Initialize an EventFacet object with initial_data.

class Ranges(cb, initial_data)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Ranges object in the Carbon Black server.

Initialize a ProcessFacet Ranges object with initial_data.

facets

Returns the reified EventFacet.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 a ProcessFacet Terms object with initial_data.

facets

Returns the terms’ facets for this result.

fields

Returns the terms facets’ fields for this result.

primary_key = 'process_guid'
ranges_

Returns the reified EventFacet.Ranges for this result.

terms_

Returns the reified EventFacet.Terms for this result.

urlobject = '/api/investigate/v2/orgs/{}/events/{}/_facet'
class EventFacetQuery(cls, cb, query=None)

Bases: cbc_sdk.base.FacetQuery

Represents the logic for an Event Facet query.

Initialize the FacetQuery object.

class EventQuery(doc_class, cb)

Bases: cbc_sdk.base.Query

Represents the logic for an Event query.

Initialize the Query object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

cbc_sdk.platform.grants module

Model and Query Classes for Administrative Grants and Profiles

class Grant(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.MutableBaseModel

Represents a Grant object in the Carbon Black server.

Variables:
  • principal – URN of principal
  • expires – Date and time the grant expires
  • revoked – True if this grant has been/is being revoked
  • roles – URNs of roles assigned to grant (obsolete)
  • profiles – Profiles assigned to this grant
  • org_ref – URN of org that this grant references
  • principal_name – Name of principal
  • created_by – URN of user that created this grant
  • updated_by – URN of user that last updated this grant
  • create_time – Date and time the grant was created
  • update_time – Date and time the grant was last updated
  • can_manage – True if can manage (TBD)

Initialize the Grant object.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • model_unique_id (str) – URN of the principal associated with this grant.
  • initial_data (dict) – Initial data used to populate the grant.
class GrantBuilder(cb, principal)

Bases: object

Auxiliary object used to construct a new grant.

Creates the empty GrantBuilder object.

Parameters:
  • cb (CBCloudAPI) – The reference to the API object that accesses the server.
  • principal (str) – The URN for the principal.
add_role(role)

Adds a role to be associated with the new grant.

Parameters:role (str) – URN of the role to be added.
Returns:This object.
Return type:GrantBuilder
build()

Builds the new Grant object from the entered data.

Returns:The new Grant object.
Return type:Grant
create_profile(template=None)

Returns either a new Profile, or a ProfileBuilder to begin the process of adding profile to the new grant.

Parameters:template (dict) – Optional template to use for creating the profile object.
Returns:If a template was specified, return the new Profile object. ProfileBuilder: If template was None, returns a ProfileBuilder object. Call methods on it to set
up the new profile, and then call build() to create the new profile.
Return type:Profile
set_org(org)

Sets the organization reference to be associated with the new grant.

Parameters:org (str) – Organization key or URN of the organization.
Returns:This object.
Return type:GrantBuilder
set_principal_name(name)

Sets the principal name to be associated with the new object.

Parameters:name (str) – Principal name to be used.
Returns:This object.
Return type:GrantBuilder
set_roles(roles)

Sets the roles to be associated with the new grant.

Parameters:roles (list) – List of role URNs.
Returns:This object.
Return type:GrantBuilder
class Profile(cb, grant, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.MutableBaseModel

Represents a Profile object in the Carbon Black server.

Variables:
  • profile_uuid – UUID identifying this profile
  • orgs – Organization references for this profile
  • org_groups – Organization groups added to this grant (TBD)
  • roles – URNs of roles assigned to profile
  • conditions – Access conditions to be imposed on this profile
  • can_manage – True if can manage (TBD)

Initialize the Profile object.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • grant (Grant) – Reference to the Grant containing this Profile.
  • model_unique_id (str) – UUID of this profile.
  • initial_data (dict) – Initial data used to populate the profile.
allowed_orgs

Returns the list of organization URNs allowed by this profile.

can_manage = None
conditions = {}
matches_template(template)

Returns whether or not the profile matches the given template.

Parameters:template (dict) – The profile template to match against.
Returns:True if this profile matches the template, False if not.
Return type:bool
org_groups = []
orgs = {}
primary_key = 'profile_uuid'
profile_uuid = None
roles = []
set_disabled(flag)

Sets the “disabled” flag on a profile.

Parameters:flag (bool) – True to disable the profile, False to enable it.
set_expiration(expiration)

Sets the expiration time on a profile.

Parameters:expiration (str) – Expiration time to set on the profile (ISO 8601 format).
urlobject = '/access/v2/orgs/{0}/grants/{1}/profiles'
urlobject_single = '/access/v2/orgs/{0}/grants/{1}/profiles/{2}'
class ProfileBuilder(grant)

Bases: object

Auxiliary object used to construct a new profile on a grant.

Create the empty ProfileBuilder object.

Parameters:grant (Grant/GrantBuilder) – The grant or GrantBuilder the new profile will be attached to.
add_org(org)

Adds the specified organization to the list of organizations for which the new profile is allowed.

Parameters:org (str) – Organization key or URN of the organization to be added.
Returns:This object.
Return type:ProfileBuilder
add_role(role)

Adds a role identifier to the list of roles associated with the new profile.

Parameters:role (str) – URN of the role to add.
Returns:This object.
Return type:ProfileBuilder
build()

Builds the new Profile object from the entered data.

Returns:The new Profile object.
Return type:Profile
set_conditions(conditions_structure)

Sets the access conditions associated with the new profile.

Parameters:conditions_structure (dict) – The conditions associated with the new profile, with ‘cidr’, ‘expiration’, and ‘disabled’ members.
Returns:This object.
Return type:ProfileBuilder
set_disabled(flag)

Sets whether or not the new profile is disabled.

Parameters:flag (bool) – True if this profile is disabled, False if noe.
Returns:This object.
Return type:ProfileBuilder
set_expiration(expiration)

Sets the expiration time on the new profile.

Parameters:expiration (str) – The expiration time, specified as ISO 8601.
Returns:This object.
Return type:ProfileBuilder
set_orgs(orgs_list)

Set the list of organizations to which the new profile is allowed access.

Parameters:orgs_list (list) – List of organization keys or URNs.
Returns:This object.
Return type:ProfileBuilder
set_roles(roles_list)

Sets the list of roles associated with the new profile.

Parameters:roles_list (list) – A list of role URNs.
Returns:This object.
Return type:ProfileBuilder
can_manage = None
classmethod create(cb, template=None, **kwargs)

Returns either a new Grant, or a GrantBuilder to begin the process of creating a new grant.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • template (dict) – Optional template to use for creating the grant object.
  • kwargs (dict) – Additional arguments to be used to specify the principal, if template is None. The arguments to be used are ‘org_key’ and ‘userid’ for the two parts of the ID.
Returns:

The new grant object, if the template is specified. GrantBuilder: If template was None, returns a GrantBuilder object. Call methods on it to set

up the new grant, and then call build() to create the new grant.
Return type:

Grant
Raises:

ApiError – If the principal is inadequately specified (whether for the Grant or GrantBuilder).
create_profile(template=None)

Returns either a new Profile, or a ProfileBuilder to begin the process of adding a new profile to this grant.

Parameters:template (dict) – Optional template to use for creating the profile object.
Returns:If a template was specified, return the new Profile object. ProfileBuilder: If template was None, returns a ProfileBuilder object. Call methods on it to set
up the new profile, and then call build() to create the new profile.
Return type:Profile
create_time = None
created_by = None
expires = None
classmethod get_permitted_role_urns(cb)

Returns a list of the URNs of all permitted roles that we can assign to a user.

Parameters:cb (CBCloudAPI) – A reference to the CBCloudAPI object.
Returns:A list of string role URNs that we are permitted to manage (assign to users).
Return type:list
org_ref = None
primary_key = 'principal'
principal = None
principal_name = None
profiles = []
profiles_

Return the profiles associated with this grant.

Returns:The profiles associated with this grant, each represented as a Profile object.
Return type:list
revoked = None
roles = []
update_time = None
updated_by = None
urlobject = '/access/v2/orgs/{0}/grants'
urlobject_single = '/access/v2/orgs/{0}/grants/{1}'
class GrantQuery(doc_class, cb)

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.AsyncQueryMixin

Query for retrieving grants in bulk.

Initialize the Query object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
add_principal(principal_urn, org_urn)

Add a new principal to the query.

Parameters:
  • principal_urn (str) – URN of the principal to search for grants on.
  • org_urn (str) – URN of the organization to which the principal belongs.
Returns:

This object.
Return type:

GrantQuery
log = <Logger cbc_sdk.platform.grants (WARNING)>

Grant and Profile Models

normalize_org(org)

Internal function to normalize an org reference to a URN.

cbc_sdk.platform.processes module

Model and Query Classes for Processes

class AsyncProcessQuery(doc_class, cb)

Bases: cbc_sdk.base.Query

Represents the query logic for an asychronous Process query.

This class specializes Query to handle the particulars of process querying.

Initialize the AsyncProcessQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
set_rows(rows)

Sets the ‘rows’ query parameter to the ‘results’ API call, determining how many rows to request per batch.

This will not limit the total results to rows instead the batch size will use rows and all of the num_available will be fetched.

Parameters:rows (int) – How many rows to request.
timeout(msecs)

Sets the timeout on a process query.

Parameters:msecs (int) – Timeout duration, in milliseconds.
Returns:
The Query object with new milliseconds
parameter.
Return type:Query (AsyncProcessQuery)

Example:

>>> cb.select(Process).where(process_name="foo.exe").timeout(5000)
class Process(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Process object in the Carbon Black server.

Initialize the Process object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – The unique ID (GUID) for this process.
  • 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.
class Summary(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Summary object in the Carbon Black server.

Initialize the Summary object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – 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.
SHOW_ATTR = {'children': {'fields': ['process_name', 'process_guid', 'process_hash', 'process_pid'], 'type': 'list'}, 'parent': {'fields': ['process_name', 'process_guid', 'process_hash', 'process_pid'], 'type': 'single'}, 'process': {'fields': ['device_id', 'device_name', 'process_name', 'parent_guid', 'parent_hash', 'parent_name', 'parent_pid', 'process_hash', 'process_pid'], 'type': 'single'}, 'siblings': {'fields': ['process_name', 'process_guid', 'process_hash', 'process_pid'], 'type': 'list'}}
default_sort = 'last_update desc'
primary_key = 'process_guid'
result_url = '/api/investigate/v2/orgs/{}/processes/summary_jobs/{}/results'
summary_format = 'summary'
urlobject = '/api/investigate/v2/orgs/{}/processes/summary_jobs'
class Tree(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Tree object in the Carbon Black server.

Initialize the Tree object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – 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.
SHOW_ATTR = {'children': ['process_name', 'process_guid', 'process_hash', 'process_pid'], 'top': ['device_id', 'device_name', 'process_name', 'parent_guid', 'parent_hash', 'parent_name', 'parent_pid', 'process_hash', 'process_pid']}
default_sort = 'last_update desc'
primary_key = 'process_guid'
result_url = '/api/investigate/v2/orgs/{}/processes/summary_jobs/{}/results'
summary_format = 'tree'
urlobject = '/api/investigate/v2/orgs/{}/processes/summary_jobs'
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)
children

Returns a list of child processes for this process.

Returns:
List of Processes, one for each child of the
parent Process.
Return type:children ([Process])
default_sort = 'last_update desc'
events(**kwargs)

Returns a query for events associated with this process’s process GUID.

Parameters:kwargs – Arguments to filter the event query with.
Returns:
Query object with the appropriate
search parameters for events
Return type:query (cbc_sdk.enterprise_edr.Query)

Example:

>>> [print(event) for event in process.events()]
>>> [print(event) for event in process.events(event_type="modload")]
facets()

Returns a FacetQuery for a Process.

This represents the search for a summary of result groupings (facets). The returned AsyncFacetQuery object must have facet fields or ranges specified before it can be submitted, using the add_facet_field() or add_range() methods.

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

Returns a parent process associated with this process.

Returns:Parent Process if one exists, None if the process has no recorded parent.
Return type:parent (Process)
primary_key = 'process_guid'
process_md5

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

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

Returns a list of PIDs associated with this process.

Returns:List of integer PIDs. None if there are no associated PIDs.
Return type:pids ([int])
process_sha256

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

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

Returns a list of sibling processes for this process.

Returns:
List of Processes, one for each sibling of the
parent Process.
Return type:siblings ([Process])
summary

Returns organization-specific information about this process.

tree

Returns a Process Tree associated with this process.

Returns:Tree with children (and possibly siblings).
Return type:Tree (cbc_sdk.enterprise_edr.Tree)

Example:

>>> tree = process.tree
urlobject = ''
validation_url = '/api/investigate/v1/orgs/{}/processes/search_validation'
class ProcessFacet(cb, model_unique_id, initial_data)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a ProcessFacet object in the Carbon Black server.

Variables:
  • job_id – The Job ID assigned to this query
  • terms – Contains the Process 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 a ResultFacet object with initial_data.

class Ranges(cb, initial_data)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Ranges object in the Carbon Black server.

Initialize a ProcessFacet Ranges object with initial_data.

facets

Returns the reified ProcessFacet.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 a ProcessFacet 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 ProcessFacet.Ranges for this result.

result_url = '/api/investigate/v2/orgs/{}/processes/facet_jobs/{}/results'
submit_url = '/api/investigate/v2/orgs/{}/processes/facet_jobs'
terms = {}
terms_

Returns the reified ProcessFacet.Terms for this result.

class SummaryQuery(doc_class, cb)

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.AsyncQueryMixin, cbc_sdk.base.QueryBuilderSupportMixin

Represents the logic for a Process Summary or Process Tree query.

Initialize the SummaryQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
results

Save query results to self._results with self._search() method.

set_time_range(start=None, end=None, window=None)

Sets the ‘time_range’ query body parameter, determining a time window based on ‘device_timestamp’.

Parameters:
  • start (str in ISO 8601 timestamp) – When to start the result search.
  • end (str in ISO 8601 timestamp) – When to end the result search.
  • window (str) – Time window to execute the result search, ending on the current time. Should be in the form “-2w”, where y=year, w=week, d=day, h=hour, m=minute, s=second.

Note

  • window will take precendent over start and end if provided.

Examples

query = api.select(Event).set_time_range(start=”2020-10-20T20:34:07Z”) second_query = api.select(Event).set_time_range(start=”2020-10-20T20:34:07Z”, end=”2020-10-30T20:34:07Z”) third_query = api.select(Event).set_time_range(window=’-3d’)

timeout(msecs)

Sets the timeout on a process query.

Parameters:msecs (int) – Timeout duration, in milliseconds.
Returns:
The Query object with new milliseconds
parameter.
Return type:Query (AsyncProcessQuery)

Example:

>>> cb.select(Process).where(process_name="foo.exe").timeout(5000)

cbc_sdk.platform.reputation module

Model and Query Classes for Reputation

class ReputationOverride(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.base.PlatformModel

Represents a ReputationOverride object in the Carbon Black server.

Variables:
  • id – An identifier for a reputation override
  • created_by – Creator of the override
  • create_time – Time the override was created
  • description – Justification for override
  • override_list – The override list to add a new reputation (BLACK_LIST only valid for SHA256)
  • override_type – Process property match when applying override
  • sha256_hash – A hexadecimal string of length 64 characters representing the SHA-256 hash of the application
  • filename – An application name for the hash
  • signed_by – Name of the signer for the application
  • certificate_authority – Certificate authority that authorizes the validity of the certificate
  • path – The absolute path to file or directory where tool exists on disk
  • include_child_processes – Include tool’s child processes on approved list

Initialize the ReputationOverride 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_delete(cb, overrides)

Deletes reputation overrides in bulk by id.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • overrides (List) – List if reputation override ids

Example

[
“e9410b754ea011ebbfd0db2585a41b07”

]

certificate_authority = None
classmethod create(cb, initial_data)

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.
  • initial_data (Object) – The initial data for a ReputationOverride

Example

{
“description”: “Banned as known malware”, “override_list”: “BLACK_LIST”, “override_type”: “SHA256”, “sha256_hash”: “dd191a5b23df92e13a8852291f9fb5ed594b76a28a5a464418442584afd1e048”, “filename”: “foo.exe”

}

Returns:The created ReputationOverride object based on the specified properties
Return type:ReputationOverride
create_time = None
created_by = None
delete()

Delete this object.

description = None
filename = None
id = None
include_child_processes = None
override_list = None
override_type = None
path = None
primary_key = 'id'
sha256_hash = None
signed_by = None
urlobject = '/appservices/v6/orgs/{0}/reputations/overrides'
urlobject_single = '/appservices/v6/orgs/{0}/reputations/overrides/{1}'
class ReputationOverrideQuery(doc_class, cb)

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.AsyncQueryMixin

Represents a query that is used to locate ReputationOverride objects.

Initialize the ReputationOverrideQuery.

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_DIRECTIONS = ['ASC', 'DESC', 'asc', 'desc']
set_override_list(override_list)

Sets the override_list criteria filter.

Parameters:override_list (str) – Override List to filter on.
Returns:The ReputationOverrideQuery with specified override_list.
set_override_type(override_type)

Sets the override_type criteria filter.

Parameters:override_type (str) – Override List to filter on.
Returns:The ReputationOverrideQuery with specified override_type.
sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

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

ReputationOverrideQuery
Raises:

ApiError – If an invalid direction value is passed.

cbc_sdk.platform.users module

Model and Query Classes for Users

class User(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.base.MutableBaseModel

Represents a User object in the Carbon Black server.

Variables:

Initialize the User object.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.
  • model_unique_id (int) – Login ID of this user.
  • initial_data (dict) – Initial data used to populate the user.
class UserBuilder(cb)

Bases: object

Auxiliary object used to construct a new User.

Create the empty UserBuilder object.

Parameters:cb (BaseAPI) – Reference to API object used to communicate with the server.
add_grant_profile(orgs, roles)

Adds a grant profile for the new user.

Parameters:
  • orgs (list[str]) – List of organizations to be allowed, specified as keys or URNs.
  • roles (list[str]) – List of roles to be granted, specified as URNs.
Returns:

This object.
Return type:

UserBuilder
build()

Builds the new user.

Notes

The new user will not be “findable” by other API functions until it has been activated and its initial password has been set.

set_auth_method(method)

Sets the authentication method for the new user. The default is ‘PASSWORD’.

Parameters:method (str) – The authentication method for the new user.
Returns:This object.
Return type:UserBuilder
set_email(email)

Sets the E-mail address for the new user.

Parameters:email (str) – The E-mail address for the new user.
Returns:This object.
Return type:UserBuilder
set_first_name(first_name)

Sets the first name for the new user.

Parameters:first_name (str) – The first name for the new user.
Returns:This object.
Return type:UserBuilder
set_last_name(last_name)

Sets the last name for the new user.

Parameters:last_name (str) – The last name for the new user.
Returns:This object.
Return type:UserBuilder
set_phone(phone)

Sets the phone number for the new user.

Parameters:phone (str) – The phone number for the new user.
Returns:This object.
Return type:UserBuilder
set_role(role)

Sets the role URN for the new user.

Parameters:role (str) – The URN of the role to set for the user.
Returns:This object.
Return type:UserBuilder
add_profiles(profile_templates)

Add the specified profiles to the user’s grant.

Parameters:profile_templates (list[dict]) – List of profile templates to be added to the user.
admin_login_version = None
auth_method = None
classmethod bulk_add_profiles(users, profile_templates)

Add the specified profiles to the specified users’ grants.

Parameters:
  • users (list[User]) – List of User objects specifying users to be modified.
  • profile_templates (list[dict]) – List of profile templates to be added to the users.
classmethod bulk_create(cb, user_templates, profile_templates)

Creates a series of new users.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • user_templates (list[dict]) – List of templates for users to be created.
  • profile_templates (list[dict]) – List of profile templates to be applied to each user.
classmethod bulk_delete(users)

Deletes all the listed users.

Parameters:users (list[User]) – List of User objects specifying users to be deleted.
classmethod bulk_disable_all_access(users)

Disables all access profiles held by the listed users.

Parameters:users (list[User]) – List of User objects specifying users to be disabled.
classmethod bulk_disable_profiles(users, profile_templates)

Disable the specified profiles in the specified users’ grants.

Parameters:
  • users (list[User]) – List of User objects specifying users to be modified.
  • profile_templates (list[dict]) – List of profile templates to be disabled.
change_role(role_urn, org=None)

Add the specified role to the user (either to the grant or the profiles).

Parameters:
  • role_urn (str) – URN of the role to be added.
  • org (str) – If specified, only profiles that match this organization will have the role added. Organization may be specified as either an org key or a URN.
Raises:

ApiError – If the user is a “legacy” user that has no grant.
contact_id = None
contact_version = None
classmethod create(cb, template=None)

Creates a new user.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • template (dict) – Optional template data for creating the new user.
Returns:

If template is None, returns an instance of this object. Call methods on the object to set

the values associated with the new user, and then call build() to create it.
Return type:

UserBuilder
disable_all_access()

Disables all access profiles held by ths user.

Raises:ApiError – If the user is a “legacy” user that has no grant.
disable_profiles(profile_templates)

Disable the specified profiles in the user’s grant.

Parameters:profile_templates (list[dict]) – List of profile templates to be disabled.
Raises:ApiError – If the user is a “legacy” user that has no grant.
email = None
first_name = None
grant()

Locates the access grant for this user.

Returns:Access grant for this user, or None if the user has none.
Return type:Grant
last_name = None
login_id = None
login_name = None
org_admin_version = None
org_id = None
org_key = None
org_urn

Returns the URN for this user’s organization (used in accessing Grants).

Returns:URN for this user’s organization.
Return type:str
phone = None
primary_key = 'login_id'
reset_google_authenticator_registration()

Forces Google Authenticator registration to be reset for this user.

role = None
set_profile_expiration(profile_templates, expiration_date)

Set the expiration time for the specified profiles in the user’s grant.

Parameters:
  • profile_templates (list[dict]) – List of profile templates to be reset.
  • expiration_date (str) – New expiration date, in ISO 8601 format.
Raises:

ApiError – If the user is a “legacy” user that has no grant.
urlobject = '/appservices/v6/orgs/{0}/users'
urlobject_single = '/appservices/v6/orgs/{0}/users/{1}'
urn

Returns the URN for this user (used in accessing Grants).

Returns:URN for this user.
Return type:str
class UserQuery(doc_class, cb)

Bases: cbc_sdk.base.BaseQuery, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.AsyncQueryMixin

Query for retrieving users in bulk.

Initialize the Query object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
email_addresses(addrs)

Limit the query to users with the specified E-mail addresses. Call multiple times to add multiple addresses.

Parameters:addrs (list[str]) – List of addresses to be added to the query.
Returns:This object.
Return type:UserQuery
user_ids(userids)

Limit the query to users with the specified user IDs. Call multiple times to add multiple user IDs.

Parameters:userids (list[str]) – List of user IDs to be added to the query.
Returns:This object.
Return type:UserQuery
normalize_profile_list(profile_templates)

Internal function to normalize a list of profile templates.

Module contents