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¶
-
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
= {}¶
-
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:
-
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
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:
-
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
= {}¶
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
-
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: - activation_code – Device activation code
- activation_code_expiry_time – When the expiration code expires and cannot be used to register a device
- ad_group_id – Device’s AD group
- av_ave_version – AVE version (part of AV Version)
- av_engine – Current AV version
- av_last_scan_time – Last AV scan time
- av_master – Whether the device is an AV Master (?)
- av_pack_version – Pack version (part of AV Version)
- av_product_version – AV Product version (part of AV Version)
- av_status – AV Statuses
- av_update_servers – Device’s AV servers
- av_vdf_version – VDF version (part of AV Version)
- current_sensor_policy_name – Current MSM policy name
- deregistered_time – When the device was deregistered with the PSC backend
- device_id – ID of the device
- device_meta_data_item_list – MSM Device metadata
- device_owner_id – ID of the user who owns the device
- email – Email of the user who owns the device
- encoded_activation_code – Encoded device activation code
- first_name – First name of the user who owns the device
- id – ID of the device
- last_contact_time – Time the device last checked into the PSC backend
- last_device_policy_changed_time – Last time the device’s policy was changed
- last_device_policy_requested_time – Last time the device requested policy updates
- last_external_ip_address – Device’s external IP
- last_internal_ip_address – Device’s internal IP
- last_location – Location of the device (on-/off-premises)
- last_name – Last name of the user who owns the device
- last_policy_updated_time – Last time the device was MSM processed
- last_reported_time – Time when device last reported an event to PSC backend
- last_reset_time – When the sensor was last reset
- last_shutdown_time – When the device last shut down
- linux_kernel_version – Linux kernel version
- login_user_name – Last acive logged in username
- mac_address – Device’s hardware MAC address
- middle_name – Middle name of the user who owns the device
- name – Device Hostname
- organization_id – Org ID to which the device belongs
- organization_name – Name of the org that owns this device
- os – Device type
- os_version – Version of the OS
- passive_mode – Whether the device is in passive mode (bypass?)
- policy_id – ID of the policy this device is using
- policy_name – Name of the policy this device is using
- policy_override – Manually assigned policy (overrides mass sensor management)
- quarantined – Whether the device is quarantined
- registered_time – When the device was registered with the PSC backend
- scan_last_action_time – When the background scan was last active
- scan_last_complete_time – When the background scan was last completed
- scan_status – Background scan status
- sensor_out_of_date – Whether the device is out of date
- sensor_states – Active sensor states
- sensor_version – Version of the PSC sensor
- status – Device status
- target_priority_type – Priority of the device
- uninstall_code – Code to enter to uninstall this device
- vdi_base_device – VDI Base device
- virtual_machine – Whether this device is a Virtual Machine (VMware AppDefense integration
- virtualization_provider – VM Virtualization Provider
- windows_platform – Type of windows platform (client/server, x86/x64)
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: 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: 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