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.platform.base.PlatformQueryBase, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin

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', 'VMWARE', '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_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”, “VMWARE”, 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.
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 VMwareAlert(cb, model_unique_id, initial_data=None)

Bases: cbc_sdk.platform.alerts.BaseAlert

Represents a VMwareAlert 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/vmware'
class VMwareAlertSearchQuery(doc_class, cb)

Bases: cbc_sdk.platform.alerts.BaseAlertSearchQuery

Represents a query that is used to locate VMwareAlert objects.

Initialize the VMwareAlertSearchQuery.

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_group_ids(groupids)

Restricts the alerts that this query is performed on to the specified AppDefense-assigned alarm group IDs.

Parameters:groupids (list) – List of (integer) AppDefense-assigned alarm group IDs.
Returns:This instance.
Return type:VMwareAlertSearchQuery
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 AsyncProcessQuery(doc_class, cb)

Bases: cbc_sdk.enterprise_edr.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.
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 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.enterprise_edr.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.
MAX_EVENT_SEARCH_RETRIES = 10

Platform Models

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.
class PlatformQueryBase(doc_class, cb)

Bases: object

Represents the base of all LiveQuery query classes.

Initialize the PlatformQueryBase object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
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.
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.
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'
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.

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.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
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
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
windows_platform = None
class DeviceSearchQuery(doc_class, cb)

Bases: cbc_sdk.platform.base.PlatformQueryBase, cbc_sdk.base.QueryBuilderSupportMixin, 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_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_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_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

Module contents