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 basic alert.
Parameters: - category – Alert category - Monitored vs Threat
- create_time – Time the alert was created
- device_id – ID of the device (empty for Container Runtime alerts)
- device_name – Device name (empty for Container Runtime alerts)
- device_os – Device OS (empty for Container Runtime alerts)
- device_os_version – Device OS Version (empty for Container Runtime alerts)
- 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 (empty for Container Runtime alerts)
- 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.
-
class
Note
(cb, alert, model_unique_id, initial_data=None)¶ Bases:
cbc_sdk.platform.base.PlatformModel
Represents a note within an alert.
Parameters: - author – User who created the note
- create_time – Time the note was created
- id – Unique ID for this note
- note – Note contents
Initialize the Note object.
Parameters: -
create_time
= None¶
-
delete
()¶ Deletes a note from an alert.
-
id
= None¶
-
note
= None¶
-
primary_key
= 'id'¶
-
urlobject
= '/appservices/v6/orgs/{0}/alerts/{1}/notes'¶
-
urlobject_single
= '/appservices/v6/orgs/{0}/alerts/{1}/notes/{2}'¶
-
category
= None¶
-
create_note
(note)¶ Creates a new note.
-
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_
()¶ Retrieves all notes for an alert.
-
notes_present
= None¶
-
org_key
= None¶
-
policy_id
= None¶
-
policy_name
= None¶
-
primary_key
= 'id'¶
-
static
search_suggestions
(cb, query)¶ Returns suggestions for keys and field values that can be used in a search.
Parameters: - cb (CBCloudAPI) – A reference to the CBCloudAPI object.
- query (str) – A search query to use.
Returns: A list of search suggestions expressed as dict objects.
Return type: list
Raises: ApiError
– if cb is not instance of CBCloudAPI
-
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.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', 'CONTAINER_RUNTIME']¶
-
VALID_CATEGORIES
= ['THREAT', 'MONITORED']¶
-
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_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:
-
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”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”. Returns: This instance. Return type: BaseAlertSearchQuery Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.
-
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 CB Analytics alerts.
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
ContainerRuntimeAlert
(cb, model_unique_id, initial_data=None)¶ Bases:
cbc_sdk.platform.alerts.BaseAlert
Represents Container Runtime alerts.
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/containerruntime'¶
-
class
ContainerRuntimeAlertSearchQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.alerts.BaseAlertSearchQuery
Represents a query that is used to locate ContainerRuntimeAlert objects.
Initialize the ContainerRuntimeAlertSearchQuery.
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_cluster_names
(names)¶ Restricts the alerts that this query is performed on to the specified Kubernetes cluster names.
Parameters: names (list) – List of Kubernetes cluster names to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_egress_group_ids
(ids)¶ Restricts the alerts that this query is performed on to the specified egress group IDs.
Parameters: ids (list) – List of egress group IDs to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_egress_group_names
(names)¶ Restricts the alerts that this query is performed on to the specified egress group names.
Parameters: names (list) – List of egress group names to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_ip_reputations
(reputations)¶ Restricts the alerts that this query is performed on to the specified IP reputation values.
Parameters: reputations (list) – List of IP reputation values to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_namespaces
(namespaces)¶ Restricts the alerts that this query is performed on to the specified Kubernetes namespaces.
Parameters: namespaces (list) – List of Kubernetes namespaces to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_ports
(ports)¶ Restricts the alerts that this query is performed on to the specified listening ports.
Parameters: ports (list) – List of listening ports to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_protocols
(protocols)¶ Restricts the alerts that this query is performed on to the specified protocols.
Parameters: protocols (list) – List of protocols to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_remote_domains
(domains)¶ Restricts the alerts that this query is performed on to the specified remote domains.
Parameters: domains (list) – List of remote domains to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_remote_ips
(addrs)¶ Restricts the alerts that this query is performed on to the specified remote IP addresses.
Parameters: addrs (list) – List of remote IP addresses to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_replica_ids
(ids)¶ Restricts the alerts that this query is performed on to the specified pod names.
Parameters: ids (list) – List of pod names to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_rule_ids
(ids)¶ Restricts the alerts that this query is performed on to the specified Kubernetes policy rule IDs.
Parameters: ids (list) – List of Kubernetes policy rule IDs to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_rule_names
(names)¶ Restricts the alerts that this query is performed on to the specified Kubernetes policy rule names.
Parameters: names (list) – List of Kubernetes policy rule names to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_workload_ids
(ids)¶ Restricts the alerts that this query is performed on to the specified workload IDs.
Parameters: ids (list) – List of workload IDs to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_workload_kinds
(kinds)¶ Restricts the alerts that this query is performed on to the specified workload types.
Parameters: kinds (list) – List of workload types to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
set_workload_names
(names)¶ Restricts the alerts that this query is performed on to the specified workload names.
Parameters: names (list) – List of workload names to look for. Returns: This instance. Return type: ContainerRuntimeAlertSearchQuery
-
class
DeviceControlAlert
(cb, model_unique_id, initial_data=None)¶ Bases:
cbc_sdk.platform.alerts.BaseAlert
Represents Device Control alerts.
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 DeviceControlAlertSearchQuery.
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 watch list alerts.
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_process
(async_mode=False)¶ Gets the process corresponding with the alert.
Parameters: async_mode – True to request process in an asynchronous manner. Returns: The process corresponding to the alert. Return type: Process
-
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 the workflow associated with alerts.
Parameters: - 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 the current workflow status of a request.
Parameters: - 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
PlatformModel
(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents the base of all Platform API model classes.
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 (endpoint).
Parameters: - 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 – Not used. Intended for when the background scan was last active
- scan_last_complete_time – Not Used. Intended for when the background scan was last completed
- scan_status – Not Used. Intended for 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)
- deployment_type – Classification determined by the device lifecycle management policy
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.
- Required Permissions:
- device.bg-scan (EXECUTE)
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.
- Required Permissions:
- device.bypass (EXECUTE)
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.
- Required Permissions:
- device.deregistered (DELETE)
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
- Required Permissions:
- vulnerabilityAssessment.data (READ)
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
(async_mode=False)¶ Retrieve a Live Response session object for this Device.
- Required Permissions:
- org.liveresponse.session (CREATE)
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¶
-
nsx_available
¶ Returns whether NSX actions are available on this device.
Returns: True if NSX actions are available, False if not. Return type: bool
-
nsx_remediation
(tag, set_tag=True)¶ Start an NSX Remediation job on this device to change the tag.
- Required Permissions:
- appliances.nsx.remediation(EXECUTE)
Parameters: - tag (str) – The NSX tag to apply to this device. Valid values are “CB-NSX-Quarantine”, “CB-NSX-Isolate”, and “CB-NSX-Custom”.
- set_tag (bool) – True to toggle the specified tag on, False to toggle it off. Default True.
Returns: The object representing all running jobs. None if the operation is a no-op.
Return type:
-
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.
- Required Permissions:
- device.quarantine (EXECUTE)
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.
- Required Permissions:
- device.uninstall (EXECUTE)
Returns: The JSON output from the request. Return type: str
-
update_policy
(policy_id)¶ Set the current policy for this device.
- Required Permissions:
- device.policy (UPDATE)
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.
- Required Permissions:
- org.kits (EXECUTE)
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.
- Required Permissions:
- vulnerabilityAssessment.data (EXECUTE)
-
windows_platform
= None¶
-
class
DeviceFacet
(cb, model_unique_id, initial_data=None)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a device field in a facet search.
Parameters: - field – Name of the field being faceted
- values – The values of the faceted field.
Initialize the DeviceFacet object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- model_unique_id (str) – Not used.
- initial_data (dict) – Initial data used to populate the facet.
-
class
DeviceFacetValue
(cb, outer, model_unique_id, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a value of a particular field.
Initialize the DeviceFacetValue object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- outer (DeviceFacet) – Reference to outer facet object.
- model_unique_id (str) – Value ID.
- initial_data (dict) – Initial data used to populate the facet value.
-
query_devices
()¶ Set up a device query to find all devices that match this facet value.
Example
>>> facets = api.select(Device).where('').facets(['policy_id']) >>> for value in facets[0].values_: ... print(f"Policy ID = {value.id}:") ... for dev in value.query_devices(): ... print(f" {dev.name} ({dev.last_external_ip_address})")
Returns: A new DeviceQuery set with the criteria, which may have additional criteria added to it. Return type: DeviceQuery
-
field
= None¶
-
primary_key
= 'id'¶
-
urlobject
= '/appservices/v6/orgs/{0}/devices/_facet'¶
-
values
= []¶
-
values_
¶ Return the list of facet values for this facet.
Returns: The list of values for this facet. Return type: list[DeviceFacetValue]
-
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_FACET_FIELDS
= ['policy_id', 'status', 'os', 'ad_group_id', 'cloud_provider_account_id', 'auto_scaling_group_name', 'virtual_private_cloud_id']¶
-
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.
- Required Permissions:
- device.bg-scan (EXECUTE)
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.
- Required Permissions:
- device.bypass (EXECUTE)
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.
- Required Permissions:
- device.deregistered (DELETE)
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()
- Required Permissions:
- device (READ)
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.
-
facets
(fieldlist, max_rows=0)¶ Return information about the facets for all known evices, using the defined criteria.
Example
>>> query = api.select(Device).where('') >>> facets = query.facets(['policy_id', 'status', 'os', 'ad_group_id']) >>> for f in facets: ... print(f"Field {f.field} - {len(f.values_)} distinct values")
- Required Permissions:
- device (READ)
Parameters: - fieldlist (list[str]) – List of facet field names. Valid names are “policy_id”, “status”, “os”, “ad_group_id”, “cloud_provider_account_id”, “auto_scaling_group_name”, and “virtual_private_cloud_id”.
- max_rows (int) – The maximum number of rows to return. 0 means return all rows.
Returns: A list of facet information.
Return type: list[DeviceFacet]
-
quarantine
(enable)¶ Set the quarantine option for the specified devices.
- Required Permissions:
- device.quarantine (EXECUTE)
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_auto_scaling_group_name
(group_names)¶ Restricts the devices that this query is performed on to the specified auto scaling group names.
Parameters: group_names (list) – List of group names to restrict search to. Returns: This instance. Return type: DeviceSearchQuery
-
set_cloud_provider_account_id
(account_ids)¶ Restricts the devices that this query is performed on to the specified cloud provider account IDs.
Parameters: account_ids (list) – List of account IDs to restrict search to. Returns: This instance. Return type: DeviceSearchQuery
-
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: 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.
-
set_virtual_private_cloud_id
(cloud_ids)¶ Restricts the devices that this query is performed on to the specified virtual private cloud IDs.
Parameters: cloud_ids (list) – List of cloud IDs to restrict search to. Returns: This instance. Return type: DeviceSearchQuery
-
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.
- Required Permissions:
- device.uninstall (EXECUTE)
Returns: The JSON output from the request. Return type: str
-
update_policy
(policy_id)¶ Set the current policy for the specified devices.
- Required Permissions:
- device.policy (UPDATE)
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.
- Required Permissions:
- org.kits (EXECUTE)
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
Events can be queried for via CBCloudAPI.select or an already selected process with Process.events().
Examples
>>> events_query = (api.select(Event).where(process_guid= "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")) # retrieve results synchronously >>> events = [event for event in events_query] # retrieve results asynchronously >>> future = events_query.execute_async() >>> events = future.result() # use an already selected process >>> process = api.select(Process, "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb") >>> events_query = process.events() >>> events = [event for event in events_query]
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 the results of an EventFacetQuery.
EventFacet objects contain both Terms and Ranges. Each of those contain facet fields and values.
Access all of the Terms facet data with
EventFacet.Terms.facets()
or see just the field names withEventFacet.Terms.fields()
.Access all of the Ranges facet data with
EventFacet.Ranges.facets()
or see just the field names withEventFacet.Ranges.fields()
.Event Facets can be queried for via CBCloudAPI.select(EventFacet). Specify a Process GUID with `.where(process_guid=”example_guid”), and facet field(s) with .add_facet_field(“my_facet_field”).
Examples
>>> event_facet_query = (api.select(EventFacet).where(process_guid= "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")) >>> event_facet_query.add_facet_field("event_type") # retrieve results synchronously >>> facet = event_facet_query.results # retrieve results asynchronously >>> future = event_facet_query.execute_async() >>> result = future.result() # result is a list with one item, so access the first item >>> facet = result[0]
Initialize an EventFacet object with initial_data.
-
class
Ranges
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents the range (bucketed) facet fields and values associated with an Event Facet query.
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 the facet fields and values associated with an Event Facet query.
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.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 of access to the Carbon Black Cloud.
Parameters: - principal – URN of principal
- expires – Date and time the grant expires
- 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 an access profile assigned to a grant.
Parameters: - 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: -
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.
- arguments to be used are 'org_key' and 'userid' for the two parts of the ID. (The) –
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: 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
-
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:
-
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.jobs module¶
Model and Query Classes for Jobs API
-
class
Job
(cb, model_unique_id, initial_data=None)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents a job currently executing in the background.
Parameters: - connector_id – Connector ID for the job
- create_time – Time this job was created
- errors – Errors for the job
- id – ID of the job
- job_parameters – Parameters that were used for this job
- last_update_time – Last time this job was updated
- org_key – Organization key of the org this job is being run against
- owner_id – ID of the job owner
- status – Current job status
- type – Type of job this is
Initialize the Job object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- model_unique_id (int) – ID of the job.
- initial_data (dict) – Initial data used to populate the job.
-
await_completion
()¶ Create a Python Future to check for job completion and return results when available.
Returns a Future object which can be used to await results that are ready to fetch. This function call does not block.
- Required Permissions:
- jobs.status(READ)
Returns: - A future which can be used to wait for this job’s completion. When complete, the result of the
- Future will be this object.
Return type: Future
-
connector_id
= None¶
-
create_time
= None¶
-
errors
= None¶
-
get_output_as_file
(filename)¶ Export the results from the job, writing the results to the given file.
- Required Permissions:
- jobs.status(READ)
Parameters: filename (str) – Name of the file to write the results to.
-
get_output_as_lines
()¶ Export the results from the job, returning the data as iterated lines of text.
This is only intended for output that can reasonably be represented as lines of text, such as plain text or CSV. If a job outputs structured text like JSON or XML, this method should not be used.
- Required Permissions:
- jobs.status(READ)
Returns: An iterable that can be used to get each line of text in turn as a string. Return type: iterable
-
get_output_as_stream
(output)¶ Export the results from the job, writing the results to the given stream.
- Required Permissions:
- jobs.status(READ)
Parameters: output (RawIOBase) – Stream to write the CSV data from the request to.
-
get_output_as_string
()¶ Export the results from the job, returning the results as a string.
- Required Permissions:
- jobs.status(READ)
Returns: The results from the job. Return type: str
-
get_progress
()¶ Get and return the current progress information for the job.
- Required Permissions:
- jobs.status(READ)
Returns: Total number of items to be operated on by this job. int: Total number of items for which operation has been completed. str: Current status message for the job. Return type: int
-
id
= None¶
-
job_parameters
= {}¶
-
last_update_time
= None¶
-
org_key
= None¶
-
owner_id
= None¶
-
primary_key
= 'id'¶
-
progress
= {}¶
-
status
= None¶
-
type
= None¶
-
urlobject
= '/jobs/v1/orgs/{0}/jobs'¶
-
urlobject_single
= '/jobs/v1/orgs/{0}/jobs/{1}'¶
-
class
JobQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.AsyncQueryMixin
Query for retrieving current jobs.
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.network_threat_metadata module¶
Model Class for NetworkThreatMetadata
-
class
NetworkThreatMetadata
(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents a NetworkThreatMetadata
Parameters: - detector_abstract – Abstract or description of the detector
- detector_goal – Description of what the detector is achieving
- false_negatives – Highlights why detector could not have been triggered
- false_positives – Highlights why detector could have been triggered
- threat_public_comment – Public comment of the threat
Initialize the NetworkThreatMetadata object.
- Required Permissions:
- org.xdr.metadata (READ)
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) – Not used, retained for compatibility.
- force_init (bool) – False to not force object initialization.
- full_doc (bool) – True to mark the object as fully initialized.
Raises: ApiError
– if model_unique_id is not provided-
detector_abstract
= None¶
-
detector_goal
= None¶
-
false_negatives
= None¶
-
false_positives
= None¶
-
primary_key
= 'tms_rule_id'¶
-
threat_public_comment
= None¶
-
urlobject
= '/threatmetadata/v1/orgs/{0}/detectors/{1}'¶
cbc_sdk.platform.observations module¶
Model and Query Classes for Observations
-
class
Observation
(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents an Observation
Initialize the Observation object.
- Required Permissions:
- org.search.events (READ)
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) – False to mark the object as not fully initialized.
-
alert_category
= []¶
-
alert_id
= []¶
-
backend_timestamp
= None¶
-
static
bulk_get_details
(cb, alert_id=None, observation_ids=None, timeout=0)¶ Bulk get details
Parameters: - cb (CBCloudAPI) – A reference to the CBCloudAPI object.
- alert_id (str) – An alert id to fetch associated observations
- observation_ids (list) – A list of observation ids to fetch
- timeout (int) – Observations details request timeout in milliseconds.
Returns: list of Observations
Return type: list
Raises: ApiError
– if cb is not instance of CBCloudAPI
-
device_group_id
= None¶
-
device_id
= None¶
-
device_name
= None¶
-
device_policy
= None¶
-
device_policy_id
= None¶
-
device_timestamp
= None¶
-
enriched
= None¶
-
enriched_event_type
= None¶
-
event_description
= None¶
-
event_id
= None¶
-
event_network_inbound
= None¶
-
event_network_local_ipv4
= None¶
-
event_network_location
= None¶
-
event_network_protocol
= None¶
-
event_network_remote_ipv4
= None¶
-
event_network_remote_port
= None¶
-
event_type
= []¶
-
get_details
(timeout=0, async_mode=False)¶ Requests detailed results.
Parameters: - timeout (int) – Observations details request timeout in milliseconds.
- async_mode (bool) – True to request details in an asynchronous manner.
Returns: Observation object enriched with the details fields
Return type: 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.
Examples
>>> observation = api.select(Observation, observation_id) >>> observation.get_details()
>>> observations = api.select(Observation.where(process_pid=2000) >>> observations[0].get_details()
-
get_network_threat_metadata
()¶ Requests Network Threat Metadata.
Returns: Get the metadata for a given detector (rule). Return type: NetworkThreatMetadata Raises: ApiError
– when rule_id is not returned for the ObservationExamples
>>> observation = api.select(Observation, observation_id) >>> threat_metadata = observation.get_network_threat_metadata()
-
ingress_time
= None¶
-
legacy
= None¶
-
observation_description
= None¶
-
observation_id
= None¶
-
observation_type
= None¶
-
org_id
= None¶
-
parent_guid
= None¶
-
parent_pid
= None¶
-
primary_key
= 'observation_id'¶
-
process_guid
= None¶
-
process_hash
= []¶
-
process_name
= None¶
-
process_pid
= []¶
-
process_username
= []¶
-
rule_id
= None¶
-
static
search_suggestions
(cb, query, count=None)¶ Returns suggestions for keys and field values that can be used in a search.
Parameters: - cb (CBCloudAPI) – A reference to the CBCloudAPI object.
- query (str) – A search query to use.
- count (int) – (optional) Number of suggestions to be returned
Returns: A list of search suggestions expressed as dict objects.
Return type: list
Raises: ApiError
– if cb is not instance of CBCloudAPI
-
validation_url
= '/api/investigate/v2/orgs/{}/observations/search_validation'¶
-
class
ObservationFacet
(cb, model_unique_id, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents an observation facet retrieved.
Parameters: - terms – Contains the Observations Facet search results
- ranges – Groupings for search result properties that are ISO 8601 timestamps or numbers
- contacted – The number of searchers contacted for this query
- completed – The number of searchers that have reported their results
Initialize the Terms object with initial data.
-
class
Ranges
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents the range (bucketed) facet fields and values associated with an Observation Facet query.
Initialize an ObservationFacet Ranges object with initial_data.
-
facets
¶ Returns the reified ObservationFacet.Terms._facets for this result.
-
fields
¶ Returns the ranges fields for this result.
-
-
class
Terms
(cb, initial_data)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents the facet fields and values associated with an Observation Facet query.
Initialize an ObservationFacet 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¶
-
num_found
= None¶
-
primary_key
= 'job_id'¶
-
ranges
= []¶
-
ranges_
¶ Returns the reified ObservationFacet.Ranges for this result.
-
result_url
= '/api/investigate/v2/orgs/{}/observations/facet_jobs/{}/results'¶
-
submit_url
= '/api/investigate/v2/orgs/{}/observations/facet_jobs'¶
-
terms
= []¶
-
terms_
¶ Returns the reified ObservationFacet.Terms for this result.
-
class
ObservationGroup
(cb, initial_data=None)¶ Bases:
object
Represents ObservationGroup
Initialize ObservationGroup object
Parameters: - cb (CBCloudAPI) – A reference to the CBCloudAPI object.
- initial_data (dict) – The data to use when initializing the model object.
Notes
The constructed object will have the following data: - group_start_timestamp - group_end_timestamp - group_key - group_value
-
class
ObservationQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.Query
Represents the query logic for an Observation query.
This class specializes Query to handle the particulars of observations querying.
Initialize the ObservationQuery object.
Parameters: - doc_class (class) – The class of the model this query returns.
- cb (CBCloudAPI) – A reference to the CBCloudAPI object.
-
VALID_GROUP_FIELDS
= ['observation_type', 'device_name', 'process_username', 'attack_tactic']¶
-
get_group_results
(fields, max_events_per_group=None, rows=500, start=None, range_duration=None, range_field=None, range_method=None)¶ Get group results grouped by provided fields.
Parameters: - fields (str / list) – field or fields by which to perform the grouping
- max_events_per_group (int) – Maximum number of events in a group, if not provided, all events will be returned
- rows (int) – Number of rows to request, can be paginated
- start (int) – First row to use for pagination
- ranges (dict) – dict with information about duration, field, method
Returns: grouped results
Return type: dict
Examples
>>> for group in api.select(Observation).where(process_pid=2000).get_group_results("device_name"): >>> ...
-
or_
(**kwargs)¶ or_()
criteria are explicitly provided to Observation queries.This method overrides the base class in order to provide or_() functionality rather than raising an exception.
-
set_rows
(rows)¶ Sets the ‘rows’ query body parameter to the ‘start search’ API call, determining how many rows to request.
Parameters: rows (int) – How many rows to request. Returns: ObservationQuery object Return type: Query Example
>>> cb.select(Observation).where(process_name="foo.exe").set_rows(50)
-
timeout
(msecs)¶ Sets the timeout on a observation query.
Parameters: msecs (int) – Timeout duration, in milliseconds. Returns: - The Query object with new milliseconds
- parameter.
Return type: Query (ObservationQuery) Example
>>> cb.select(Observation).where(process_name="foo.exe").timeout(5000)
cbc_sdk.platform.policies module¶
Policy implementation as part of Platform API
-
class
Policy
(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.base.MutableBaseModel
Represents a policy within the organization.
Create one of these objects (either directly or with the CBCloudAPI.create() method) and set its properties, then call its save() method to create the policy on the server. This requires the org.policies(CREATE) permission.
Alternatively, you may call Policy.create() to get a PolicyBuilder, use its methods to set the properties of the new policy, call its build() method to build the populated Policy, then call the policy save() method.
To update a Policy, change the values of its property fields, then call the policy’s save() method. This requires the org.policies(UPDATE) permission.
To delete an existing Policy, call its delete() method. This requires the org.policies(DELETE) permission.
For information on values for policy settings including enumeration values, see the Policy Service API page: https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/policy-service/#fields
Parameters: - id – The policy identifier
- name – Defined name for the policy
- org_key – The organization key associated with the console instance
- priority_level – The priority level designated for policy
- is_system – Indicates that the policy was created by VMware
- description – The description of the policy
- auto_deregister_inactive_vdi_interval_ms – The time in milliseconds to wait after a VDI is inactive before setting the VDI to a DEREGISTERED state
- auto_delete_known_bad_hashes_delay – Enables the Carbon Black Cloud to automatically delete known malware after a specified time in milliseconds
- av_settings – Anti-Virus settings for endpoints and workloads assigned to the policy
- rules – Permission or prevention rules
- directory_action_rules – Rules to deny or allow the deployed sensors to send uploads from specific paths
- sensor_settings – Settings to configure sensor behavior and capabilities
- managed_detection_response_permissions – Permissions for Managed Detection and Response analysts to perform remediations on endpoints and workloads assigned to the policy
- version – Version of the policy
Initialize the Policy object.
- Required Permissions:
- org.policies (READ)
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- model_unique_id (int) – ID of the policy.
- initial_data (dict) – Initial data used to populate the policy.
- force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
- full_doc (bool) – If True, object is considered “fully” initialized. Default False.
-
class
PolicyBuilder
(cb)¶ Bases:
object
Builder object to simplify the creation of new Policy objects.
To use, call Policy.create() to get a PolicyBuilder, use its methods to set the properties of the new policy, call its build() method to build the populated Policy, then call the policy save() method. The org.policy(CREATE) permission is required.
Examples
>>> builder = Policy.create(api) >>> builder.set_name("New Policy").set_priority("MEDIUM").set_description("New policy description") >>> # more calls here to set up rules, sensor settings, etc. >>> policy = builder.build() >>> policy.save()
Initialize the PolicyBuilder object.
Parameters: cb (BaseAPI) – Reference to API object used to communicate with the server. -
add_directory_action_rule
(path, file_upload, protection)¶ Add a directory action rule to the new policy.
Parameters: - path (str) – Path to the file or directory.
- file_upload (bool) – True to allow the deployed sensor to upload from that path.
- protection (bool) – True to deny the deployed sensor to upload from that path.
Returns: This object.
Return type:
-
add_rule
(app_type, app_value, operation, action, required=True)¶ Add a new rule as discrete data elements to the new policy.
Parameters: - app_type (str) – Specifies “NAME_PATH”, “SIGNED_BY”, or “REPUTATION”.
- app_value (str) – Value of the attribute specified by app_type to be matched.
- operation (str) – The type of behavior the application is performing.
- action (str) – The action the sensor will take when the application performs the specified action.
- required (bool) – True if this rule is required, False if not.
Returns: This object.
Return type: Raises: InvalidObjectError
– If the rule data passed in is not valid.
-
add_rule_config
(config_id, name, category, **kwargs)¶ Add a new rule configuration as discrete data elements to the new policy.
Parameters: - config_id (str) – ID of the rule configuration object (a GUID).
- name (str) – Name of the rule configuration object.
- category (str) – Category of the rule configuration object.
- **kwargs (dict) – Parameter values for the rule configuration object.
Returns: This object.
Return type: Raises: InvalidObjectError
– If the rule configuration data passed in is not valid.
-
add_rule_config_copy
(rule_config)¶ Adds a copy of an existing rule configuration to this new policy.
Parameters: rule_config (PolicyRuleConfig) – The rule configuration to copy and add to this object. Returns: This object. Return type: PolicyBuilder Raises: InvalidObjectError
– If the rule configuration data passed in is not valid.
-
add_rule_copy
(rule)¶ Adds a copy of an existing rule to this new policy.
Parameters: rule (PolicyRule) – The rule to copy and add to this object. Returns: This object. Return type: PolicyBuilder Raises: InvalidObjectError
– If the rule data passed in is not valid.
-
add_sensor_setting
(name, value)¶ Add a sensor setting to the policy.
Parameters: - name (str) – Sensor setting name.
- value (str) – Sensor setting value.
Returns: This object.
Return type: Raises: ApiError
– If the sensor setting name is not a valid one.
-
build
()¶ Build a new Policy object using the contents of this builder.
The new policy must have save() called on it to be saved to the server.
Returns: The new Policy object. Return type: Policy
-
set_auto_delete_bad_hash_delay
(delay)¶ Set the delay in milliseconds after which known malware will be deleted.
Parameters: delay (int) – The desired delay interval in milliseconds. Returns: This object. Return type: PolicyBuilder
-
set_auto_deregister_interval
(interval)¶ Set the time in milliseconds after a VDI goes inactive to deregister it.
Parameters: interval (int) – The desired interval in milliseconds. Returns: This object. Return type: PolicyBuilder
-
set_avira_protection_cloud
(enabled, max_exe_delay=None, max_file_size=None, risk_level=None)¶ Set the settings for third-party unknown binary reputation analysis.
Parameters: - enabled (bool) – True to enable unknown binary reputation analysis.
- max_exe_delay (int) – Time before sending unknown binary for analysis, in seconds.
- max_file_size (int) – Maximum size of file to send for analysis, in megabytes.
- risk_level (int) – Risk level to send for analysis (0-7).
Returns: This object.
Return type:
-
set_description
(descr)¶ Set the new policy description.
Parameters: descr (str) – The new policy description. Returns: This object. Return type: PolicyBuilder
-
set_managed_detection_response_permissions
(policy_mod, quarantine)¶ Set the permissions for managed detection and response.
Parameters: - policy_mod (bool) – True to allow MDR team to modify the policy.
- quarantine (bool) – True to allow MDR team to quarantine endpoints/workloads associated with the policy.
Returns: This object.
Return type:
-
set_name
(name)¶ Set the new policy name.
Parameters: name (str) – The new policy name. Returns: This object. Return type: PolicyBuilder
-
set_on_access_scan
(enabled, mode='NORMAL')¶ Sets the local scan settings.
Parameters: - enabled (bool) – True to enable local scan.
- mode (str) – The mode to operate in, either “NORMAL” or “AGGRESSIVE”.
Returns: This object.
Return type: Raises: ApiError
– If an invalid value is passed for the “mode” parameter.
-
set_on_demand_scan
(enabled, profile='NORMAL', scan_usb='AUTOSCAN', scan_cd_dvd='AUTOSCAN')¶ Sets the background scan settings.
Parameters: - enabled (bool) – True to enable background scan.
- profile (str) – The background scan mode, either “NORMAL” or “AGGRESSIVE”.
- scan_usb (str) – Either “AUTOSCAN” to scan USB devices, or “DISABLED” to not do so.
- scan_cd_dvd (str) – Either “AUTOSCAN” to scan CDs and DVDs, or “DISABLED” to not do so.
Returns: This object.
Return type: Raises: ApiError
– If an invalid value is passed for any parameter.
-
set_on_demand_scan_schedule
(days, start_hour, range_hours, recover_if_missed=True)¶ Sets the schedule for when background scans will be performed.
Parameters: - days (list[str]) – The days on which to perform background scans.
- start_hour (int) – The hour of the day at which to perform the scans.
- range_hours (int) – The range of hours over which to perform the scans.
- recover_if_missed (bool) – True if the background scan should be performed ASAP if it’s been missed.
Returns: This object.
Return type: Raises: ApiError
– If an invalid value is passed for a day of the week.
-
set_priority
(priority)¶ Set the new policy’s priority. Default is MEDIUM.
Parameters: priority (str) – The priority, either “LOW”, “MEDIUM”, “HIGH”, or “MISSION_CRITICAL”. Returns: This object. Return type: PolicyBuilder Raises: ApiError
– If an invalid priority value is passed in.
-
set_signature_update
(enabled)¶ Set the enable status for signature updates.
Parameters: enabled (bool) – True to enable signature updates. Returns: This object. Return type: PolicyBuilder
-
set_signature_update_schedule
(full_interval_hours, initial_random_delay_hours, interval_hours)¶ Set the signature update schedule.
Parameters: - full_interval_hours (int) – The interval in hours between signature updates.
- initial_random_delay_hours (int) – The initial delay in hours before the first signature update.
- interval_hours (int) – The interval in hours between signature updates.
Returns: This object.
Return type:
-
set_update_servers_offsite
(names)¶ Sets the list of update servers for offsite devices.
Parameters: names (list[str]) – The list of update servers, as URIs. Returns: This object. Return type: PolicyBuilder
-
set_update_servers_onsite
(names, preferred_servers=None)¶ Sets the list of update servers for internal devices.
Parameters: - names (list[str]) – The list of available update servers, as URIs.
- preferred_servers (list[str]) – The list of update servers to be considered “preferred,” as URIs.
Returns: This object.
Return type:
-
set_update_servers_override
(names)¶ Sets the list of update servers to override offsite/onsite settings.
Parameters: names (list[str]) – The server names to use, as a list of URIs. Returns: This object. Return type: PolicyBuilder
-
-
VALID_DAYS
= ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']¶
-
VALID_PRIORITIES
= ['LOW', 'MEDIUM', 'HIGH', 'MISSION_CRITICAL']¶
-
VALID_SCAN_MODES
= ['NORMAL', 'AGGRESSIVE']¶
-
VALID_SCAN_OPTIONS
= ['AUTOSCAN', 'DISABLED']¶
-
VALID_SENSOR_SETTINGS
= ['SHOW_UI', 'ALLOW_UNINSTALL', 'ALLOW_UPLOAD', 'QUARANTINE_DEVICE', 'ENABLE_FORENSICS', 'LOGGING_LEVEL', 'QUARANTINE_DEVICE_MESSAGE', 'ENABLE_THREAT_SHARING', 'SET_SENSOR_MODE', 'SENSOR_RESET', 'BLOCK_REMOVABLE_MEDIA', 'POLICY_ACTION_OVERRIDE', 'BACKGROUND_SCAN', 'RATE_LIMIT', 'QUEUE_SIZE', 'DROP_CONNECTION_TIME', 'CONNECTION_LIMIT', 'LEARNING_MODE', 'SET_AV_MODE', 'SCAN_NETWORK_DRIVE', 'BYPASS_AFTER_RESTART_MINS', 'BYPASS_AFTER_LOGIN_MINS', 'HELP_MESSAGE', 'SHOW_FULL_UI', 'SCAN_EXECUTE_ON_NETWORK_DRIVE', 'DELAY_EXECUTE', 'ALLOW_INLINE_BLOCKING', 'PRESERVE_SYSTEM_MEMORY_SCAN', 'HASH_MD5', 'SCAN_LARGE_FILE_READ', 'SECURITY_CENTER_OPT', 'CB_LIVE_RESPONSE', 'UNINSTALL_CODE', 'ALLOW_EXPEDITED_SCAN', 'UBS_OPT_IN', 'DISABLE_MALWARE_SERVICES']¶
-
add_rule
(new_rule)¶ Adds a rule to this Policy.
Parameters: new_rule (dict(str,str)) – The new rule to add to this Policy. Notes
The new rule must conform to this dictionary format:
{“action”: “ACTION”, “application”: {“type”: “TYPE”, “value”: “VALUE”}, “operation”: “OPERATION”, “required”: “REQUIRED”}
The dictionary keys have these possible values:
“action”: [“IGNORE”, “ALLOW”, “DENY”, “TERMINATE_PROCESS”, “TERMINATE_THREAD”, “TERMINATE”]
“type”: [“NAME_PATH”, “SIGNED_BY”, “REPUTATION”]
“value”: Any string value to match on
“operation”: [“BYPASS_ALL”, “INVOKE_SCRIPT”, “INVOKE_SYSAPP”, “POL_INVOKE_NOT_TRUSTED”, “INVOKE_CMD_INTERPRETER”, “RANSOM”, “NETWORK”, “PROCESS_ISOLATION”, “CODE_INJECTION”, “MEMORY_SCRAPE”, “RUN_INMEMORY_CODE”, “ESCALATE”, “RUN”]
“required”: [True, False]
-
auto_delete_known_bad_hashes_delay
= None¶
-
auto_deregister_inactive_vdi_interval_ms
= None¶
-
av_settings
= {}¶
-
core_prevention_rule_configs
¶ Returns a dictionary of core prevention rule configuration IDs and objects for this Policy.
Returns: - A dictionary with core prevention rule configuration IDs as keys and CorePreventionRuleConfig objects
- as values.
Return type: dict
-
core_prevention_rule_configs_list
¶ Returns a list of core prevention rule configuration objects for this Policy.
Returns: A list of CorePreventionRuleConfig objects. Return type: list
-
classmethod
create
(cb)¶ Begins creating a policy by returning a PolicyBuilder.
Parameters: cb (BaseAPI) – Reference to API object used to communicate with the server. Returns: The new policy builder object. Return type: PolicyBuilder
-
delete_rule
(rule_id)¶ Deletes a rule from this Policy.
Parameters: rule_id (int) – The ID of the rule to be deleted. Raises: ApiError
– If the rule ID does not exist in this policy.
-
delete_rule_config
(rule_config_id)¶ Deletes a rule configuration from this Policy.
Parameters: rule_config_id (str) – The ID of the rule configuration to be deleted. Raises: ApiError
– If the rule configuration ID does not exist in this policy.
-
description
= None¶
-
directory_action_rules
= []¶
-
get_ruleconfig_parameter_schema
(ruleconfig_id)¶ Returns the parameter schema for a specified rule configuration.
Uses cached rule configuration presentation data if present.
Parameters: ruleconfig_id (str) – The rule configuration ID (UUID). Returns: The parameter schema for this particular rule configuration (a JSON schema). Return type: dict Raises: InvalidObjectError
– If the rule configuration ID is not valid.
-
id
= None¶
-
is_system
= None¶
-
latestRevision
¶ Returns the latest revision of this policy (compatibility method).
-
managed_detection_response_permissions
= {}¶
-
name
= None¶
-
object_rule_configs
¶ Returns a dictionary of rule configuration IDs and objects for this Policy.
Returns: A dictionary with rule configuration IDs as keys and PolicyRuleConfig objects as values. Return type: dict
-
object_rule_configs_list
¶ Returns a list of rule configuration objects for this Policy.
Returns: A list of PolicyRuleConfig objects. Return type: list
-
object_rules
¶ Returns a dictionary of rule objects and rule IDs for this Policy.
Returns: A dictionary with rule IDs as keys and PolicyRule objects as values. Return type: dict
-
org_key
= None¶
-
policy
¶ Returns the contents of this policy [compatibility method].
-
position
= None¶
-
primary_key
= 'id'¶
-
priorityLevel
¶ Returns the priority level of this policy (compatibility method).
-
priority_level
= None¶
-
replace_rule
(rule_id, new_rule)¶ Replaces a rule in this policy.
Parameters: - rule_id (int) – The ID of the rule to be replaced.
- new_rule (dict) – The data for the new rule.
Raises: ApiError
– If the rule ID does not exist in this policy.
-
replace_rule_config
(rule_config_id, new_rule_config)¶ Replaces a rule configuration in this policy.
Parameters: - rule_config_id (str) – The ID of the rule configuration to be replaced.
- new_rule_config (dict) – The data for the new rule configuration.
Raises: ApiError
– If the rule configuration ID does not exist in this policy.
-
rules
= []¶
-
sensor_settings
= []¶
-
systemPolicy
¶ Returns whether or not this is a systsem policy (compatibility method).
-
urlobject
= '/policyservice/v1/orgs/{0}/policies'¶
-
urlobject_single
= '/policyservice/v1/orgs/{0}/policies/{1}'¶
-
valid_rule_configs
()¶ Returns a dictionary identifying all valid rule configurations for this policy.
Returns: - A dictionary mapping string ID values (UUIDs) to dicts containing entries for name, description,
- and category.
Return type: dict
-
version
= None¶
-
class
PolicyQuery
(doc_class, cb)¶ Bases:
cbc_sdk.base.BaseQuery
,cbc_sdk.base.IterableQueryMixin
,cbc_sdk.base.AsyncQueryMixin
Query for retrieving policies (summary info only).
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_descriptions
(descrs)¶ Add policy description(s) to the list to search for.
Parameters: descrs (str/list) – Either a single policy description or a list of descriptions. Returns: This object instance. Return type: PolicyQuery Raises: ApiError
– If not supplied with a string or a list of strings.
-
add_names
(names)¶ Add policy name(s) to the list to search for.
Parameters: names (str/list) – Either a single policy name or a list of names. Returns: This object instance. Return type: PolicyQuery Raises: ApiError
– If not supplied with a string or a list of strings.
-
add_policy_ids
(ids)¶ Add policy ID(s) to the list to search for.
Parameters: ids (int/list) – Either a single policy ID or a list of IDs. Returns: This object instance. Return type: PolicyQuery Raises: ApiError
– If not supplied with an int or a list of ints.
-
add_priorities
(priorities)¶ Add policy priority/priorities to the list to search for.
Parameters: priorities (str/list) – Either a single policy priority value or a list of priority values. Returns: This object instance. Return type: PolicyQuery Raises: ApiError
– If not supplied with a string priority value or a list of string priority values.
-
set_system
(system)¶ Set to look for either system or non-system policies.
Parameters: system (bool) – True to look for system policies, False to look for non-system policies. Returns: This object instance. Return type: PolicyQuery Raises: ApiError
– If not supplied with a Boolean.
-
class
PolicyRule
(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.base.MutableBaseModel
Represents a rule in the policy.
Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule to the policy. This requires the org.policies(UPDATE) permission.
To update a PolicyRule, change the values of its property fields, then call the rule’s save() method. This requires the org.policies(UPDATE) permission.
To delete an existing PolicyRule, call its delete() method. This requires the org.policies(UPDATE) permission.
Parameters: - id – The identifier of the rule
- action – The action the sensor will take when an application attempts to perform the selected operation
- application – The path, signature or reputation of the application
- operation – The type of behavior an application is performing
Initialize the PolicyRule object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- parent (Policy) – The “parent” policy of this rule.
- model_unique_id (int) – ID of the rule.
- initial_data (dict) – Initial data used to populate the rule.
- force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
- full_doc (bool) – If True, object is considered “fully” initialized. Default False.
-
VALID_ACTIONS
= ['IGNORE', 'ALLOW', 'TERMINATE_PROCESS', 'TERMINATE_THREAD', 'TERMINATE', 'DENY']¶
-
VALID_APP_KEYS
= {'type', 'value'}¶
-
VALID_APP_TYPES
= ['NAME_PATH', 'SIGNED_BY', 'REPUTATION']¶
-
VALID_OPERATIONS
= ['BYPASS_ALL', 'BYPASS_API', 'INVOKE_SCRIPT', 'INVOKE_SYSAPP', 'POL_INVOKE_NOT_TRUSTED', 'INVOKE_CMD_INTERPRETER', 'RANSOM', 'NETWORK', 'PROCESS_ISOLATION', 'CODE_INJECTION', 'MEMORY_SCRAPE', 'RUN_INMEMORY_CODE', 'ESCALATE', 'RUN']¶
-
VALID_REPUTATIONS
= ['ADAPTIVE_WHITE_LIST', 'ADWARE', 'COMMON_WHITE_LIST', 'COMPANY_BLACK_LIST', 'COMPANY_WHITE_LIST', 'HEURISTIC', 'IGNORE', 'KNOWN_MALWARE', 'LOCAL_WHITE', 'NOT_LISTED', 'PUP', 'RESOLVING', 'SUSPECT_MALWARE', 'TRUSTED_WHITE_LIST']¶
-
action
= None¶
-
application
= {}¶
-
id
= None¶
-
is_deleted
¶ Returns True if this rule object has been deleted.
-
operation
= None¶
-
primary_key
= 'id'¶
-
required
= None¶
-
validate
()¶ Validates this rule against its constraints.
Raises: InvalidObjectError
– If the rule object is not valid.
cbc_sdk.platform.policy_ruleconfigs module¶
Policy rule configuration implementation as part of Platform API
-
class
CorePreventionRuleConfig
(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.platform.policy_ruleconfigs.PolicyRuleConfig
Represents a core prevention rule configuration in the policy.
Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule configuration to the policy. This requires the org.policies(UPDATE) permission.
To update a CorePreventionRuleConfig, change the values of its property fields, then call its save() method. This requires the org.policies(UPDATE) permission.
To delete an existing CorePreventionRuleConfig, call its delete() method. This requires the org.policies(DELETE) permission.
Parameters: - id – The ID of this rule config
- name – The name of this rule config
- description – The description of this rule config
- inherited_from – Indicates where the rule config was inherited from
- category – The category for this rule config
- parameters – The parameters associated with this rule config
Initialize the CorePreventionRuleConfig object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- parent (Policy) – The “parent” policy of this rule configuration.
- model_unique_id (str) – ID of the rule configuration.
- initial_data (dict) – Initial data used to populate the rule configuration.
- force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
- full_doc (bool) – If True, object is considered “fully” initialized. Default False.
-
category
= None¶
-
description
= None¶
-
get_assignment_mode
()¶ Returns the assignment mode of this core prevention rule configuration.
Returns: The assignment mode, either “REPORT” or “BLOCK”. Return type: str
-
id
= None¶
-
inherited_from
= None¶
-
name
= None¶
-
parameters
= {}¶
-
set_assignment_mode
(mode)¶ Sets the assignment mode of this core prevention rule configuration.
Parameters: mode (str) – The new mode to set, either “REPORT” or “BLOCK”. The default is “BLOCK”.
-
class
PolicyRuleConfig
(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶ Bases:
cbc_sdk.base.MutableBaseModel
Represents a rule configuration in the policy.
Create one of these objects, associating it with a Policy, and set its properties, then call its save() method to add the rule configuration to the policy. This requires the org.policies(UPDATE) permission.
To update a PolicyRuleConfig, change the values of its property fields, then call its save() method. This requires the org.policies(UPDATE) permission.
To delete an existing PolicyRuleConfig, call its delete() method. This requires the org.policies(DELETE) permission.
Parameters: - id – The ID of this rule config
- name – The name of this rule config
- description – The description of this rule config
- inherited_from – Indicates where the rule config was inherited from
- category – The category for this rule config
- parameters – The parameters associated with this rule config
Initialize the PolicyRuleConfig object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- parent (Policy) – The “parent” policy of this rule configuration.
- model_unique_id (str) – ID of the rule configuration.
- initial_data (dict) – Initial data used to populate the rule configuration.
- force_init (bool) – If True, forces the object to be refreshed after constructing. Default False.
- full_doc (bool) – If True, object is considered “fully” initialized. Default False.
-
category
= None¶
-
description
= None¶
-
get_parameter
(name)¶ Returns a parameter value from the rule configuration.
Parameters: name (str) – The parameter name. Returns: The parameter value, or None if there is no value. Return type: Any
-
id
= None¶
-
inherited_from
= None¶
-
name
= None¶
-
parameters
= {}¶
-
primary_key
= 'id'¶
-
set_parameter
(name, value)¶ Sets a parameter value into the rule configuration.
Parameters: - name (str) – The parameter name.
- value (Any) – The new value to be set.
-
urlobject
= '/policyservice/v1/orgs/{0}/policies'¶
-
validate
()¶ Validates this rule configuration against its constraints.
Raises: InvalidObjectError
– If the rule object is not valid.
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 retrieved by one of the Enterprise EDR endpoints.
Examples
# use the Process GUID directly
>>> process = api.select(Process, "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")
# use the Process GUID in a where() clause
>>> process_query = (api.select(Process).where(process_guid= "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")) >>> process_query_results = [proc for proc in process_query] >>> process_2 = process_query_results[0]
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 of organization-specific information for a process.
The preferred interface for interacting with Summary models is Process.summary.
Example
>>> process = api.select(Process, "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb") >>> summary = process.summary
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 summary of organization-specific information for a process.
The preferred interface for interacting with Tree models is Process.tree.
Example
>>> process = api.select(Process, "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb") >>> tree = process.tree
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 the results of an AsyncFacetQuery.
ProcessFacet objects contain both Terms and Ranges. Each of those contain facet fields and values.
Access all of the Terms facet data with
ProcessFacet.Terms.facets()
or see just the field names withProcessFacet.Terms.fields()
.Access all of the Ranges facet data with
ProcessFacet.Ranges.facets()
or see just the field names withProcessFacet.Fanges.fields()
.Process Facets can be queried for via CBCloudAPI.select(ProcessFacet). Specify facet field(s) with .add_facet_field(“my_facet_field”).
Optionally you can limit the facet query to a single process with the following two options. Using the solrq builder specify Process GUID with .where(process_guid=”example_guid”) and modify the query with .or_(parent_effective_reputation=”KNOWN_MALWARE”) and .and_(parent_effective_reputation=”KNOWN_MALWARE”).
If you want full control over the query string specify Process Guid in the query string .where(“process_guid: example_guid OR parent_effective_reputation: KNOWN_MALWARE”) Examples:
>>> process_facet_query = (api.select(ProcessFacet).where(process_guid= "WNEXFKQ7-00050603-0000066c-00000000-1d6c9acb43e29bb")) >>> process_facet_query.add_facet_field("device_name")
# retrieve results synchronously
>>> facet = process_facet_query.results
# retrieve results asynchronously
>>> future = process_facet_query.execute_async() >>> result = future.result()
# result is a list with one item, so access the first item
>>> facet = result[0]
Parameters: - 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 the range (bucketed) facet fields and values associated with a Process Facet query.
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 the facet fields and values associated with a Process Facet query.
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 reputation override.
Parameters: - 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" ]
-
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: 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 in the Carbon Black Cloud.
Parameters: - org_key – Organization key for this user
- auth_method – Method to be used for the user to authenticate
- admin_login_version – Version number of the user information
- email – User’s E-mail address
- login_name – Login name for the user
- login_id – Login ID (user ID) for this user
- phone – User’s phone number
- first_name – User’s first name
- last_name – User’s last name
- org_id – ID of the organization the user is in
- org_admin_version – TBD
- role – Not used, always “DEPRECATED”
- contact_id – ID of the user’s contact information
- contact_version – Version of the user’s contact information
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:
-
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:
-
delete
()¶ Delete this object.
-
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.
-
log
= <Logger cbc_sdk.platform.users (WARNING)>¶ User Models
-
normalize_profile_list
(profile_templates)¶ Internal function to normalize a list of profile templates.
cbc_sdk.platform.vulnerability_assessment module¶
Model and Query Classes for Vulnerability Assessment API
-
class
AffectedAssetQuery
(vulnerability, cb)¶ Bases:
cbc_sdk.platform.vulnerability_assessment.VulnerabilityQuery
Query Class for the Vulnerability
Initialize the AffectedAssetQuery.
Parameters: - vulnerability (class) – The vulnerability that will be returned by this query.
- cb (BaseAPI) – Reference to API object used to communicate with the server.
-
set_os_product_id
(os_product_id, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified os_product_id.
Parameters: - os_product_id (str) – os_product_id.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
class
Vulnerability
(cb, model_unique_id, os_product_id=None, initial_data=None)¶ Bases:
cbc_sdk.base.NewBaseModel
Represents a vulnerability
Parameters: - affected_assets – List of affected assets
- category – Vulnerability category
- device_count – Number of affected devices
- os_info – Information about the operating system associated with the vulnerability
- os_product_id – Operating system product ID
- product_info – Information about the vulnerable product
- vuln_info – Information about the vulnerability
Initialize the Vulnerability object.
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- model_unique_id (str) – ID of the vulnerability represented.
- os_product_id (str) – os_product_id of the vulnerabilty used to uniquely identify a CVE with multiple OS/Product instances
- initial_data (dict) – Initial data used to populate the alert.
-
class
AssetView
(cb, initial_data=None)¶ Bases:
list
Represents a list of Vulnerability for an organization.
Initialize Vulnerability.AssetView object
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- initial_data (list[dict]) – list of assets and their vulnerabilty view
-
swagger_meta_file
= 'workload/models/vulnerabilityAssetView.yaml'¶
-
urlobject
= '/vulnerability/assessment/api/v1/orgs/{}'¶
-
class
OrgSummary
(cb, initial_data=None)¶ Bases:
cbc_sdk.base.UnrefreshableModel
Represents a vulnerability summary for an organization.
Parameters: - monitored_assets – Number of assets being monitored
- severity_summary – Information about vulnerabilities at each severity level
Initialize Vulnerability.OrgSummary object
Parameters: - cb (BaseAPI) – Reference to API object used to communicate with the server.
- initial_data (dict) – dictionary of the data
-
monitored_assets
= None¶
-
severity_levels
()¶ Returns the severity levels
Returns: List of severities Return type: Severities (list[str])
-
severity_summary
= {}¶
-
urlobject
= '/vulnerability/assessment/api/v1/orgs/{}'¶
-
affected_assets
= []¶
-
category
= None¶
-
device_count
= None¶
-
get_affected_assets
()¶ Returns an AffectedAssetQuery to fetch the list of devices affected by the Vulnerability.
- Args;
- os_product_id (str) operating system product ID
Returns: AffectedAssetQuery
-
os_info
= {}¶
-
os_product_id
= None¶
-
perform_action
(type, reason=None, notes=None)¶ Take an action to manage the Vulnerability.
Parameters: - type (str) – The type of action. (supports DISMISS, DISMISS_EDIT, or UNDISMISS)
- reason (str) – The reason the vulnerabilty is dismissed. Required when type is DISMISS or DISMISS_EDIT. (supports FALSE_POSITIVE, RESOLUTION_DEFERRED, NON_ISSUE, NON_CRITICAL_ASSET, UNDER_RESOLUTION, OTHER)
- notes (str) – Notes to be associated with the dismissal. Required when reason is OTHER.
Returns: The action response
Return type: obj
Raises: ApiError
– If the request is invalid or missing required properties
-
primary_key
= 'cve_id'¶
-
product_info
= {}¶
-
urlobject
= '/vulnerability/assessment/api/v1/orgs/{}'¶
-
vuln_info
= {}¶
-
class
VulnerabilityAssetViewQuery
(doc_class, cb)¶ Bases:
cbc_sdk.platform.vulnerability_assessment.VulnerabilityQuery
Represents a query that is used fetch the Vulnerability Asset View
Initialize the VulnerabilityAssetViewQuery.
Parameters: - doc_class (class) – The model class that will be returned by this query.
- cb (BaseAPI) – Reference to API object used to communicate with the server.
-
class
VulnerabilityOrgSummaryQuery
(doc_class, cb, device=None)¶ Bases:
cbc_sdk.base.BaseQuery
Represents a query that is used fetch the VulnerabiltitySummary
Initialize the VulnerabilityQuery.
Parameters: -
VALID_SEVERITY
= ['CRITICAL', 'IMPORTANT', 'MODERATE', 'LOW']¶
-
VALID_VISIBILITY
= ['DISMISSED', 'ACTIVE']¶
-
set_severity
(severity)¶ Restricts the vulnerability summary to a severity level
Parameters: severity (str) – filters the vulnerability summary per severity (CRITICAL, IMPORTANT, MODERATE, LOW) Returns: This instance. Return type: VulnerabilityOrgSummaryQuery
-
set_vcenter
(vcenter_uuid)¶ Restricts the vulnerability summary to a specific vcenter
Parameters: vcenter_uuid (str) – vcenter uuid. Returns: This instance. Return type: VulnerabilityOrgSummaryQuery
-
set_visibility
(visibility)¶ Restricts the vulnerabilities that this query is performed on to the specified visibility
Parameters: visibility (str) – The visibility state of the vulnerabilty. (supports ACTIVE, DISMISSED) Returns: This instance. Return type: VulnerabilityOrgSummaryQuery
-
submit
()¶ Performs the query and returns the Vulnerability.OrgSummary
Returns: The vulnerabilty summary for the organization Return type: Vulnerability.OrgSummary
-
-
class
VulnerabilityQuery
(doc_class, cb, device=None)¶ 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 Vulnerabiltity objects.
Initialize the VulnerabilityQuery.
Parameters: -
VALID_DEVICE_TYPE
= ['WORKLOAD', 'ENDPOINT']¶
-
VALID_DIRECTIONS
= ['ASC', 'DESC']¶
-
VALID_OS_TYPE
= ['CENTOS', 'RHEL', 'SLES', 'UBUNTU', 'WINDOWS']¶
-
VALID_SEVERITY
= ['CRITICAL', 'IMPORTANT', 'MODERATE', 'LOW']¶
-
VALID_SYNC_STATUS
= ['NOT_STARTED', 'MATCHED', 'ERROR', 'NOT_MATCHED', 'NOT_SUPPORTED', 'CANCELLED', 'IN_PROGRESS', 'ACTIVE', 'COMPLETED']¶
-
VALID_SYNC_TYPE
= ['MANUAL', 'SCHEDULED']¶
-
VALID_VISIBILITY
= ['DISMISSED', 'ACTIVE']¶
-
add_criteria
(key, value, operator='EQUALS')¶ Restricts the vulnerabilities that this query is performed on to the specified key value pair.
Parameters: - key (str) – Property from the vulnerability object
- value (str) – Value of the property to filter by
- operator (str) – (optional) logic operator to apply to property value.
Returns: This instance.
Return type:
-
export
()¶ Performs the query and export the results in the form of a Job.
Example
>>> # Create the Vulnerability query >>> query = cb.select(Vulnerability).set_severity('CRITICAL') >>> # Export the results >>> job = query.export() >>> # wait for the export to finish >>> job.await_completion() >>> # write the results to a file >>> job.get_output_as_file("vulnerabilities.csv")
Returns: The export job. Return type: Job
-
set_deployment_type
(deployment_type, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified deployment type.
Parameters: - deployment_type (str) – deployment type (“ENDPOINT”, “AWS”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_device_type
(device_type, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified device type.
Parameters: - device_type (str) – device type (“WORKLOAD”, “ENDPOINT”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_highest_risk_score
(highest_risk_score, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified highest_risk_score.
Parameters: - highest_risk_score (double) – highest_risk_score.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_last_sync_ts
(last_sync_ts, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified last_sync_ts.
Parameters: - last_sync_ts (str) – last_sync_ts.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_name
(name, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified name.
Parameters: - name (str) – name.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_os_arch
(os_arch, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified os_arch.
Parameters: - os_arch (str) – os_arch.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_os_name
(os_name, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified os_name.
Parameters: - os_name (str) – os_name.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_os_type
(os_type, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified os type.
Parameters: - os_type (str) – os type (“CENTOS”, “RHEL”, “SLES”, “UBUNTU”, “WINDOWS”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_os_version
(os_version, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified os_version.
Parameters: - os_version (str) – os_version.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_severity
(severity, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified severity.
Parameters: - severity (str) – severity (“CRITICAL”, “IMPORTANT”, “MODERATE”, “LOW”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_sync_status
(sync_status, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified sync_status.
Parameters: - sync_status (str) – sync_status (“NOT_STARTED”, “MATCHED”, “ERROR”, “NOT_MATCHED”, “NOT_SUPPORTED”, “CANCELLED”, “IN_PROGRESS”, “ACTIVE”, “COMPLETED”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_sync_type
(sync_type, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified sync_type.
Parameters: - sync_type (str) – sync_type (“MANUAL”, “SCHEDULED”)
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_vcenter
(vcenter_uuid)¶ Restricts the vulnerabilities that this query is performed on to the specified vcenter id.
Parameters: vcenter_uuid (str) – vcenter uuid. Returns: This instance. Return type: VulnerabilityQuery
-
set_visibility
(visibility)¶ Restricts the vulnerabilities that this query is performed on to the specified visibility
Parameters: visibility (str) – The visibility state of the vulnerabilty. (supports ACTIVE, DISMISSED) Returns: This instance. Return type: VulnerabilityQuery
-
set_vm_id
(vm_id, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified vm_id.
Parameters: - vm_id (str) – vm_id.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
set_vuln_count
(vuln_count, operator)¶ Restricts the vulnerabilities that this query is performed on to the specified vuln_count.
Parameters: - vuln_count (str) – vuln_count.
- operator (str) – logic operator to apply to property value.
Returns: This instance.
Return type:
-
sort_by
(key, direction='ASC')¶ Sets the sorting behavior on a query’s results.
Example
>>> cb.select(Vulnerabiltiy).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.
-
-
log
= <Logger cbc_sdk.platform.vulnerability_assessment (WARNING)>¶ Vulnerability models