Platform Package
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:
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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- log = <Logger cbc_sdk.platform.base (WARNING)>
Platform Models
Submodules
Alerts Module
Model and Query Classes for Platform Alerts and Workflows
- class Alert(cb, model_unique_id, initial_data=None)
Bases:
PlatformModel
Represents a basic alert.
- Parameters:
additional_events_present – Indicator to let API and forwarder users know that they should look up other associated events related to this alert
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
attack_tactic – A tactic from the MITRE ATT&CK framework; defines a reason for an adversary’s action, such as achieving credential access
attack_technique – A technique from the MITRE ATT&CK framework; defines an action an adversary takes to accomplish a goal, such as dumping credentials to achieve credential access
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
blocked_effective_reputation – Effective reputation of the blocked file or process; applied by the sensor at the time the block occurred
blocked_md5 – MD5 hash of the child process binary; for any process terminated by the sensor
blocked_name – Tokenized file path of the files blocked by sensor action
blocked_sha256 – SHA-256 hash of the child process binary; for any process terminated by the sensor
category – Alert category - Monitored vs Threat
childproc_cmdline – Command line for the child process
childproc_effective_reputation – Effective reputation of the child process; applied by the sensor at the time the event occurred
childproc_guid – Unique process identifier assigned to the child process
childproc_md5 – Hash of the child process’ binary (Enterprise EDR)
childproc_name – Filesystem path of the child process’ binary
childproc_sha256 – Hash of the child process’ binary (Endpoint Standard)
childproc_username – User context in which the child process was executed
connection_type – Connection Type
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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)
egress_group_id – Unique identifier for the egress group
egress_group_name – Name of the egress group
external_device_friendly_name – Human-readable external device names
first_event_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
ioc_field – The field the indicator of comprise (IOC) hit contains
ioc_hit – IOC field value or IOC query that matches
ioc_id – Unique identifier of the IOC that generated the watchlist hit
ip_reputation – Range of reputations to accept for the remote IP 0- unknown 1-20 high risk 21-40 suspicious 41-60 moderate 61-80 low risk 81-100 trustworthy There must be two values in this list. The first is the lower end of the range (inclusive) the second is the upper end of the range (inclusive)
is_updated – Boolean that describes whether or not this is the original copy of the alert
k8s_cluster – K8s Cluster name
k8s_kind – K8s Workload kind
k8s_namespace – K8s namespace
k8s_pod_name – Name of the pod within a workload
k8s_policy – Name of the K8s policy
k8s_policy_id – Unique identifier for the K8s policy
k8s_rule – Name of the K8s policy rule
k8s_rule_id – Unique identifier for the K8s policy rule
k8s_workload_name – K8s Workload Name
last_event_timestamp – Timestamp when the last event in the alert occurred
mdr_alert – Is Mdr alert
mdr_alert_notes_present – Customer visible notes at the alert level that were added by a MDR analyst
mdr_determination – Mdr updatable classification of the alert
mdr_threat_notes_present – Customer visible notes at the threat level that were added by a MDR analyst
mdr_workflow – MDR-updatable workflow of the alert
ml_classification_final_verdict – Final verdict of the alert, based on the ML models that were used to make the prediction.
ml_classification_global_prevalence – Categories (low/medium/high) used to describe the prevalence of alerts across all regional organizations.
ml_classification_org_prevalence – Categories (low/medium/high) used to describe the prevalence of alerts within an organization.
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
parent_cmdline – Command line of the parent process
parent_effective_reputation – Effective reputation of the parent process; applied by the sensor when the event occurred
parent_guid – Unique process identifier assigned to the parent process
parent_md5 – MD5 hash of the parent process binary
parent_name – Filesystem path of the parent process binary
parent_pid – Identifier assigned by the operating system to the parent process
parent_reputation – Reputation of the parent process; applied by the Carbon Black Cloud when the event is initially processed
parent_sha256 – SHA-256 hash of the parent process binary
parent_username – User context in which the parent process was executed
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
process_cmdline – Command line executed by the actor process
process_effective_reputation – Effective reputation of the actor hash
process_guid – Guid of the process that has fired the alert (optional)
process_md5 – MD5 hash of the actor process binary
process_name – Process names of an alert
process_pid – PID of the process that has fired the alert (optional)
process_reputation – Reputation of the actor process; applied when event is processed by the Carbon Black Cloud
process_sha256 – SHA-256 hash of the actor process binary
process_username – User context in which the actor process was executed. MacOS - all users for the PID for fork() and exec() transitions. Linux - process user for exec() events, but in a future sensor release can be multi-valued due to setuid().
product_id – IDs of the product that identifies USB devices
product_name – Names of the product that identifies USB devices
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
remote_is_private – Is the remote information private
remote_k8s_kind – Kind of remote workload; set if the remote side is another workload in the same cluster
remote_k8s_namespace – Namespace within the remote workload’s cluster; set if the remote side is another workload in the same cluster
remote_k8s_pod_name – Remote workload pod name; set if the remote side is another workload in the same cluster
remote_k8s_workload_name – Name of the remote workload; set if the remote side is another workload in the same cluster
report_description – Description of the watchlist report associated with the alert
report_id – Report IDs that contained the IOC that caused a hit
report_link – Link of reports that contained the IOC that caused a hit
report_name – Name of the watchlist report
report_tags – Tags associated with the watchlist report
rule_category_id – ID representing the category of the rule_id for certain alert types
rule_config_category – Types of rule configs
rule_id – ID of the rule that triggered an alert; applies to Intrusion Detection System, Host-Based Firewall, TAU Intelligence, and USB Device Control alerts
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
serial_number – Serial numbers of the specific devices
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_name – Name of the threat
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
tms_rule_id – Detection id
ttps – Other potential malicious activities involved in a threat
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
vendor_id – IDs of the vendors who produced the devices
vendor_name – Names of the vendors who produced the devices
watchlists – List of watchlists associated with an alert. Alerts are batched hourly
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class AlertSearchQuery(doc_class, cb)
Bases:
BaseQuery
,QueryBuilderSupportMixin
,IterableQueryMixin
,LegacyAlertSearchQueryCriterionMixin
,CriteriaBuilderSupportMixin
,ExclusionBuilderSupportMixin
Represents a query that is used to locate Alert objects.
Initialize the AlertSearchQuery.
- 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.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- add_time_criteria(key, **kwargs)
Restricts the alerts that this query is performed on to the specified time range for a given key.
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, backend_update_timestamp, or last_update_time
**kwargs (dict) –
Used to specify:
start= for start time
end= for end time
range= for range
excludes= to set this as an exclusion rather than criteria. Defaults to False.
- Returns:
This instance.
- Return type:
Examples
>>> query = api.select(Alert). ... add_time_criteria("detection_timestamp", start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z") >>> second_query = api.select(Alert).add_time_criteria("detection_timestamp", range='-3d') >>> third_query_legacy = api.select(Alert).set_time_range("create_time", range='-3d') >>> exclusions_query = api.add_time_criteria("detection_timestamp", range="-2h", exclude=True)
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- close(closure_reason=None, determination=None, note=None)
Close all alerts matching the given query. The alerts will be left in a CLOSED state after this request.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
- Returns:
The Job object for the bulk workflow action.
- Return type:
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert_query = cb.select(Alert).add_criteria("threat_id", ["19261158DBBF00775959F8AA7F7551A1"]) >>> job = alert_query.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result()
- 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.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.
- Returns:
A list of facet information specified as dicts. error: invalid enum
- Return type:
list
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
ApiError – If the facet field is not valid
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- set_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string alert IDs.
- Returns:
This instance.
- Return type:
- set_alert_notes_present(is_present, exclude=False)
Restricts the alerts that this query is performed on to those with or without notes.
- Parameters:
is_present (bool) – If true, returns alerts that have a note attached
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_blocked_threat_categories(categories)
The field blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_categories(categories)
The field categories was deprecated and not included in v7. This method has been removed.
In Alerts v7, only records with the type THREAT are returned. Records that in v6 had the category MONITORED (Observed) are now Observations See Developer Network Alerts v6 Migration for more details.
- Parameters:
categories (list) – List of categories to be restricted to.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_cluster_names(names)
Restricts the alerts that this query is performed on to the specified Kubernetes cluster names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes cluster names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- 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. In SDK 1.5.0 to align with Alerts v7 API, create_time is set as time_range outside of criteria.
- Deprecated:
Use add_time_criteria(field_name, start, end, range) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_ids (list) – List of integer device IDs.
- Returns:
This instance.
- Return type:
- set_device_locations(locations)
Restricts the alerts that this query is performed on to the specified device locations.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
locations (list) – List of device locations to look for. Valid values are “ONSITE”, “OFFSITE”, and “UNKNOWN”.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_device_names(device_names)
Restricts the alerts that this query is performed on to the specified device names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_names (list) – List of string device names.
- Returns:
This instance.
- Return type:
- set_device_os(device_os)
Restricts the alerts that this query is performed on to the specified device operating systems.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
- Returns:
This instance.
- Return type:
- set_device_os_versions(device_os_versions)
Restricts the alerts that this query is performed on to the specified device operating system versions.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os_versions (list) – List of string operating system versions.
- Returns:
This instance.
- Return type:
- set_device_username(users)
Restricts the alerts that this query is performed on to the specified user names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
users (list) – List of string user names.
- Returns:
This instance.
- Return type:
- set_egress_group_ids(ids)
Restricts the alerts that this query is performed on to the specified egress group IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of egress group names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_external_device_friendly_names(names)
Restricts the alerts that this query is performed on to the specified external device friendly names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of external device IDs to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_group_by(field)
Converts the AlertSearchQuery to a GroupAlertSearchQuery grouped by the argument
- Parameters:
field (string) – The field to group by, defaults to “threat_id”
- Returns:
AlertSearchQuery
Note
Does not preserve sort criterion
- set_group_results(do_group)
The field group_results was deprecated and not included in v7. This method has been removed.
It previously specified whether to group the results of the query. Use the Grouped Alerts Operations #grouped-alerts-operations) instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
do_group (bool) – True to group the results, False to not do so.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_ip_reputations(reputations)
Restricts the alerts that this query is performed on to the specified IP reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reputations (list) – List of IP reputation values to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_kill_chain_statuses(statuses)
The field kill_chain_status was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: statuses (list): List of kill chain statuses to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_legacy_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified legacy alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string legacy alert IDs.
- Returns:
This instance.
- Return type:
- 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:
- set_namespaces(namespaces)
Restricts the alerts that this query is performed on to the specified Kubernetes namespaces.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
namespaces (list) – List of Kubernetes namespaces to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_not_blocked_threat_categories(categories)
The field not_blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_policy_applied(applied_statuses)
Restricts the alerts that this query is performed on to the specified policy status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_policy_ids(policy_ids)
Restricts the alerts that this query is performed on to the specified policy IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_ids (list) – List of integer policy IDs.
- Returns:
This instance.
- Return type:
- set_policy_names(policy_names)
Restricts the alerts that this query is performed on to the specified policy names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_names (list) – List of string policy names.
- Returns:
This instance.
- Return type:
- set_ports(ports)
Restricts the alerts that this query is performed on to the specified netconn_local_ports.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
Note that in SDK 1.5.0, to align with Alerts API v7, the search field was updated from port to netconn_local_port. It is possible to search on either netconn_local_port or netconn_remote_port using the `add_criteria(fieldname, [field values]) method.
- Parameters:
ports (list) – List of netconn_local_ports to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_process_names(process_names)
Restricts the alerts that this query is performed on to the specified process names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
process_names (list) – List of string process names.
- Returns:
This instance.
- Return type:
- set_process_sha256(shas)
Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
shas (list) – List of string process SHA-256 hash values.
- Returns:
This instance.
- Return type:
- set_product_ids(ids)
Restricts the alerts that this query is performed on to the specified product IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of product names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_protocols(protocols)
Restricts the alerts that this query is performed on to the specified protocols.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
protocols (list) – List of protocols to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reason_code(reason)
Restricts the alerts that this query is performed on to the specified reason codes (enum values).
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reason (list) – List of string reason codes to look for.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_remote_domains(domains)
Restricts the alerts that this query is performed on to the specified remote domains.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
addrs (list) – List of remote IP addresses to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_remote_is_private(is_private, exclude=False)
Restricts the alerts that this query is performed on based on matching the remote_is_private field.
This field is only present on CONTAINER_RUNTIME alerts and so filtering will be ignored on other alert types.
- Parameters:
is_private (boolean) – Whether the remote information is private: true or false
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_replica_ids(ids)
Restricts the alerts that this query is performed on to the specified pod names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of pod names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reputations(reps)
Restricts the alerts that this query is performed on to the specified reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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:
- set_rows(rows)
Sets the ‘rows’ query body parameter, determining how many rows of results to request.
- Parameters:
rows (int) – How many rows to request.
- set_rule_ids(ids)
Restricts the alerts that this query is performed on to the specified Kubernetes policy rule IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
In SDK prior to 1.5.0 this was only supported for Container Runtime Alerts so will convert to k8s_rule_id in criteria. In SDK 1.5.0 and later, aligned to Alert v7 API, use add_criteria() should be used for both k8s_rule_id and for other alert types, rule_id.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes policy rule names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_run_states(states)
Restricts the alerts that this query is performed on to the specified run states.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_serial_numbers(serial_numbers)
Restricts the alerts that this query is performed on to the specified serial numbers.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
serial_numbers (list) – List of serial numbers to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_tags(tags)
Restricts the alerts that this query is performed on to the specified tag values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
tags (list) – List of string tag values.
- Returns:
This instance.
- Return type:
- set_target_priorities(priorities)
Restricts the alerts that this query is performed on to the specified target priority values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
- Returns:
This instance.
- Return type:
- set_threat_cause_vectors(vectors)
The field threat_cause_vector was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
- Parameters:
vectors (list) – List of threat cause vectors to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_threat_ids(threats)
Restricts the alerts that this query is performed on to the specified threat ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
threats (list) – List of string threat ID values.
- Returns:
This instance.
- Return type:
- set_threat_notes_present(is_present, exclude=False)
Restricts the alerts that this query is performed on to those with or without threat_notes.
- Parameters:
is_present (bool) – If true, returns alerts that have a note attached to the threat_id
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_time_range(*args, **kwargs)
For v7 Alerts:
Sets the ‘time_range’ query body parameter, determining a time range based on ‘backend_timestamp’.
- Parameters:
*args – not used
**kwargs (dict) –
Used to specify the period to search within
start= either timestamp ISO 8601 strings or datetime objects
end= either timestamp ISO 8601 strings or datetime objects
range= the period on which to execute the result search, ending on the current time.
Range must be in the format “-<quantity><units>” where quantity is an integer, and units is one of:
M: month(s)
w: week(s)
d: day(s)
h: hour(s)
m: minute(s)
s: second(s)
For v6 Alerts (backwards compatibility):
Restricts the alerts that this query is performed on to the specified time range for a given key. Will set the ‘time_range’ as in the v7 usage if key is create_time and set a criteria value for any other valid key.
- Parameters:
key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time or last_update_time. i.e. legacy field names from the Alert v6 API.
**kwargs (dict) –
Used to specify the period to search within
start= either timestamp ISO 8601 strings or datetime objects
end= either timestamp ISO 8601 strings or datetime objects
range= the period on which to execute the result search, ending on the current time.
- Returns:
This instance.
- Return type:
Examples
>>> query_specify_start_and_end = api.select(Alert). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z") >>> query_specify_range = api.select(Alert).set_time_range(range='-3d') >>> query_legacy_use = api.select(Alert).set_time_range("create_time", range='-3d')
- set_types(alerttypes)
Restricts the alerts that this query is performed on to the specified alert type values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”. In SDK 1.5.0, to align with Alert API v7, more alert types are available but the add_criteria method must be used.
- Returns:
This instance.
- Return type:
Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.
- set_vendor_ids(ids)
Restricts the alerts that this query is performed on to the specified vendor IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of vendor names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_watchlist_ids(ids)
Restricts the alerts that this query is performed on to the specified watchlist ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of string watchlist name values.
- Returns:
This instance.
- Return type:
WatchlistAlertSearchQuery
- set_workflows(workflow_vals)
Restricts the alerts that this query is performed on to the specified workflow status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
- Returns:
This instance.
- Return type:
- set_workload_ids(ids)
The field workload_id was deprecated and not included in v7. This method has been removed.
Use workload_name instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
ids (list) – List of workload IDs to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_workload_kinds(kinds)
Restricts the alerts that this query is performed on to the specified workload types.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of workload names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
Example
>>> cb.select(Alert).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(status, closure_reason=None, determination=None, note=None)
Update all alerts matching the given query.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
- Returns:
The Job object for the bulk workflow action.
- Return type:
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert_query = cb.select(Alert).add_criteria("threat_id", ["19261158DBBF00775959F8AA7F7551A1"]) >>> job = alert_query.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result()
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- class CBAnalyticsAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents CB Analytics alerts.
- Parameters:
additional_events_present – Indicator to let API and forwarder users know that they should look up other associated events related to this alert
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
attack_tactic – A tactic from the MITRE ATT&CK framework; defines a reason for an adversary’s action, such as achieving credential access
attack_technique – A technique from the MITRE ATT&CK framework; defines an action an adversary takes to accomplish a goal, such as dumping credentials to achieve credential access
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
blocked_effective_reputation – Effective reputation of the blocked file or process; applied by the sensor at the time the block occurred
blocked_md5 – MD5 hash of the child process binary; for any process terminated by the sensor
blocked_name – Tokenized file path of the files blocked by sensor action
blocked_sha256 – SHA-256 hash of the child process binary; for any process terminated by the sensor
category – Alert category - Monitored vs Threat
childproc_cmdline – Command line for the child process
childproc_effective_reputation – Effective reputation of the child process; applied by the sensor at the time the event occurred
childproc_guid – Unique process identifier assigned to the child process
childproc_md5 – Hash of the child process’ binary (Enterprise EDR)
childproc_name – Filesystem path of the child process’ binary
childproc_sha256 – Hash of the child process’ binary (Endpoint Standard)
childproc_username – User context in which the child process was executed
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
is_updated – Boolean that describes whether or not this is the original copy of the alert
last_event_timestamp – Timestamp when the last event in the alert occurred
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
parent_cmdline – Command line of the parent process
parent_effective_reputation – Effective reputation of the parent process; applied by the sensor when the event occurred
parent_guid – Unique process identifier assigned to the parent process
parent_md5 – MD5 hash of the parent process binary
parent_name – Filesystem path of the parent process binary
parent_pid – Identifier assigned by the operating system to the parent process
parent_reputation – Reputation of the parent process; applied by the Carbon Black Cloud when the event is initially processed
parent_sha256 – SHA-256 hash of the parent process binary
parent_username – User context in which the parent process was executed
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
process_cmdline – Command line executed by the actor process
process_effective_reputation – Effective reputation of the actor hash
process_guid – Guid of the process that has fired the alert (optional)
process_md5 – MD5 hash of the actor process binary
process_name – Process names of an alert
process_pid – PID of the process that has fired the alert (optional)
process_reputation – Reputation of the actor process; applied when event is processed by the Carbon Black Cloud
process_sha256 – SHA-256 hash of the actor process binary
process_username – User context in which the actor process was executed. MacOS - all users for the PID for fork() and exec() transitions. Linux - process user for exec() events, but in a future sensor release can be multi-valued due to setuid().
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
rule_category_id – ID representing the category of the rule_id for certain alert types
rule_id – ID of the rule that triggered an alert; applies to Intrusion Detection System, Host-Based Firewall, TAU Intelligence, and USB Device Control alerts
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
ttps – Other potential malicious activities involved in a threat
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_events(timeout=0, async_mode=False)
Removed in CBC SDK 1.5.0 because Enriched Events are deprecated.
Previously requested enriched events detailed results. Update to use get_observations() instead. See Developer Network Observations Migration for more details.
- 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.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class ContainerRuntimeAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents Container Runtime alerts.
- Parameters:
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
connection_type – Connection Type
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
egress_group_id – Unique identifier for the egress group
egress_group_name – Name of the egress group
first_event_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
ip_reputation – Range of reputations to accept for the remote IP 0- unknown 1-20 high risk 21-40 suspicious 41-60 moderate 61-80 low risk 81-100 trustworthy There must be two values in this list. The first is the lower end of the range (inclusive) the second is the upper end of the range (inclusive)
is_updated – Boolean that describes whether or not this is the original copy of the alert
k8s_cluster – K8s Cluster name
k8s_kind – K8s Workload kind
k8s_namespace – K8s namespace
k8s_pod_name – Name of the pod within a workload
k8s_policy – Name of the K8s policy
k8s_policy_id – Unique identifier for the K8s policy
k8s_rule – Name of the K8s policy rule
k8s_rule_id – Unique identifier for the K8s policy rule
k8s_workload_name – K8s Workload Name
last_event_timestamp – Timestamp when the last event in the alert occurred
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
remote_is_private – Is the remote information private
remote_k8s_kind – Kind of remote workload; set if the remote side is another workload in the same cluster
remote_k8s_namespace – Namespace within the remote workload’s cluster; set if the remote side is another workload in the same cluster
remote_k8s_pod_name – Remote workload pod name; set if the remote side is another workload in the same cluster
remote_k8s_workload_name – Name of the remote workload; set if the remote side is another workload in the same cluster
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class DeviceControlAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents Device Control alerts.
- Parameters:
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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)
external_device_friendly_name – Human-readable external device names
first_event_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
is_updated – Boolean that describes whether or not this is the original copy of the alert
last_event_timestamp – Timestamp when the last event in the alert occurred
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
product_id – IDs of the product that identifies USB devices
product_name – Names of the product that identifies USB devices
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
serial_number – Serial numbers of the specific devices
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
vendor_id – IDs of the vendors who produced the devices
vendor_name – Names of the vendors who produced the devices
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class GroupedAlert(cb, model_unique_id, initial_data=None)
Bases:
PlatformModel
Represents Grouped alerts.
- Parameters:
count – Count of individual alerts that are a part of the group
determination_values – Map of determination (TRUE_POSITIVE, FALSE_POSITIVE, NONE) to the number of individual alerts in the group with that determination. Determinations with no alerts are omitted.
ml_classification_final_verdicts – Map of ML classification (ANOMALOUS, NOT_ANOMALOUS, NO_PREDICTION) to the number of individual alerts in the group with that classification. Classifications with no alerts are omitted.
workflow_states – Map of workflow state (OPEN, IN_PROGRESS, CLOSED) to the number of individual alerts in the group in that state. States with no alerts are omitted.
device_count – Count of unique devices where this alert can be found
first_alert_timestamp – Timestamp of the first (oldest) alert in the group
highest_severity – Highest severity score of all alerts in the group
last_alert_timestamp – Timestamp of the last (newest) alert in the group
most_recent_alert – The most recent alert in the group. Follows the Alerts Schema and returns an
Alert
object. Specific fields vary between alert instancespolicy_applied – APPLIED, when any of the alerts in the group had actions blocked by the sensor due to a policy. NOT_APPLIED otherwise.
tags – List of tags that have been applied to the threat ID
threat_notes_present – Whether there are threat-level notes available on this threat ID
workload_count – Count of unique Kubernetes workloads where this alert can be found
Initialize the Grouped Alert 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(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_alert_search_query()
Returns the Alert Search Query needed to pull all alerts for a given Group Alert.
- Returns:
for all alerts associated with the calling group alert.
- Return type:
Note
Does not preserve sort criterion
- get_alerts()
Returns the all alerts for a given Group Alert.
- Returns:
alerts associated with the calling group alert.
- Return type:
list
- property most_recent_alert_
Returns the most recent alert for a given group alert.
- Returns:
the most recent alert in the Group Alert.
- Return type:
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class GroupedAlertSearchQuery(*args, **kwargs)
Bases:
AlertSearchQuery
Represents a query that is used to group Alert objects by a given field.
Initialize the GroupAlertSearchQuery.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- add_time_criteria(key, **kwargs)
Restricts the alerts that this query is performed on to the specified time range for a given key.
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, backend_update_timestamp, or last_update_time
**kwargs (dict) –
Used to specify:
start= for start time
end= for end time
range= for range
excludes= to set this as an exclusion rather than criteria. Defaults to False.
- Returns:
This instance.
- Return type:
Examples
>>> query = api.select(Alert). ... add_time_criteria("detection_timestamp", start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z") >>> second_query = api.select(Alert).add_time_criteria("detection_timestamp", range='-3d') >>> third_query_legacy = api.select(Alert).set_time_range("create_time", range='-3d') >>> exclusions_query = api.add_time_criteria("detection_timestamp", range="-2h", exclude=True)
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- close(closure_reason=None, determination=None, note=None)
Closing all alerts matching a grouped alert query is not implemented.
Note
Closing all alerts in all groups returned by a
GroupedAlertSearchQuery
can be done by
getting the
AlertSearchQuery
and using close() on it as shown in the following example.Example
>>> alert_query = grouped_alert_query.get_alert_search_query() >>> alert_query.close(closure_reason, determination, note)
- facets(fieldlist, max_rows=0, filter_values=False)
Return information about the facets for this alert by search, using the defined criteria.
- Parameters:
fieldlist (list) – List of facet field names.
max_rows (int) – The maximum number of rows to return. 0 means return all rows.
filter_values (boolean) – A flag to indicate whether any filters on a term should be applied to facet
false (calculation. When) –
- Returns:
A list of facet information specified as dicts. error: invalid enum
- Return type:
list
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
ApiError – If the facet field is not valid
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- get_alert_search_query()
Converts the GroupedAlertSearchQuery into a nongrouped AlertSearchQuery
Returns: AlertSearchQuery
Note: Does not preserve sort criterion
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- set_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string alert IDs.
- Returns:
This instance.
- Return type:
- set_alert_notes_present(is_present, exclude=False)
Restricts the alerts that this query is performed on to those with or without notes.
- Parameters:
is_present (bool) – If true, returns alerts that have a note attached
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_blocked_threat_categories(categories)
The field blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_categories(categories)
The field categories was deprecated and not included in v7. This method has been removed.
In Alerts v7, only records with the type THREAT are returned. Records that in v6 had the category MONITORED (Observed) are now Observations See Developer Network Alerts v6 Migration for more details.
- Parameters:
categories (list) – List of categories to be restricted to.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_cluster_names(names)
Restricts the alerts that this query is performed on to the specified Kubernetes cluster names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes cluster names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- 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. In SDK 1.5.0 to align with Alerts v7 API, create_time is set as time_range outside of criteria.
- Deprecated:
Use add_time_criteria(field_name, start, end, range) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_ids (list) – List of integer device IDs.
- Returns:
This instance.
- Return type:
- set_device_locations(locations)
Restricts the alerts that this query is performed on to the specified device locations.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
locations (list) – List of device locations to look for. Valid values are “ONSITE”, “OFFSITE”, and “UNKNOWN”.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_device_names(device_names)
Restricts the alerts that this query is performed on to the specified device names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_names (list) – List of string device names.
- Returns:
This instance.
- Return type:
- set_device_os(device_os)
Restricts the alerts that this query is performed on to the specified device operating systems.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
- Returns:
This instance.
- Return type:
- set_device_os_versions(device_os_versions)
Restricts the alerts that this query is performed on to the specified device operating system versions.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os_versions (list) – List of string operating system versions.
- Returns:
This instance.
- Return type:
- set_device_username(users)
Restricts the alerts that this query is performed on to the specified user names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
users (list) – List of string user names.
- Returns:
This instance.
- Return type:
- set_egress_group_ids(ids)
Restricts the alerts that this query is performed on to the specified egress group IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of egress group names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_external_device_friendly_names(names)
Restricts the alerts that this query is performed on to the specified external device friendly names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of external device IDs to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_group_by(field)
Sets the ‘group_by’ query body parameter, determining which field to group the alerts by.
- Parameters:
field (string) – The field to group by
- set_group_results(do_group)
The field group_results was deprecated and not included in v7. This method has been removed.
It previously specified whether to group the results of the query. Use the Grouped Alerts Operations #grouped-alerts-operations) instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
do_group (bool) – True to group the results, False to not do so.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_ip_reputations(reputations)
Restricts the alerts that this query is performed on to the specified IP reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reputations (list) – List of IP reputation values to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_kill_chain_statuses(statuses)
The field kill_chain_status was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: statuses (list): List of kill chain statuses to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_legacy_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified legacy alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string legacy alert IDs.
- Returns:
This instance.
- Return type:
- 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:
- set_namespaces(namespaces)
Restricts the alerts that this query is performed on to the specified Kubernetes namespaces.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
namespaces (list) – List of Kubernetes namespaces to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_not_blocked_threat_categories(categories)
The field not_blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_policy_applied(applied_statuses)
Restricts the alerts that this query is performed on to the specified policy status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_policy_ids(policy_ids)
Restricts the alerts that this query is performed on to the specified policy IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_ids (list) – List of integer policy IDs.
- Returns:
This instance.
- Return type:
- set_policy_names(policy_names)
Restricts the alerts that this query is performed on to the specified policy names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_names (list) – List of string policy names.
- Returns:
This instance.
- Return type:
- set_ports(ports)
Restricts the alerts that this query is performed on to the specified netconn_local_ports.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
Note that in SDK 1.5.0, to align with Alerts API v7, the search field was updated from port to netconn_local_port. It is possible to search on either netconn_local_port or netconn_remote_port using the `add_criteria(fieldname, [field values]) method.
- Parameters:
ports (list) – List of netconn_local_ports to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_process_names(process_names)
Restricts the alerts that this query is performed on to the specified process names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
process_names (list) – List of string process names.
- Returns:
This instance.
- Return type:
- set_process_sha256(shas)
Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
shas (list) – List of string process SHA-256 hash values.
- Returns:
This instance.
- Return type:
- set_product_ids(ids)
Restricts the alerts that this query is performed on to the specified product IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of product names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_protocols(protocols)
Restricts the alerts that this query is performed on to the specified protocols.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
protocols (list) – List of protocols to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reason_code(reason)
Restricts the alerts that this query is performed on to the specified reason codes (enum values).
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reason (list) – List of string reason codes to look for.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_remote_domains(domains)
Restricts the alerts that this query is performed on to the specified remote domains.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
addrs (list) – List of remote IP addresses to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_remote_is_private(is_private, exclude=False)
Restricts the alerts that this query is performed on based on matching the remote_is_private field.
This field is only present on CONTAINER_RUNTIME alerts and so filtering will be ignored on other alert types.
- Parameters:
is_private (boolean) – Whether the remote information is private: true or false
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_replica_ids(ids)
Restricts the alerts that this query is performed on to the specified pod names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of pod names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reputations(reps)
Restricts the alerts that this query is performed on to the specified reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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:
- set_rows(rows)
Sets the ‘rows’ query body parameter, determining how many rows of results to request.
- Parameters:
rows (int) – How many rows to request.
- set_rule_ids(ids)
Restricts the alerts that this query is performed on to the specified Kubernetes policy rule IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
In SDK prior to 1.5.0 this was only supported for Container Runtime Alerts so will convert to k8s_rule_id in criteria. In SDK 1.5.0 and later, aligned to Alert v7 API, use add_criteria() should be used for both k8s_rule_id and for other alert types, rule_id.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes policy rule names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_run_states(states)
Restricts the alerts that this query is performed on to the specified run states.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_serial_numbers(serial_numbers)
Restricts the alerts that this query is performed on to the specified serial numbers.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
serial_numbers (list) – List of serial numbers to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_tags(tags)
Restricts the alerts that this query is performed on to the specified tag values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
tags (list) – List of string tag values.
- Returns:
This instance.
- Return type:
- set_target_priorities(priorities)
Restricts the alerts that this query is performed on to the specified target priority values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
- Returns:
This instance.
- Return type:
- set_threat_cause_vectors(vectors)
The field threat_cause_vector was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
- Parameters:
vectors (list) – List of threat cause vectors to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_threat_ids(threats)
Restricts the alerts that this query is performed on to the specified threat ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
threats (list) – List of string threat ID values.
- Returns:
This instance.
- Return type:
- set_threat_notes_present(is_present, exclude=False)
Restricts the alerts that this query is performed on to those with or without threat_notes.
- Parameters:
is_present (bool) – If true, returns alerts that have a note attached to the threat_id
exclude (bool) – If true, will set is_present in the exclusions. Otherwise adds to criteria
- Returns:
This instance.
- Return type:
- set_time_range(*args, **kwargs)
For v7 Alerts:
Sets the ‘time_range’ query body parameter, determining a time range based on ‘backend_timestamp’.
- Parameters:
*args – not used
**kwargs (dict) –
Used to specify the period to search within
start= either timestamp ISO 8601 strings or datetime objects
end= either timestamp ISO 8601 strings or datetime objects
range= the period on which to execute the result search, ending on the current time.
Range must be in the format “-<quantity><units>” where quantity is an integer, and units is one of:
M: month(s)
w: week(s)
d: day(s)
h: hour(s)
m: minute(s)
s: second(s)
For v6 Alerts (backwards compatibility):
Restricts the alerts that this query is performed on to the specified time range for a given key. Will set the ‘time_range’ as in the v7 usage if key is create_time and set a criteria value for any other valid key.
- Parameters:
key (str) – The key to use for criteria one of create_time, first_event_time, last_event_time or last_update_time. i.e. legacy field names from the Alert v6 API.
**kwargs (dict) –
Used to specify the period to search within
start= either timestamp ISO 8601 strings or datetime objects
end= either timestamp ISO 8601 strings or datetime objects
range= the period on which to execute the result search, ending on the current time.
- Returns:
This instance.
- Return type:
Examples
>>> query_specify_start_and_end = api.select(Alert). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z") >>> query_specify_range = api.select(Alert).set_time_range(range='-3d') >>> query_legacy_use = api.select(Alert).set_time_range("create_time", range='-3d')
- set_types(alerttypes)
Restricts the alerts that this query is performed on to the specified alert type values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”. In SDK 1.5.0, to align with Alert API v7, more alert types are available but the add_criteria method must be used.
- Returns:
This instance.
- Return type:
Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.
- set_vendor_ids(ids)
Restricts the alerts that this query is performed on to the specified vendor IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of vendor names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_watchlist_ids(ids)
Restricts the alerts that this query is performed on to the specified watchlist ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of string watchlist name values.
- Returns:
This instance.
- Return type:
WatchlistAlertSearchQuery
- set_workflows(workflow_vals)
Restricts the alerts that this query is performed on to the specified workflow status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
- Returns:
This instance.
- Return type:
- set_workload_ids(ids)
The field workload_id was deprecated and not included in v7. This method has been removed.
Use workload_name instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
ids (list) – List of workload IDs to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_workload_kinds(kinds)
Restricts the alerts that this query is performed on to the specified workload types.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of workload names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
Example
>>> cb.select(Alert).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(status, closure_reason=None, determination=None, note=None)
Updating all alerts matching a grouped alert query is not implemented.
Note
Updating all alerts in all groups returned by a
GroupedAlertSearchQuery
can be done by
getting the
AlertSearchQuery
and using update() on it as shown in the following example.Example
>>> alert_query = grouped_alert_query.get_alert_search_query() >>> job = alert_query.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result()
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- class HostBasedFirewallAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents Host Based Firewall alerts.
- Parameters:
additional_events_present – Indicator to let API and forwarder users know that they should look up other associated events related to this alert
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
blocked_effective_reputation – Effective reputation of the blocked file or process; applied by the sensor at the time the block occurred
blocked_md5 – MD5 hash of the child process binary; for any process terminated by the sensor
blocked_name – Tokenized file path of the files blocked by sensor action
blocked_sha256 – SHA-256 hash of the child process binary; for any process terminated by the sensor
category – Alert category - Monitored vs Threat
childproc_cmdline – Command line for the child process
childproc_effective_reputation – Effective reputation of the child process; applied by the sensor at the time the event occurred
childproc_guid – Unique process identifier assigned to the child process
childproc_md5 – Hash of the child process’ binary (Enterprise EDR)
childproc_name – Filesystem path of the child process’ binary
childproc_sha256 – Hash of the child process’ binary (Endpoint Standard)
childproc_username – User context in which the child process was executed
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
is_updated – Boolean that describes whether or not this is the original copy of the alert
last_event_timestamp – Timestamp when the last event in the alert occurred
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
parent_cmdline – Command line of the parent process
parent_effective_reputation – Effective reputation of the parent process; applied by the sensor when the event occurred
parent_guid – Unique process identifier assigned to the parent process
parent_md5 – MD5 hash of the parent process binary
parent_name – Filesystem path of the parent process binary
parent_pid – Identifier assigned by the operating system to the parent process
parent_reputation – Reputation of the parent process; applied by the Carbon Black Cloud when the event is initially processed
parent_sha256 – SHA-256 hash of the parent process binary
parent_username – User context in which the parent process was executed
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
process_cmdline – Command line executed by the actor process
process_effective_reputation – Effective reputation of the actor hash
process_guid – Guid of the process that has fired the alert (optional)
process_md5 – MD5 hash of the actor process binary
process_name – Process names of an alert
process_pid – PID of the process that has fired the alert (optional)
process_reputation – Reputation of the actor process; applied when event is processed by the Carbon Black Cloud
process_sha256 – SHA-256 hash of the actor process binary
process_username – User context in which the actor process was executed. MacOS - all users for the PID for fork() and exec() transitions. Linux - process user for exec() events, but in a future sensor release can be multi-valued due to setuid().
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
rule_category_id – ID representing the category of the rule_id for certain alert types
rule_id – ID of the rule that triggered an alert; applies to Intrusion Detection System, Host-Based Firewall, TAU Intelligence, and USB Device Control alerts
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class IntrusionDetectionSystemAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents Intrusion Detection System alerts.
- Parameters:
additional_events_present – Indicator to let API and forwarder users know that they should look up other associated events related to this alert
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
attack_tactic – A tactic from the MITRE ATT&CK framework; defines a reason for an adversary’s action, such as achieving credential access
attack_technique – A technique from the MITRE ATT&CK framework; defines an action an adversary takes to accomplish a goal, such as dumping credentials to achieve credential access
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
blocked_effective_reputation – Effective reputation of the blocked file or process; applied by the sensor at the time the block occurred
blocked_md5 – MD5 hash of the child process binary; for any process terminated by the sensor
blocked_name – Tokenized file path of the files blocked by sensor action
blocked_sha256 – SHA-256 hash of the child process binary; for any process terminated by the sensor
category – Alert category - Monitored vs Threat
childproc_cmdline – Command line for the child process
childproc_effective_reputation – Effective reputation of the child process; applied by the sensor at the time the event occurred
childproc_guid – Unique process identifier assigned to the child process
childproc_md5 – Hash of the child process’ binary (Enterprise EDR)
childproc_name – Filesystem path of the child process’ binary
childproc_sha256 – Hash of the child process’ binary (Endpoint Standard)
childproc_username – User context in which the child process was executed
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
is_updated – Boolean that describes whether or not this is the original copy of the alert
last_event_timestamp – Timestamp when the last event in the alert occurred
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
parent_cmdline – Command line of the parent process
parent_effective_reputation – Effective reputation of the parent process; applied by the sensor when the event occurred
parent_guid – Unique process identifier assigned to the parent process
parent_md5 – MD5 hash of the parent process binary
parent_name – Filesystem path of the parent process binary
parent_pid – Identifier assigned by the operating system to the parent process
parent_reputation – Reputation of the parent process; applied by the Carbon Black Cloud when the event is initially processed
parent_sha256 – SHA-256 hash of the parent process binary
parent_username – User context in which the parent process was executed
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
process_cmdline – Command line executed by the actor process
process_effective_reputation – Effective reputation of the actor hash
process_guid – Guid of the process that has fired the alert (optional)
process_md5 – MD5 hash of the actor process binary
process_name – Process names of an alert
process_pid – PID of the process that has fired the alert (optional)
process_reputation – Reputation of the actor process; applied when event is processed by the Carbon Black Cloud
process_sha256 – SHA-256 hash of the actor process binary
process_username – User context in which the actor process was executed. MacOS - all users for the PID for fork() and exec() transitions. Linux - process user for exec() events, but in a future sensor release can be multi-valued due to setuid().
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
rule_category_id – ID representing the category of the rule_id for certain alert types
rule_id – ID of the rule that triggered an alert; applies to Intrusion Detection System, Host-Based Firewall, TAU Intelligence, and USB Device Control alerts
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_name – Name of the threat
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
tms_rule_id – Detection id
ttps – Other potential malicious activities involved in a threat
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_network_threat_metadata()
The NetworkThreatMetadata associated with this IDS alert if it exists.
Example
>>> alert_threat_metadata = ids_alert.get_network_threat_metadata()
- Returns:
The NetworkThreatMetadata associated with this IDS alert.
- Return type:
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
- class WatchlistAlert(cb, model_unique_id, initial_data=None)
Bases:
Alert
Represents watch list alerts.
- Parameters:
additional_events_present – Indicator to let API and forwarder users know that they should look up other associated events related to this alert
alert_notes_present – True if notes are present on the alert ID. False if notes are not present.
alert_url – Link to the alerts page for this alert. Does not vary by alert type
attack_tactic – A tactic from the MITRE ATT&CK framework; defines a reason for an adversary’s action, such as achieving credential access
attack_technique – A technique from the MITRE ATT&CK framework; defines an action an adversary takes to accomplish a goal, such as dumping credentials to achieve credential access
backend_timestamp – Timestamp when the Carbon Black Cloud processed and enabled the alert for searching. Corresponds to the Created column on the Alerts page.
backend_update_timestamp – Timestamp when the Carbon Black Cloud initiated and processed an update to an alert. Corresponds to the Updated column on the Alerts page. Note that changes made by users do not change this date; those changes are reflected on user_update_timestamp
blocked_effective_reputation – Effective reputation of the blocked file or process; applied by the sensor at the time the block occurred
blocked_md5 – MD5 hash of the child process binary; for any process terminated by the sensor
blocked_name – Tokenized file path of the files blocked by sensor action
blocked_sha256 – SHA-256 hash of the child process binary; for any process terminated by the sensor
category – Alert category - Monitored vs Threat
childproc_cmdline – Command line for the child process
childproc_effective_reputation – Effective reputation of the child process; applied by the sensor at the time the event occurred
childproc_guid – Unique process identifier assigned to the child process
childproc_md5 – Hash of the child process’ binary (Enterprise EDR)
childproc_name – Filesystem path of the child process’ binary
childproc_sha256 – Hash of the child process’ binary (Endpoint Standard)
childproc_username – User context in which the child process was executed
detection_timestamp – For sensor-sent alerts, this is the time of the event on the sensor. For alerts generated on the backend, this is the time the backend system triggered the alert.
determination – User-updatable determination of the alert
device_external_ip – IP address of the endpoint according to the Carbon Black Cloud; can differ from device_internal_ip due to network proxy or NAT; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_id – ID of devices
device_internal_ip – IP address of the endpoint reported by the sensor; either IPv4 (dotted decimal notation) or IPv6 (proprietary format)
device_location – Whether the device was on or off premises when the alert started, based on the current IP address and the device’s registered DNS domain suffix
device_name – Device name
device_os – Device Operating Systems
device_os_version – The operating system and version of the endpoint. Requires Windows CBC sensor version 3.5 or later.
device_policy – Device policy
device_policy_id – Device policy id
device_target_value – Target value assigned to the device, set from the policy
device_uem_id – Device correlation with WS1/EUC, required for our Workspace ONE Intelligence integration to function
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_timestamp – Timestamp when the first event in the alert occurred
id – Unique IDs of alerts
ioc_field – The field the indicator of comprise (IOC) hit contains
ioc_hit – IOC field value or IOC query that matches
ioc_id – Unique identifier of the IOC that generated the watchlist hit
is_updated – Boolean that describes whether or not this is the original copy of the alert
last_event_timestamp – Timestamp when the last event in the alert occurred
ml_classification_final_verdict – Final verdict of the alert, based on the ML models that were used to make the prediction.
ml_classification_global_prevalence – Categories (low/medium/high) used to describe the prevalence of alerts across all regional organizations.
ml_classification_org_prevalence – Categories (low/medium/high) used to describe the prevalence of alerts within an organization.
netconn_local_ip – IP address of the remote side of the network connection; stored as dotted decimal
netconn_local_ipv4 – IPv4 address of the local side of the network connection; stored as a dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_ipv6 – IPv6 address of the local side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_local_port – TCP or UDP port used by the local side of the network connection
netconn_protocol – Network protocol of the network connection
netconn_remote_domain – Domain name (FQDN) associated with the remote end of the network connection, if available
netconn_remote_ip – IP address of the local side of the network connection; stored as dotted decimal
netconn_remote_ipv4 – IPv4 address of the remote side of the network connection; stored as dotted decimal. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_ipv6 – IPv6 address of the remote side of the network connection; stored as a string without octet-separating colon characters. Only one of ipv4 and ipv6 fields will be populated.
netconn_remote_port – TCP or UDP port used by the remote side of the network connection; same as netconn_port and event_network_remote_port
org_key – Unique alphanumeric string that identifies your organization in the Carbon Black Cloud
parent_cmdline – Command line of the parent process
parent_effective_reputation – Effective reputation of the parent process; applied by the sensor when the event occurred
parent_guid – Unique process identifier assigned to the parent process
parent_md5 – MD5 hash of the parent process binary
parent_name – Filesystem path of the parent process binary
parent_pid – Identifier assigned by the operating system to the parent process
parent_reputation – Reputation of the parent process; applied by the Carbon Black Cloud when the event is initially processed
parent_sha256 – SHA-256 hash of the parent process binary
parent_username – User context in which the parent process was executed
policy_applied – Indicates whether or not a policy has been applied to any event associated with this alert
primary_event_id – ID of the primary event in the alert
process_cmdline – Command line executed by the actor process
process_effective_reputation – Effective reputation of the actor hash
process_guid – Guid of the process that has fired the alert (optional)
process_md5 – MD5 hash of the actor process binary
process_name – Process names of an alert
process_pid – PID of the process that has fired the alert (optional)
process_reputation – Reputation of the actor process; applied when event is processed by the Carbon Black Cloud
process_sha256 – SHA-256 hash of the actor process binary
process_username – User context in which the actor process was executed. MacOS - all users for the PID for fork() and exec() transitions. Linux - process user for exec() events, but in a future sensor release can be multi-valued due to setuid().
reason – A spoken language written explanation of the what and why the alert occurred and any action taken, usually consisting of 1 to 3 sentences.
reason_code – A unique short-hand code or GUID identifying the particular alert reason
report_description – Description of the watchlist report associated with the alert
report_id – Report IDs that contained the IOC that caused a hit
report_link – Link of reports that contained the IOC that caused a hit
report_name – Name of the watchlist report
report_tags – Tags associated with the watchlist report
run_state – Whether the threat in the alert actually ran
sensor_action – Actions taken by the sensor, according to the rules of a policy
severity – integer representation of the impact of alert if true positive
tags – Tags added to the threat ID of the alert
threat_id – ID assigned to a group of alerts with common criteria, based on alert type
threat_notes_present – True if notes are present on the threat ID. False if notes are not present.
ttps – Other potential malicious activities involved in a threat
type – Type of alert generated
user_update_timestamp – Timestamp of the last property of an alert changed by a user, such as the alert workflow or determination
watchlists – List of watchlists associated with an alert. Alerts are batched hourly
workflow – Current workflow state of an alert. The workflow represents the flow from OPEN to IN_PROGRESS to CLOSED and captures who moved the alert into the current state. The history of these state transitions is available via the alert history route.
Initialize the Alert 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, threat_note=False, initial_data=None)
Bases:
PlatformModel
Represents a note within an alert.
- Parameters:
author – User who created the note
create_timestamp – Time the note was created
last_update_timestamp – Time the note was created
id – Unique ID for this note
note – Note contents
parent_id – ID for this note of this notes parent if is a thread
Initialize the Note object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
alert (Alert) – The alert where the note is saved.
model_unique_id (str) – ID of the note represented.
threat_note (bool) – Whether the note is an Alert or Threat note
initial_data (dict) – Initial data used to populate the note.
- delete()
Deletes a note from an alert.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- add_threat_tags(tags)
Adds tags to the threat
- Required Permissions:
org.alerts.tags (CREATE)
- Parameters:
tags (list[str]) – List of tags to add to the threat
- Raises:
ApiError – If tags is not a list of strings
- Returns:
The list of current tags
- Return type:
(list[str])
- close(closure_reason=None, determination=None, note=None)
Closes this alert.
- Parameters:
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.close("RESOLVED", "FALSE_POSITIVE", "Normal behavior") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- create_note(note, threat_note=False)
Creates a new note.
- Parameters:
note (str) – Note content to add
threat_note (bool) – Whether to add the note to the Alert or Threat
- delete_threat_tag(tag)
Delete a threat tag
- Required Permissions:
org.alerts.tags (DELETE)
- Parameters:
tag (str) – The tag to delete
- Returns:
The list of current tags
- Return type:
(list[str])
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the alert and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- dismiss_threat(remediation=None, comment=None)
Dismisses all future alerts assigned to the threat_id.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to dismiss all past and current open alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).close(...)
- get(item, default_val=None)
Return an attribute of this object.
- Parameters:
item (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_history(threat=False)
Get the actions taken on an Alert such as Notes added and workflow state changes.
- Parameters:
threat (bool) – Whether to return the Alert or Threat history
- Returns:
The dicts of each determination, note or workflow change
- Return type:
list
- get_observations(timeout=0)
Requests observations that are associated with the Alert.
Uses Observations bulk get details.
- Returns:
Observations associated with the alert
- 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.
- 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:
- get_threat_tags()
Gets the threat’s tags
- Required Permissions:
org.alerts.tags (READ)
- Returns:
The list of current tags
- Return type:
(list[str])
- get_watchlist_objects()
Returns the list of associated watchlist objects for the associated watchlist alert.
Example
>>> watchlist_alert = cb.select(Alert, "f643d11f-59ab-478f-92c3-4198ca9b8230") >>> watchlist_objects = watchlist_alert.get_watchlist_objects()
- Returns:
A list of Watchlist objects.
- Return type:
list[Watchlist]
- notes_(threat_note=False)
Retrieves all notes for an alert.
- Parameters:
threat_note (bool) – Whether to return the Alert notes or Threat notes
- refresh()
Reload this object from the server.
- 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
- to_json(version='v7')
Return a json object of the response.
- Parameters:
version (str) – version of json to return. Either v6 or v7. DEFAULT v7
- Returns:
The returned attribute value.
- Return type:
Any
- update(status, closure_reason=None, determination=None, note=None)
Update the Alert with optional closure_reason, determination, note, or status.
- Parameters:
status (str) – The status to set for this alert, either “OPEN”, “IN_PROGRESS”, or “CLOSED”.
closure_reason (str) – the closure reason for this alert, either “NO_REASON”, “RESOLVED”, “RESOLVED_BENIGN_KNOWN_GOOD”, “DUPLICATE_CLEANUP”, “OTHER”
determination (str) – The determination status to set for the alert, either “TRUE_POSITIVE”, “FALSE_POSITIVE”, or “NONE”
note (str) – The comment to set for the alert.
Note
This is an asynchronus call that returns a Job. If you want to wait and block on the results you can call await_completion() to get a Futre then result() on the future object to wait for completion and get the results.
Example
>>> alert = cb.select(Alert, "708d7dbf-2020-42d4-9cbc-0cddd0ffa31a") >>> job = alert.update("IN_PROGESS", "NO_REASON", "NONE", "Starting Investigation") >>> completed_job = job.await_completion().result() >>> alert.refresh()
- Returns:
The Job object for the alert workflow action.
- Return type:
- update_threat(remediation=None, comment=None)
Updates all future alerts assigned to the threat_id to the OPEN state.
- Parameters:
remediation (str) – The remediation status to set for the alert.
comment (str) – The comment to set for the alert.
Note
- If you want to update all past and current alerts associated to the threat use the following:
>>> cb.select(Alert).add_criteria("threat_id", [alert.threat_id]).update(...)
- property workflow_
Returns the workflow associated with this alert.
- Returns:
The workflow associated with this alert.
- Return type:
dict
Asset Groups Module
The model and query classes for referencing asset groups.
An asset group represents a group of devices (endpoints, VM workloads, and/or VDIs) that can have a single policy applied to it so the protections of all similar assets are synchronized with one another. Policies carry a “position” value as one of their attributes, so that, between the policy attached directly to the device, and the policies attached to any asset groups the device is a member of, the one with the highest “position” is the one that applies to that device. Devices may be added to an asset group either explicitly, or implicitly by specifying a query on the asset group, such that all devices matching that search criteria are considered part of the asset group.
Typical usage example:
# assume "cb" is an instance of CBCloudAPI
query = cb.select(AssetGroup).where('name:"HQ Devices"')
group = query.first()
- class AssetGroup(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
MutableBaseModel
Represents an asset group within the current organization in the Carbon Black Cloud.
AssetGroup
objects are typically located via a search (usingAssetGroupQuery
) before they can be operatedon. They may also be created on the Carbon Black Cloud by using the
create_group()
class method.
- Parameters:
id – The asset group identifier.
name – The asset group name.
description – The asset group description.
org_key – The organization key of the owning organization.
status – Status of the group.
member_type – The type of objects this asset group contains.
discovered – Whether this group has been discovered.
create_time – Date and time the group was created.
update_time – Date and time the group was last updated.
member_count – Number of members in this group.
policy_id – ID of the policy associated with this group.
policy_name – Name of the policy associated with this group.
query – Search query used to determine which assets are included in the group membership.
Initialize the
AssetGroup
object.- Required Permissions:
group-management(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.
- add_members(members)
Adds additional members to this asset group.
- Required Permissions:
group-management(CREATE)
- Parameters:
members (int, Device, or list) – The members to be added to the group. This may be an integer device ID, a
Device
object, or a list of either integers orDevice
objects.
- classmethod create_group(cb, name, description=None, policy_id=None, query=None)
Create a new asset group.
- Required Permissions:
group-management(CREATE)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
name (str) – Name for the new asset group.
description (str) – Description for the new asset group. Default is
None
.policy_id (int) – ID of the policy to be associated with this asset group. Default is
None
.query (str) – Query string to be used to dynamically populate this group. Default is
None
, which means devices _must_ be manually assigned to the group.
- Returns:
The new asset group.
- Return type:
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- classmethod get_all_groups(cb)
Retrieve all asset groups in the organization.
- Required Permissions:
group-management(READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
- Returns:
List of
AssetGroup
objects corresponding to the asset groups in the organization.- Return type:
list[AssetGroup]
- get_statistics()
For this group, return statistics about its group membership.
The statistics include how many of the group’s members belong to other groups, and how many members belong to groups without policy association.
See this page for more details on the structure of the return value from this method.
- Required Permissions:
group-management(READ)
- Returns:
- A dict with two elements. The “intersections” element contains elements detailing which groups share
members with this group, and which members they are. The “unassigned_properties” element contains elements showing which members belong to groups without policy association.
- Return type:
dict
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- list_member_ids(rows=20, start=0)
Gets a list of all member IDs in the group, optionally constrained by membership type.
- Required Permissions:
group-management(READ)
- Parameters:
rows (int) – Maximum number of rows to retrieve from the server. The function may return fewer member IDs if filtering is applied to the output. Default is 20.
start (int) – Starting row to retrieve from the server; used to implement pagination. Default is 0.
- Returns:
- List of dictionaries that contain the integer element
external_member_id
for the device ID, the boolean element
dynamic
which isTrue
if the group member is there due to the group’s dynamic query, and the boolean elementmanual
which isTrue
if the group member was manually added. (It is possible for bothdynamic
andmanual
to beTrue
.)
- List of dictionaries that contain the integer element
- Return type:
list[dict]
- list_members(rows=20, start=0, membership='ALL')
Gets a list of all member devices in the group, optionally constrained by membership type.
- Required Permissions:
group-management(READ), devices(READ)
- Parameters:
rows (int) – Maximum number of rows to retrieve from the server. The function may return fewer member IDs if filtering is applied to the output. Default is 20.
start (int) – Starting row to retrieve from the server; used to implement pagination. Default is 0.
membership (str) – Can restrict the types of members that are returned by this method. Values are “ALL” to return all members, “DYNAMIC” to return only members that were added via the asset group query, or “MANUAL” to return only manually-added members. Default is “ALL”.
- Returns:
List of
Device
objects comprising the membership of the group.``- Return type:
list[Device]
- preview_add_members(devices)
Previews changes to the effective policies for devices which result from adding them to this asset group.
- Required Permissions:
org.policies (READ)
- Parameters:
devices (list) – The devices which will be added to this asset group. Each entry in this list is either an integer device ID or a
Device
object.- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_add_members_to_groups(cb, members, groups)
Previews changes to the effective policies for devices which result from adding them to asset groups.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
members (list) – The devices which will be added to new asset groups. Each entry in this list is either an integer device ID or a
Device
object.groups (list) – The asset groups to which the devices will be added. Each entry in this list is either a string asset group ID or an
AssetGroup
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_create_asset_group(cb, policy_id, query)
Previews changes to the effective policies for devices which result from creating a new asset group.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
policy_id (int) – The ID of the policy to be added to the new asset group.
query (str) – The query string to be used for the new asset group.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- preview_delete()
Previews changes to the effective policies for devices which result from this asset group being deleted.
- Required Permissions:
org.policies (READ)
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_delete_asset_groups(cb, groups)
Previews changes to the effective policies for devices which result from deleting asset groups.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
groups (list) – The asset groups which will be deleted. Each entry in this list is either a string asset group ID or an
AssetGroup
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- preview_remove_members(devices)
Previews changes to the effective policies for devices which result from removing them from this asset group.
- Required Permissions:
org.policies (READ)
- Parameters:
devices (list) – The devices which will be removed from this asset group. Each entry in this list is either an integer device ID or a
Device
object.- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_remove_members_from_groups(cb, members, groups)
Previews changes to the effective policies for devices which result from removing them from asset groups.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
members (list) – The devices which will be removed from asset groups. Each entry in this list is either an integer device ID or a
Device
object.groups (list) – The asset groups from which the devices will be removed. Each entry in this list is either a string asset group ID or an
AssetGroup
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- preview_save()
Previews changes to the effective policies for devices which result from unsaved changes to this asset group.
- Required Permissions:
org.policies (READ)
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_update_asset_groups(cb, groups, policy_id=None, query=None, remove_policy_id=False, remove_query=False)
Previews changes to the effective policies for devices which result from changes to asset groups.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
groups (list) – The asset groups which will be updated. Each entry in this list is either a string asset group ID or an
AssetGroup
object.policy_id (int) – If this is not
None
andremove_policy_id
isFalse
, contains the ID of the policy to be assigned to the specified groups. Default isNone
.query (str) – If this is not
None
andremove_query
isFalse
, contains the new query string to be assigned to the specified groups. Default isNone
.remove_policy_id (bool) – If this is
True
, indicates that the specified groups will have their policy ID removed entirely. Default isFalse
.remove_query (bool) – If this is
True
, indicates that the specified groups will have their query strings removed entirely. Default isFalse
.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- refresh()
Reload this object from the server.
- remove_members(members)
Removes members from this asset group.
- Required Permissions:
group-management(DELETE)
- Parameters:
members (int, Device, or list) – The members to be removed from the group. This may be an integer device ID, a
Device
object, or a list of either integers orDevice
objects.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- swagger_meta_file
The valid values for the ‘filter’ parameter to list_members().
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- class AssetGroupQuery(doc_class, cb)
Bases:
BaseQuery
,QueryBuilderSupportMixin
,IterableQueryMixin
,CriteriaBuilderSupportMixin
,AsyncQueryMixin
Query object that is used to locate
AssetGroup
objects.The
AssetGroupQuery
is constructed via SDK functions like theselect()
method onCBCloudAPI
. The user would then add a query and/or criteria to it before iterating over the results.The following criteria are supported on
AssetGroupQuery
via the standardadd_criteria()
method:discovered: bool
- Whether the asset group has been discovered or not.name: str
- The asset group name to be matched.policy_id: int
- The policy ID to be matched, expressed as an integer.group_id: str
- The asset group ID to be matched, expressed as a GUID.
Initialize the
AssetGroupQuery
.- 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.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- set_rows(rows)
Sets the number of query rows to fetch in each batch from the server.
- Parameters:
rows (int) – The number of rows to be fetched fromt hes erver at a time. Default is 100.
- Returns:
This instance.
- Return type:
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
Example
>>> cb.select(AssetGroup).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_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
Audit Module
Model and Query Classes for Platform Auditing
- class AuditLog(cb, model_unique_id, initial_data=None)
Bases:
UnrefreshableModel
Model class which represents audit log events. Mostly for future implementation.
Creation of AuditLog objects is not yet implemented.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- static get_auditlogs(cb)
Retrieve queued audit logs from the Carbon Black Cloud server.
- Required Permissions:
org.audits (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
- Returns:
List of dictionary objects representing the audit logs, or an empty list if none available.
- Return type:
list[dict]
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
Devices Module
The model and query classes for referencing platform devices.
A platform device represents an endpoint registered with the Carbon Black Cloud that runs a sensor, which communicates with Carbon Black analytics and the console. Using these classes, you can search for devices using a wide variety of filterable fields, such as policy ID, status, or operating system. You can also perform actions on individual devices such as quarantining/unquarantining them, enabling or disabling bypass, or upgrading them to a new sensor version.
Typical usage example:
# assume "cb" is an instance of CBCloudAPI
query = cb.select(Device).where(os="WINDOWS").set_policy_ids([142857])
for device in query:
device.quarantine(True)
- class Device(cb, model_unique_id, initial_data=None)
Bases:
PlatformModel
Represents a device (endpoint) within the Carbon Black Cloud.
Device
objects are generally located through a search (usingDeviceSearchQuery
) before they can be operated on.- 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
asset_group – The asset groups that this device is a member of.
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 device represented.
initial_data (dict) – Initial data used to populate the device.
- add_to_groups(groups)
Given a list of asset groups, adds this device to each one as a member.
- Parameters:
groups (list[AssetGroup]) – The list of groups to add this device to.
- add_to_groups_by_id(group_ids)
Given a list of asset group IDs, adds this device to each one as a member.
- Parameters:
group_ids (list[str]) – The list of group IDs to add this device to.
- 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
- delete_sensor()
Delete this sensor device.
- Required Permissions:
device.deregistered(DELETE)
- Returns:
The JSON output from the request.
- Return type:
str
- property deviceId
Warn user that Platform Devices use ‘id’, not ‘device_id’.
Platform Device APIs return ‘id’ in API responses, where Endpoint Standard APIs return ‘deviceId’.
- Raises:
AttributeError – In all cases.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_asset_group_ids(membership='ALL')
Finds the list of asset group IDs that this device is a member of.
- Parameters:
membership (str) – Can restrict the types of group membership returned by this method. Values are “ALL” to return all groups, “DYNAMIC” to return only groups that each member belongs to via the asset group query, or “MANUAL” to return only groups that the members were manually added to. Default is “ALL”.
- Returns:
A list of asset group IDs this device belongs to.
- Return type:
list[str]
- get_asset_groups(membership='ALL')
Finds the list of asset groups that this device is a member of.
- Required Permissions:
group-management(READ)
- Parameters:
membership (str) – Can restrict the types of group membership returned by this method. Values are “ALL” to return all groups, “DYNAMIC” to return only groups that each member belongs to via the asset group query, or “MANUAL” to return only groups that the members were manually added to. Default is “ALL”.
- Returns:
A list of asset groups this device belongs to.
- Return type:
list[AssetGroup]
- classmethod get_asset_groups_for_devices(cb, devices, membership='ALL')
Given a list of devices, returns lists of asset groups that they are members of.
- Required Permissions:
group-management(READ)
- Parameters:
cls (class) – Class associated with the
Device
object.cb (BaseAPI) – Reference to API object used to communicate with the server.
devices (int, Device, or list) – The devices to find the group membership of. This may be an integer device ID, a
Device
object, or a list of either integers orDevice
objects.membership (str) – Can restrict the types of group membership returned by this method. Values are “ALL” to return all groups, “DYNAMIC” to return only groups that each member belongs to via the asset group query, or “MANUAL” to return only groups that the members were manually added to. Default is “ALL”.
- Returns:
A dict containing member IDs as keys, and lists of group IDs as values.
- Return type:
dict
- 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 of the vulnerabilities for this device.
- Return type:
dict
- get_vulnerabilties()
Return a query to get an operating system or application vulnerability list for this device.
- Returns:
Query for searching for vulnerabilities on this device.
- Return type:
- 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:
- Raises:
ApiError – If there is an error establishing a Live Response session for this
Device
.
- property 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. DefaultTrue
.
- Returns:
The object representing all running jobs.
None
if the operation is a no-op.- Return type:
- classmethod preview_add_policy_override_for_devices(cb, policy_id, devices)
Previews changes to the effective policies for devices which result from setting a policy override on them.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
policy_id (int) – The ID of the policy to be added to the devices as an override.
devices (list) – The devices which will have their policies overridden. Each entry in this list is either an integer device ID or a
Device
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- preview_remove_policy_override()
Previews changes to this device’s effective policy which result from removing its policy override.
- Required Permissions:
org.policies (READ)
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_remove_policy_override_for_devices(cb, devices)
Previews changes to the effective policies for devices which result from removing their policy override.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
devices (list) – The devices which will have their policy overrides removed. Each entry in this list is either an integer device ID or a
Device
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- 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
- refresh()
Reload this object from the server.
- remove_from_groups(groups)
Given a list of asset groups, removes this device from each one as a member.
- Parameters:
groups (list[AssetGroup]) – The list of groups to remove this device from.
- remove_from_groups_by_id(group_ids)
Given a list of asset group IDs, removes this device from each one as a member.
- Parameters:
group_ids (list[str]) – The list of group IDs to remove this device from.
- swagger_meta_file
The valid values for the ‘filter’ parameter to get_asset_groups_for_devices().
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- 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 device.
- 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
- vulnerability_refresh()
Refresh vulnerability information for the device.
- Required Permissions:
vulnerabilityAssessment.data(EXECUTE)
- class DeviceFacet(cb, model_unique_id, initial_data=None)
Bases:
UnrefreshableModel
Represents a device field in a facet search.
Faceting is a search technique that categorizes search results according to common attributes. This allows users to explore and discover information within a dataset, in this case, the set of devices.
- Example:
>>> facets = api.select(Device).facets(['policy_id']) >>> for value in facets[0].values_: ... print(f"Policy ID {value.id}: {value.total} device(s)")
- 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:
UnrefreshableModel
Represents a value of a particular faceted field.
Faceting is a search technique that categorizes search results according to common attributes. This allows users to explore and discover information within a dataset, in this case, the set of devices.
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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- query_devices()
Set up a device query to find all devices that match this facet value.
Example
>>> facets = api.select(Device).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.
- A new
- Return type:
DeviceQuery
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- property values_
Returns the list of facet values for this facet.
- class DeviceSearchQuery(doc_class, cb)
Bases:
BaseQuery
,QueryBuilderSupportMixin
,CriteriaBuilderSupportMixin
,IterableQueryMixin
,AsyncQueryMixin
Query object that is used to locate
Device
objects.The
DeviceSearchQuery
is constructed via SDK functions like theselect()
method onCBCloudAPI
. The user would then add a query and/or criteria to it before iterating over the results.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.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- 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.
- Deprecated:
Use DeviceSearchQuery.export for increased export capabilities and limits
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.
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- export()
Starts the process of exporting Devices from the organization in CSV format.
Example
>>> cb.select(Device).set_status(["ACTIVE"]).export()
- Required Permissions:
device(READ)
- Returns:
The asynchronous job that will provide the export output when the server has prepared it.
- Return type:
- facets(fieldlist, max_rows=0)
Return information about the facets for all matching devices, 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]
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- 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
- scroll(rows=10000)
Iteratively paginate all Devices beyond the 10k max search limits.
To fetch the next set of Devices repeatively call the scroll function until DeviceSearchQuery.num_remaining == 0 or no results are returned.
Example
>>> cb.select(Device).set_status(["ACTIVE"]).scroll(100)
- Required Permissions:
device(READ)
- Parameters:
rows (int) – The number of rows to fetch
- Returns:
The list of results
- Return type:
list[Device]
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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. Must be in the range (0, 10000).
- Returns:
This instance.
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- uninstall_sensor()
Uninstall the specified sensor devices.
- Required Permissions:
device.uninstall(EXECUTE)
- Returns:
The JSON output from the request.
- Return type:
str
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- 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
- log = <Logger cbc_sdk.platform.devices (WARNING)>
“Device Models
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:
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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class EventFacet(cb, model_unique_id, initial_data)
Bases:
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:
UnrefreshableModel
Represents the range (bucketed) facet fields and values associated with an Event Facet query.
Initialize a ProcessFacet Ranges object with initial_data.
- property facets
Returns the reified EventFacet.Terms._facets for this result.
- property fields
Returns the ranges fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class Terms(cb, initial_data)
Bases:
UnrefreshableModel
Represents the facet fields and values associated with an Event Facet query.
Initialize a ProcessFacet Terms object with initial_data.
- property facets
Returns the terms’ facets for this result.
- property fields
Returns the terms facets’ fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- property ranges_
Returns the reified EventFacet.Ranges for this result.
- refresh()
Reload this object from the server.
- property terms_
Returns the reified EventFacet.Terms for this result.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class EventFacetQuery(cls, cb, query=None)
Bases:
FacetQuery
Represents the logic for an Event Facet query.
Initialize the FacetQuery object.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- add_facet_field(field)
Sets the facet fields to be received by this query.
- Parameters:
field (str or [str]) – Field(s) to be received.
- Returns:
The Query object that will receive the specified field(s).
- Return type:
Query (AsyncQuery)
Example
>>> cb.select(ProcessFacet).add_facet_field(["process_name", "process_username"])
- add_range(range)
Sets the facet ranges to be received by this query.
- Parameters:
range (dict or [dict]) – Range(s) to be received.
- Returns:
The Query object that will receive the specified range(s).
- Return type:
Query (AsyncQuery)
Note
The range parameter must be in this dictionary format:
{
“bucket_size”: “<object>”,
“start”: “<object>”,
“end”: “<object>”,
“field”: “<string>”
},
where “bucket_size”, “start”, and “end” can be numbers or ISO 8601 timestamps.
Examples
>>> cb.select(ProcessFacet).add_range({"bucket_size": 5, "start": 0, "end": 10, "field": "netconn_count"}) >>> cb.select(ProcessFacet).add_range({"bucket_size": "+1DAY", "start": "2020-11-01T00:00:00Z", ... "end": "2020-11-12T00:00:00Z", "field": "backend_timestamp"})
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- limit(limit)
Sets the maximum number of facets per category (i.e. any Process Search Fields in self._fields).
The default limit for Process Facet searches in the Carbon Black Cloud backend is 100.
- Parameters:
limit (int) – Maximum number of facets per category.
- Returns:
The Query object with new limit parameter.
- Return type:
Query (AsyncQuery)
Example
>>> cb.select(ProcessFacet).where(process_name="foo.exe").limit(50)
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- property results
Save query results to self._results with self._search() method.
- set_rows(rows)
Sets the number of facet results to return with the query.
- Parameters:
rows (int) – Number of rows to return.
- Returns:
The Query object with the new rows parameter.
- Return type:
Query (AsyncQuery)
Example
>>> cb.select(ProcessFacet).set_rows(50)
- 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.
"-2w" (Should be in the form) –
y=year (where) –
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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required") >>> second_query = api.select(Process). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required") >>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
- timeout(msecs)
Sets the timeout on an AsyncQuery.
- Parameters:
msecs (int) – Timeout duration, in milliseconds. This value can never be greater than the configured default timeout. If this is 0, the configured default timeout value is used.
- Returns:
The Query object with new milliseconds parameter.
- Return type:
Query (AsyncQuery)
Example
>>> cb.select(ProcessFacet).where(process_name="foo.exe").timeout(5000)
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- class EventQuery(doc_class, cb)
Bases:
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.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- batch_size(new_batch_size)
Set the batch size of the paginated query.
- Parameters:
new_batch_size (int) – The new batch size.
- Returns:
A new query with the updated batch size.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- set_fields(fields)
Sets the fields to be returned with the response.
- Parameters:
fields (str or list[str]) – Field or list of fields to be returned.
- set_rows(rows)
Sets the ‘rows’ query body parameter, determining how many rows of results to request.
- Parameters:
rows (int) – How many rows to request.
- set_start(start)
Sets the ‘start’ query body parameter, determining where to begin retrieving results from.
- Parameters:
start (int) – Where to start results from.
- 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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required") >>> second_query = api.select(Process). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required") >>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
- Parameters:
key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.
- Returns:
The query with sorting parameters.
- Return type:
Example
>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
Grants Module
Model and Query Classes for Administrative Grants and Profiles
- class Grant(cb, model_unique_id, initial_data=None)
Bases:
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:
- build()
Builds the new Grant object from the entered data.
- Returns:
The new Grant object.
- Return type:
- 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:
- 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:
- 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:
- 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:
- class Profile(cb, grant, model_unique_id, initial_data=None)
Bases:
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:
- property allowed_orgs
Returns the list of organization URNs allowed by this profile.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- 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
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- 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).
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- 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:
- 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:
- build()
Builds the new Profile object from the entered data.
- Returns:
The new Profile object.
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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.
ID. (The arguments to be used are 'org_key' and 'userid' for the two parts of 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:
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- 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
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property profiles_
Return the profiles associated with this grant.
- Returns:
The profiles associated with this grant, each represented as a Profile object.
- Return type:
list
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- class GrantQuery(doc_class, cb)
Bases:
BaseQuery
,IterableQueryMixin
,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:
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- log = <Logger cbc_sdk.platform.grants (WARNING)>
Grant and Profile Models
- normalize_org(org)
Internal function to normalize an org reference to a URN.
Jobs Module
Model and Query Classes for Jobs API
- class Job(cb, model_unique_id, initial_data=None)
Bases:
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
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- 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
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class JobQuery(doc_class, cb)
Bases:
BaseQuery
,IterableQueryMixin
,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.
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
Legacy Alerts Module
Model and Query Classes for Legacy Alerts and Workflows used Alert API v6 and SDK 1.4.3 or earlier
- class LegacyAlertSearchQueryCriterionMixin
Bases:
CriteriaBuilderSupportMixin
Represents a legacy alert, based on Alert API v6 or SDK 1.4.3 or earlier.
- set_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string alert IDs.
- Returns:
This instance.
- Return type:
- set_blocked_threat_categories(categories)
The field blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_categories(categories)
The field categories was deprecated and not included in v7. This method has been removed.
In Alerts v7, only records with the type THREAT are returned. Records that in v6 had the category MONITORED (Observed) are now Observations See Developer Network Alerts v6 Migration for more details.
- Parameters:
categories (list) – List of categories to be restricted to.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_cluster_names(names)
Restricts the alerts that this query is performed on to the specified Kubernetes cluster names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes cluster names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- 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. In SDK 1.5.0 to align with Alerts v7 API, create_time is set as time_range outside of criteria.
- Deprecated:
Use add_time_criteria(field_name, start, end, range) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_ids (list) – List of integer device IDs.
- Returns:
This instance.
- Return type:
- set_device_locations(locations)
Restricts the alerts that this query is performed on to the specified device locations.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
locations (list) – List of device locations to look for. Valid values are “ONSITE”, “OFFSITE”, and “UNKNOWN”.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_device_names(device_names)
Restricts the alerts that this query is performed on to the specified device names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_names (list) – List of string device names.
- Returns:
This instance.
- Return type:
- set_device_os(device_os)
Restricts the alerts that this query is performed on to the specified device operating systems.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os (list) – List of string operating systems. Valid values are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER.”
- Returns:
This instance.
- Return type:
- set_device_os_versions(device_os_versions)
Restricts the alerts that this query is performed on to the specified device operating system versions.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
device_os_versions (list) – List of string operating system versions.
- Returns:
This instance.
- Return type:
- set_device_username(users)
Restricts the alerts that this query is performed on to the specified user names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
users (list) – List of string user names.
- Returns:
This instance.
- Return type:
- set_egress_group_ids(ids)
Restricts the alerts that this query is performed on to the specified egress group IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of egress group names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_external_device_friendly_names(names)
Restricts the alerts that this query is performed on to the specified external device friendly names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of external device IDs to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_group_results(do_group)
The field group_results was deprecated and not included in v7. This method has been removed.
It previously specified whether to group the results of the query. Use the Grouped Alerts Operations #grouped-alerts-operations) instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
do_group (bool) – True to group the results, False to not do so.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_ip_reputations(reputations)
Restricts the alerts that this query is performed on to the specified IP reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reputations (list) – List of IP reputation values to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_kill_chain_statuses(statuses)
The field kill_chain_status was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: statuses (list): List of kill chain statuses to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_legacy_alert_ids(alert_ids)
Restricts the alerts that this query is performed on to the specified legacy alert IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alert_ids (list) – List of string legacy alert IDs.
- Returns:
This instance.
- Return type:
- set_namespaces(namespaces)
Restricts the alerts that this query is performed on to the specified Kubernetes namespaces.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
namespaces (list) – List of Kubernetes namespaces to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_not_blocked_threat_categories(categories)
The field not_blocked_threat_category was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
Args: categories (list): List of threat categories to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_policy_applied(applied_statuses)
Restricts the alerts that this query is performed on to the specified policy status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_policy_ids(policy_ids)
Restricts the alerts that this query is performed on to the specified policy IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_ids (list) – List of integer policy IDs.
- Returns:
This instance.
- Return type:
- set_policy_names(policy_names)
Restricts the alerts that this query is performed on to the specified policy names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
policy_names (list) – List of string policy names.
- Returns:
This instance.
- Return type:
- set_ports(ports)
Restricts the alerts that this query is performed on to the specified netconn_local_ports.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
Note that in SDK 1.5.0, to align with Alerts API v7, the search field was updated from port to netconn_local_port. It is possible to search on either netconn_local_port or netconn_remote_port using the `add_criteria(fieldname, [field values]) method.
- Parameters:
ports (list) – List of netconn_local_ports to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_process_names(process_names)
Restricts the alerts that this query is performed on to the specified process names.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
process_names (list) – List of string process names.
- Returns:
This instance.
- Return type:
- set_process_sha256(shas)
Restricts the alerts that this query is performed on to the specified process SHA-256 hash values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
shas (list) – List of string process SHA-256 hash values.
- Returns:
This instance.
- Return type:
- set_product_ids(ids)
Restricts the alerts that this query is performed on to the specified product IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of product names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_protocols(protocols)
Restricts the alerts that this query is performed on to the specified protocols.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
protocols (list) – List of protocols to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reason_code(reason)
Restricts the alerts that this query is performed on to the specified reason codes (enum values).
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
reason (list) – List of string reason codes to look for.
- Returns:
This instance.
- Return type:
CBAnalyticsAlertSearchQuery
- set_remote_domains(domains)
Restricts the alerts that this query is performed on to the specified remote domains.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
ids (list) – List of pod names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_reputations(reps)
Restricts the alerts that this query is performed on to the specified reputation values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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:
- set_rule_ids(ids)
Restricts the alerts that this query is performed on to the specified Kubernetes policy rule IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
In SDK prior to 1.5.0 this was only supported for Container Runtime Alerts so will convert to k8s_rule_id in criteria. In SDK 1.5.0 and later, aligned to Alert v7 API, use add_criteria() should be used for both k8s_rule_id and for other alert types, rule_id.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of Kubernetes policy rule names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
- set_run_states(states)
Restricts the alerts that this query is performed on to the specified run states.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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_serial_numbers(serial_numbers)
Restricts the alerts that this query is performed on to the specified serial numbers.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
serial_numbers (list) – List of serial numbers to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_tags(tags)
Restricts the alerts that this query is performed on to the specified tag values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
tags (list) – List of string tag values.
- Returns:
This instance.
- Return type:
- set_target_priorities(priorities)
Restricts the alerts that this query is performed on to the specified target priority values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
priorities (list) – List of string target priority values. Valid values are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.
- Returns:
This instance.
- Return type:
- set_threat_cause_vectors(vectors)
The field threat_cause_vector was deprecated and not included in v7. This method has been removed.
See Developer Network Alerts v6 Migration for more details.
- Parameters:
vectors (list) – List of threat cause vectors to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_threat_ids(threats)
Restricts the alerts that this query is performed on to the specified threat ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
threats (list) – List of string threat ID values.
- Returns:
This instance.
- Return type:
- set_types(alerttypes)
Restricts the alerts that this query is performed on to the specified alert type values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
alerttypes (list) – List of string alert type values. Valid values are “CB_ANALYTICS”, “WATCHLIST”, “DEVICE_CONTROL”, and “CONTAINER_RUNTIME”. In SDK 1.5.0, to align with Alert API v7, more alert types are available but the add_criteria method must be used.
- Returns:
This instance.
- Return type:
Note: - When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.
- set_vendor_ids(ids)
Restricts the alerts that this query is performed on to the specified vendor IDs.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of vendor names to look for.
- Returns:
This instance.
- Return type:
DeviceControlAlertSearchQuery
- set_watchlist_ids(ids)
Restricts the alerts that this query is performed on to the specified watchlist ID values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of string watchlist name values.
- Returns:
This instance.
- Return type:
WatchlistAlertSearchQuery
- set_workflows(workflow_vals)
Restricts the alerts that this query is performed on to the specified workflow status values.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
workflow_vals (list) – List of string alert type values. Valid values are “OPEN” and “DISMISSED”.
- Returns:
This instance.
- Return type:
- set_workload_ids(ids)
The field workload_id was deprecated and not included in v7. This method has been removed.
Use workload_name instead. See Developer Network Alerts v6 Migration for more details.
- Parameters:
ids (list) – List of workload IDs to look for.
- Raises:
FunctionalityDecommissioned – If the requested attribute is no longer available.
- set_workload_kinds(kinds)
Restricts the alerts that this query is performed on to the specified workload types.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- 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.
- Deprecated:
Use add_criteria(field_name, [field_value]) instead.
- Parameters:
names (list) – List of workload names to look for.
- Returns:
This instance.
- Return type:
ContainerRuntimeAlertSearchQuery
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:
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
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
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:
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.
- 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. This may never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.
- Returns:
list of Observations
- Return type:
list
- Raises:
ApiError – if cb is not instance of CBCloudAPI
- deobfuscate_cmdline()
Deobfuscates the command line of the process pointed to by the observation and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_details(timeout=0, async_mode=False)
Requests detailed results.
- Parameters:
timeout (int) – Observations details request timeout in milliseconds. This may never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.
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:
- Raises:
ApiError – when rule_id is not returned for the Observation
Examples
>>> observation = api.select(Observation, observation_id) >>> threat_metadata = observation.get_network_threat_metadata()
- refresh()
Reload this object from the server.
- 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
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class ObservationFacet(cb, model_unique_id, initial_data)
Bases:
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:
UnrefreshableModel
Represents the range (bucketed) facet fields and values associated with an Observation Facet query.
Initialize an ObservationFacet Ranges object with initial_data.
- property facets
Returns the reified ObservationFacet.Terms._facets for this result.
- property fields
Returns the ranges fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class Terms(cb, initial_data)
Bases:
UnrefreshableModel
Represents the facet fields and values associated with an Observation Facet query.
Initialize an ObservationFacet Terms object with initial_data.
- property facets
Returns the terms’ facets for this result.
- property fields
Returns the terms facets’ fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- property ranges_
Returns the reified ObservationFacet.Ranges for this result.
- refresh()
Reload this object from the server.
- property terms_
Returns the reified ObservationFacet.Terms for this result.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- 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:
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.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- batch_size(new_batch_size)
Set the batch size of the paginated query.
- Parameters:
new_batch_size (int) – The new batch size.
- Returns:
A new query with the updated batch size.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- 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"): >>> ...
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- 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_fields(fields)
Sets the fields to be returned with the response.
- Parameters:
fields (str or list[str]) – Field or list of fields to be returned.
- 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:
Example
>>> cb.select(Observation).where(process_name="foo.exe").set_rows(50)
- set_start(start)
Sets the ‘start’ query body parameter, determining where to begin retrieving results from.
- Parameters:
start (int) – Where to start results from.
- 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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required") >>> second_query = api.select(Process). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required") >>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
- Parameters:
key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.
- Returns:
The query with sorting parameters.
- Return type:
Example
>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")
- timeout(msecs)
Sets the timeout on a observation query.
- Parameters:
msecs (int) – Timeout duration, in milliseconds. This may never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.
- Returns:
The Query object with new milliseconds parameter.
- Return type:
Example
>>> cb.select(Observation).where(process_name="foo.exe").timeout(5000)
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
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:
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
position – Relative priority of this policy within the organization. Lower values indicate higher priority.
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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]
- property 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
- property 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:
- property data_collection_rule_configs
Returns a dictionary of data collection rule configuration IDs and objects for this Policy.
- Returns:
- A dictionary with data collection rule configuration IDs as keys and DataCollectionRuleConfig objects
as values.
- Return type:
dict
- property data_collection_rule_configs_list
Returns a list of data collection rule configuration objects for this Policy.
- Returns:
A list of DataCollectionRuleConfig objects.
- Return type:
list
- delete()
Delete this object.
- 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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- 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.
- property host_based_firewall_rule_config
Returns the host-based firewall rule configuration for this policy.
- Returns:
The host-based firewall rule configuration, or None.
- Return type:
- Raises:
InvalidObjectError – If there’s more than one host-based firewall rule configuration (should not happen).
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property latestRevision
Returns the latest revision of this policy (compatibility method).
- property 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
- property object_rule_configs_list
Returns a list of rule configuration objects for this Policy.
- Returns:
A list of PolicyRuleConfig objects.
- Return type:
list
- property 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
- property policy
Returns the contents of this policy [compatibility method].
- preview_add_policy_override(devices)
Previews changes to the effective policies for devices which result from setting this policy override on them.
- Required Permissions:
org.policies (READ)
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
devices (list) – The devices which will have their policies overridden. Each entry in this list is either an integer device ID or a
Device
object.
- Returns:
- A list of
DevicePolicyChangePreview
objects representing the assets that change which policy is effective as the result of this operation.
- A list of
- Return type:
- classmethod preview_policy_rank_changes(cb, changes_list)
Previews changes in the ranking of policies, and determines how this will affect asset groups.
Example:
>>> cb = CBCloudAPI(profile='sample') >>> changes = Policy.preview_policy_rank_changes(cb, [(667251, 1)]) >>> # also: changes = Policy.preview_policy_rank_changes(cb, [{"id": 667251, "position": 1}]) >>> len(changes) 2 >>> changes[0].current_policy_id 660578 >>> changes[0].new_policy_id 667251
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
changes_list (list) – The list of proposed changes in the ranking of policies. Each change may be in the form of a dict, in which case the “id” and “position” members are used to designate the policy ID and the new position, or in the form of a list or tuple, in which case the first element specifies the policy ID, and the second element specifies the new position. In all cases, “position” values are limited to values in the range [1.._N_], where _N_ is the total number of policies in the organization.
- Returns:
A list of objects containing data previewing the policy changes.
- Return type:
- preview_rank_change(new_rank)
Previews a change in the ranking of this policy, and determines how this will affect asset groups.
- Parameters:
new_rank (int) – The new rank to give this policy. Ranks are limited to values in the range [1.._N_], where _N_ is the total number of policies in the organization.
- Returns:
A list of objects containing data previewing the policy changes.
- Return type:
- property priorityLevel
Returns the priority level of this policy (compatibility method).
- refresh()
Reload this object from the server.
- 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.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- set_auth_event_collection(flag)
Sets auth event collection to be enabled or disabled on this policy.
- Parameters:
flag (bool) –
True
to enable auth event data collection,False
to disable it.- Raises:
ApiError – If the parameter setting operation failed.
- set_data_collection(parameter, value)
Sets a data collection parameter value on any data collection rule configurations in the policy that have it.
As a safety check, this method also validates that the type of the existing value of that parameter is the same as the type of the new value we want to set for that parameter.
- Parameters:
parameter (str) – The name of the parameter to set.
value (Any) – The value of the parameter to set.
- Raises:
ApiError – If the parameter setting operation failed.
- set_xdr_collection(flag)
Sets XDR collection to be enabled or disabled on this policy.
- Parameters:
flag (bool) –
True
to enable XDR data collection,False
to disable it.- Raises:
ApiError – If the parameter setting operation failed.
- property systemPolicy
Returns whether or not this is a systsem policy (compatibility method).
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- 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
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- class PolicyQuery(doc_class, cb)
Bases:
BaseQuery
,IterableQueryMixin
,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:
- 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:
- 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:
- 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:
- Raises:
ApiError – If not supplied with a string priority value or a list of string priority values.
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- class PolicyRule(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
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.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- property is_deleted
Returns True if this rule object has been deleted.
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this rule against its constraints.
- Raises:
InvalidObjectError – If the rule object is not valid.
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:
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.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_assignment_mode()
Returns the assignment mode of this core prevention rule configuration.
- Returns:
The assignment mode, either “REPORT” or “BLOCK”.
- Return type:
str
- get_parameter(name, default_value=None)
Returns a parameter value from the rule configuration.
- Parameters:
name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.
- Returns:
The parameter value, or None if there is no value.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property parameter_names
Returns a list of parameter names in this rule configuration.
- Returns:
A list of parameter names in this rule configuration.
- Return type:
list[str]
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- 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”.
- 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.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this rule configuration against its constraints.
- Raises:
InvalidObjectError – If the rule object is not valid.
- class DataCollectionRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
PolicyRuleConfig
Represents a data collection 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 DataCollectionRuleConfig, 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.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_parameter(name, default_value=None)
Returns a parameter value from the rule configuration.
- Parameters:
name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.
- Returns:
The parameter value, or None if there is no value.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property parameter_names
Returns a list of parameter names in this rule configuration.
- Returns:
A list of parameter names in this rule configuration.
- Return type:
list[str]
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- 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.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this rule configuration against its constraints.
- Raises:
InvalidObjectError – If the rule object is not valid.
- class HostBasedFirewallRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
PolicyRuleConfig
Represents a host-based firewall rule configuration in the policy.
- 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.
- class FirewallRule(cb, parent, initial_data)
Bases:
MutableBaseModel
Represents a single firewall rule.
- Parameters:
action – The action to take when rule is hit
application_path – The application path to limit the rule
direction – The direction the network request is being made from
enabled – Whether the rule is enabled
protocol – The type of network request
local_ip_address – IPv4 address of the local side of the network connection (stored as dotted decimal)
local_port_ranges – TCP or UDP port used by the local side of the network connection
remote_ip_address – IPv4 address of the remote side of the network connection (stored as dotted decimal)
remote_port_ranges – TCP or UDP port used by the remote side of the network connection
test_mode – Enables host-based firewall hits without blocking network traffic or generating alerts
Initialize the FirewallRule object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the firewall rule.
parent (HostBasedFirewallRuleConfig) – The parent rule configuration.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- refresh()
Reload this object from the server.
- remove()
Removes this rule from the rule group that contains it.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- class FirewallRuleGroup(cb, parent, initial_data)
Bases:
MutableBaseModel
Represents a group of related firewall rules.
- Parameters:
name – Name of the rule group
description – Description of the rule group
rules – List of rules in the rule group
Initialize the FirewallRuleGroup object.
- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
initial_data (dict) – Initial data used to populate the firewall rule group.
parent (HostBasedFirewallRuleConfig) – The parent rule configuration.
- append_rule(name, action, direction, protocol, remote_ip, **kwargs)
Creates a new FirewallRule object and appends it to this rule group.
- Parameters:
name (str) – The name for the new rule.
action (str) – The action to be taken by this rule. Valid values are “ALLOW,” “BLOCK,” and “BLOCK_ALERT.”
direction (str) – The traffic direction this rule matches. Valid values are “IN,” “OUT,” and “BOTH.”
protocol (str) – The network protocol this rule matches. Valid values are “TCP” and “UDP.”
remote_ip (str) – The remote IP address this rule matches.
kwargs (dict) – Additional parameters which may be added to the new rule.
- Returns:
The new rule object.
- Return type:
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- refresh()
Reload this object from the server.
- remove()
Removes this rule group from the rule configuration.
- reset()
Undo any changes made to this object’s fields.
- property rules_
Returns a list of the firewall rules within this rule group.
- Returns:
List of contained firewall rules.
- Return type:
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- append_rule_group(name, description)
Creates a new FirewallRuleGroup object and appends it to the list of rule groups in the rule configuration.
- Parameters:
name (str) – The name of the new rule group.
description (str) – The description of the new rule group.
- Returns:
The newly added rule group.
- Return type:
- copy_rules(*args)
Copies the parameters for host-based firewall rule configurations to another policy or policies.
- Required Permissions:
org.firewall.rules(UPDATE)
- Parameters:
args (list[Any]) – References to policies to copy to. May be Policy objects, integers, or string representations of integers.
- Returns:
Result structure from copy operation.
- Return type:
dict
- Raises:
ApiError – If the parameters could not be converted to policy IDs.
- property default_action
Returns the default action of this rule configuration.
- Returns:
The default action of this rule configuration, either “ALLOW” or “BLOCK.”
- Return type:
str
- delete()
Delete this object.
- property enabled
Returns whether or not the host-based firewall is enabled.
- Returns:
True if the host-based firewall is enabled, False if not.
- Return type:
bool
- export_rules(format='json')
Exports the rules from this host-based firewall rule configuration.
- Required Permissions:
org.firewall.rules(READ)
- Parameters:
format (str) – The format to return the rule data in. Valid values are “csv” and “json” (the default).
- Returns:
The exported rule configuration data.
- Return type:
str
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_parameter(name, default_value=None)
Returns a parameter value from the rule configuration.
- Parameters:
name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.
- Returns:
The parameter value, or None if there is no value.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property parameter_names
Returns a list of parameter names in this rule configuration.
- Returns:
A list of parameter names in this rule configuration.
- Return type:
list[str]
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- property rule_groups
Returns the list of rule groups in this rule configuration.
- Returns:
The list of rule groups.
- Return type:
list[FirewallRuleGroup]
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- set_default_action(action)
Sets the default action of this rule configuration.
- Parameters:
action (str) – The new default action of this rule configuration. Valid values are “ALLOW” and “BLOCK.”
- set_enabled(flag)
Sets whether or not the host-based firewall is enabled.
- Parameters:
flag (bool) – True if the host-based firewall should be enabled, False if not.
- 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.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this rule configuration against its constraints.
- Raises:
InvalidObjectError – If the rule object is not valid.
- class PolicyRuleConfig(cb, parent, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
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.
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_parameter(name, default_value=None)
Returns a parameter value from the rule configuration.
- Parameters:
name (str) – The parameter name.
default_value (Any) – The default value to return if there’s no parameter by that name. Default is None.
- Returns:
The parameter value, or None if there is no value.
- Return type:
Any
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property parameter_names
Returns a list of parameter names in this rule configuration.
- Returns:
A list of parameter names in this rule configuration.
- Return type:
list[str]
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- 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.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- validate()
Validates this rule configuration against its constraints.
- Raises:
InvalidObjectError – If the rule object is not valid.
Previewer Module
This module contains the DevicePolicyChangePreview
object.
When methods on Device
, Policy
, or AssetGroup
are called to “preview” changes in device policy,
a list of these objects is returned. Each object represents a change in “effective” policy on one or more
devices.
- class DevicePolicyChangePreview(cb, preview_data)
Bases:
object
Contains data previewing a change in device policies.
Changes to policies may happen via asset group memberships, policy rank changes, device policy overrides, or other causes.
Each one of these objects shows, for a given group of assets, the current policy that is the “effective policy” for those assets, the new policy that will be the “effective policy” for those assets, the number of assets affected, and which assets they are.
Creates a new instance of
AssetGroupChangePreview
.- Parameters:
cb (BaseAPI) – Reference to API object used to communicate with the server.
preview_data (dict) – Contains the preview data returned by the server API.
- property asset_count
The number of assets to be affected by the change in their effective policy.
- property asset_query
A
Device
query which looks up the assets that are to be affected by the change in their effective policy.Once the query is created, it can be modified with additional criteria or options before it is executed.
- property assets
The list of assets, i.e.
Device
objects, to be affected by the change in their effective policy.- Required Permissions:
device (READ)
- property current_policy
The
Policy
object that is the current “effective” policy for a group of assets.
- property current_policy_id
The ID of the policy that is the current “effective” policy for a group of assets.
- property current_policy_position
The position, or rank, of the policy that is the current “effective” policy for a group of assets.
- property new_policy
The
Policy
object that will become the new “effective” policy for a group of assets.
- property new_policy_id
The ID of the policy that will become the new “effective” policy for a group of assets.
- property new_policy_position
The position, or rank, of the policy that will become the new “effective” policy for a group of assets.
Processes Module
Model and query that allow location and manipulation of process data reported by an organization’s sensors.
This data can be used to identify applications that are acting abnormally and over time, cull the outliers from the total observed process activity, and retroactively identify the origination point for attacks that previously escaped notice. Use cases include:
Finding the process that was identified in an alert with a process search.
Finding processes that match targeted behavioral characteristics identified in Carbon Black or third-party threat intelligence reports.
Finding additional details about processes that were potentially involved in malicious activity identified elsewhere.
Using faceting to get filtering terms or prevalent values in a set of processes.
Locating processes generally requires the Endpoint Standard or Enterprise EDR products.
Typical usage example:
>>> query = api.select(Process).where("process_name:chrome.exe")
>>> for process in query:
... print(f"Chrome PID = {process.process_guid}")
- class AsyncProcessQuery(doc_class, cb)
Bases:
Query
A query object used to search for
Process
objects asynchronously.Create one of these objects by calling
select(Process)
on aCBCloudAPI
object.Initialize the
AsyncProcessQuery
object.- Parameters:
doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the
CBCloudAPI
object.
- add_criteria(key, newlist)
Add to the criteria on this query with a custom criteria key.
Will overwrite any existing criteria for the specified key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (str or list[str]) – Value or list of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"]) >>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
- add_exclusions(key, newlist)
Add to the exclusions on this query with a custom exclusions key.
Will overwrite any existing exclusion for the specified key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"]) >>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- batch_size(new_batch_size)
Set the batch size of the paginated query.
- Parameters:
new_batch_size (int) – The new batch size.
- Returns:
A new query with the updated batch size.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- set_fields(fields)
Sets the fields to be returned with the response.
- Parameters:
fields (str or list[str]) – Field or list of fields to be returned.
- set_rows(rows)
Sets the number of rows to request per batch.
This will not limit the total results to the specified number of rows; instead, the query will use this to determine how many rows to request at a time from the server.
- Parameters:
rows (int) – How many rows to request.
- set_start(start)
Sets the ‘start’ query body parameter, determining where to begin retrieving results from.
- Parameters:
start (int) – Where to start results from.
- 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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required") >>> second_query = api.select(Process). ... set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required") >>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
- sort_by(key, direction='ASC')
Sets the sorting behavior on a query’s results.
- Parameters:
key (str) – The key in the schema to sort by.
direction (str) – The sort order, either “ASC” or “DESC”.
- Returns:
The query with sorting parameters.
- Return type:
Example
>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")
- timeout(msecs)
Sets the timeout on a process query.
- Parameters:
msecs (int) – Timeout duration, in milliseconds. This can never be greater than the configured default timeout. If this is 0, the configured default timeout is used.
- Returns:
The modified query object.
- Return type:
Example
>>> cb.select(Process).where(process_name="foo.exe").timeout(5000)
- update_criteria(key, newlist)
Update the criteria on this query with a custom criteria key.
- Parameters:
key (str) – The key for the criteria item to be set.
newlist (list) – List of values to be set for the criteria item.
- Returns:
The query object with specified custom criteria.
Example
>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- update_exclusions(key, newlist)
Update the exclusion on this query with a custom exclusion key.
- Parameters:
key (str) – The key for the exclusion item to be set.
newlist (list) – List of values to be set for the exclusion item.
- Returns:
The query object with specified custom exclusion.
Example
>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])
Note
Use this method if there is no implemented method for your desired criteria.
- class Process(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)
Bases:
UnrefreshableModel
Information about a process running on one of the endpoints connected to the Carbon Black Cloud.
Objects of this type are retrieved through queries to the Carbon Black Cloud server, such as via
AsyncProcessQuery
.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 = list(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:
UnrefreshableModel
A summary of organization-specific information for a process.
The preferred interface for interacting with
Summary
models isProcess.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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class Tree(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)
Bases:
UnrefreshableModel
Summary of organization-specific information for a process.
The preferred interface for interacting with
Tree
models isProcess.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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- approve_process_sha256(description='')
Approves the application by adding the
process_sha256
to theWHITE_LIST
.- Parameters:
description (str) – The justification for why the application was added to the
WHITE_LIST
.- Returns:
ReputationOverride
object created in the Carbon Black Cloud.- Return type:
cbc_sdk.platform.ReputationOverride
- ban_process_sha256(description='')
Bans the application by adding the
process_sha256
to theBLACK_LIST
.- Parameters:
description (str) – The justification for why the application was added to the
BLACK_LIST
.- Returns:
cbc_sdk.platform.ReputationOverride)
ReputationOverride
object created in the Carbon Black Cloud.
- property children
Returns a list of child processes for this process.
- deobfuscate_cmdline()
Deobfuscates the command line of the process and returns the deobfuscated result.
- Required Permissions:
script.deobfuscation(EXECUTE)
- Returns:
A dict containing information about the obfuscated command line, including the deobfuscated result.
- Return type:
dict
- events(**kwargs)
Returns a query for events associated with this process’s process GUID.
- Parameters:
kwargs – Arguments to filter the event query with.
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 theadd_facet_field()
oradd_range()
methods.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- get_details(timeout=0, async_mode=False)
Requests detailed information about this process from the Carbon Black Cloud server.
- Required Permissions:
org.search.events(CREATE, READ)
- Parameters:
timeout (int) – Event details request timeout in milliseconds. This value can never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.
async_mode (bool) –
True
to request details in an asynchronous manner.
- Returns:
- If
async_mode
isTrue
. Callresult()
on thisFuture
to wait for completion and retrieve the results.
dict: If
async_mode
isFalse
.- If
- Return type:
Future
- property parents
Returns the parent process associated with this process, or
None
if there is no recorded parent.
- property process_md5
Returns a string representation of the MD5 hash for this process.
- property process_pids
Returns a list of integer PIDs associated with this process, or
None
if there are none.
- property process_sha256
Returns a string representation of the SHA256 hash for this process.
- refresh()
Reload this object from the server.
- property siblings
Returns a list of sibling processes for this process.
- property summary
Returns organization-specific information about this process.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- property tree
Returns a process tree associated with this process.
Example
>>> tree = process.tree
- class ProcessFacet(cb, model_unique_id, initial_data)
Bases:
UnrefreshableModel
Represents the results of a process facet query.
ProcessFacet
objects contain bothTerms
andRanges
. Each of those contain facet fields and values.Access all of the
Terms
facet data withProcessFacet.Terms.facets()
or see just the field names withProcessFacet.Terms.fields()
.Access all of the
Ranges
facet data withProcessFacet.Ranges.facets()
or see just the field names withProcessFacet.Ranges.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 the 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
ProcessFacet
object withinitial_data
.- class Ranges(cb, initial_data)
Bases:
UnrefreshableModel
The range (bucketed) facet fields and values associated with a process facet query.
Initialize a
ProcessFacet.Ranges
object withinitial_data
.- property facets
Returns the reified facets for this result.
- property fields
Returns the ranges fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class Terms(cb, initial_data)
Bases:
UnrefreshableModel
The facet fields and values associated with a process facet query.
Initialize a
ProcessFacet.Terms
object withinitial_data
.- property facets
Returns the terms’ facets for this result.
- property fields
Returns the terms facets’ fields for this result.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- property ranges_
Returns the reified
ProcessFacet.Ranges
for this result.
- refresh()
Reload this object from the server.
- property terms_
Returns the reified
ProcessFacet.Terms
for this result.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class SummaryQuery(doc_class, cb)
Bases:
BaseQuery
,AsyncQueryMixin
,QueryBuilderSupportMixin
A query used to search for
Process.Summary
orProcess.Tree
objects.Create one of these queries with a
select()
on eitherProcess.Summary
orProcess.Tree
. These queries are also created by accessing thesummary
ortree
properties onProcess
.Initialize the
SummaryQuery
object.- Parameters:
doc_class (class) – The class of the model this query returns.
cb (CBCloudAPI) – A reference to the
CBCloudAPI
object.
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- property results
Return the results of this query. If the query has not yet been run, it is run to determine the results.
- Required Permissions:
org.search.events(CREATE, READ)
- set_time_range(start=None, end=None, window=None)
Sets the
time_range
query body parameter, determining a time window based ondevice_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 “-nx”, where n is an integer and x is y=year, w=week, d=day, h=hour, m=minute, s=second.
Note
window
will take precendent overstart
andend
if provided.Example
>>> 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. This can never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.
- Returns:
The modified query object.
- Return type:
Example
>>> cb.select(Process).where(process_name="foo.exe").timeout(5000)
Reputation Module
Model and Query Classes for Reputation
- class ReputationOverride(cb, model_unique_id, initial_data=None)
Bases:
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:
- delete()
Delete this object.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class ReputationOverrideQuery(doc_class, cb)
Bases:
BaseQuery
,QueryBuilderSupportMixin
,IterableQueryMixin
,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.
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- 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.
Users Module
Model and Query Classes for Users
- class User(cb, model_unique_id, initial_data=None)
Bases:
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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.
- 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.
- 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.
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- grant()
Locates the access grant for this user.
- Returns:
Access grant for this user, or None if the user has none.
- Return type:
- is_dirty()
Returns whether or not any fields of this object have been changed.
- Returns:
True if any fields of this object have been changed, False if not.
- Return type:
bool
- property org_urn
Returns the URN for this user’s organization (used in accessing Grants).
- Returns:
URN for this user’s organization.
- Return type:
str
- refresh()
Reload this object from the server.
- reset()
Undo any changes made to this object’s fields.
- reset_google_authenticator_registration()
Forces Google Authenticator registration to be reset for this user.
- save()
Save any changes made to this object’s fields.
- Returns:
This object.
- Return type:
- 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.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- touch(fulltouch=False)
Force this object to be considered as changed.
- property urn
Returns the URN for this user (used in accessing Grants).
- Returns:
URN for this user.
- Return type:
str
- validate()
Validates this object.
- Returns:
True if the object is validated.
- Return type:
bool
- Raises:
InvalidObjectError – If the object has missing fields.
- class UserQuery(doc_class, cb)
Bases:
BaseQuery
,IterableQueryMixin
,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.
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- email_addresses(addrs)
Limit the query to users with the specified E-mail addresses. Call multiple times to add multiple addresses.
- Parameters:
addrs (list[str]) – List of addresses to be added to the query.
- Returns:
This object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- log = <Logger cbc_sdk.platform.users (WARNING)>
User Models
- normalize_profile_list(profile_templates)
Internal function to normalize a list of profile templates.
Vulnerability Assessment Module
Model and Query Classes for Vulnerability Assessment API
- class AffectedAssetQuery(vulnerability, cb)
Bases:
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.
- 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:
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- 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:
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- 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_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:
- 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:
- 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:
- 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.
- class Vulnerability(cb, model_unique_id, os_product_id=None, initial_data=None)
Bases:
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
- append(object, /)
Append object to the end of the list.
- clear()
Remove all items from list.
- copy()
Return a shallow copy of the list.
- count(value, /)
Return number of occurrences of value.
- extend(iterable, /)
Extend list by appending elements from the iterable.
- index(value, start=0, stop=9223372036854775807, /)
Return first index of value.
Raises ValueError if the value is not present.
- insert(index, object, /)
Insert object before index.
- pop(index=-1, /)
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()
Reverse IN PLACE.
- sort(*, key=None, reverse=False)
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- class OrgSummary(cb, initial_data=None)
Bases:
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
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- refresh()
Reload this object from the server.
- severity_levels()
Returns the severity levels
- Returns:
List of severities
- Return type:
Severities (list[str])
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- get(attrname, default_val=None)
Return an attribute of this object.
- Parameters:
attrname (str) – Name of the attribute to be returned.
default_val (Any) – Default value to be used if the attribute is not set.
- Returns:
The returned attribute value, which may be defaulted.
- Return type:
Any
- 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
- 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
- refresh()
Reload this object from the server.
- to_json()
Return a json object of the response.
- Returns:
The response dictionary representation.
- Return type:
Any
- class VulnerabilityAssetViewQuery(doc_class, cb)
Bases:
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.
- 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:
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- export()
Performs the query and export the results in the form of a Job.
- Returns:
The export job.
- Return type:
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- 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:
- 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:
- 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.
- class VulnerabilityOrgSummaryQuery(doc_class, cb, device=None)
Bases:
BaseQuery
Represents a query that is used fetch the VulnerabiltitySummary
Initialize the VulnerabilityQuery.
- 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.
device (cbc_sdk.platform.devices.Device) – Optional Device object to indicate VulnerabilityQuery is for a specific device
- 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:
- set_vcenter(vcenter_uuid)
Restricts the vulnerability summary to a specific vcenter
- Parameters:
vcenter_uuid (str) – vcenter uuid.
- Returns:
This instance.
- Return type:
- 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:
- submit()
Performs the query and returns the Vulnerability.OrgSummary
- Returns:
The vulnerabilty summary for the organization
- Return type:
- class VulnerabilityQuery(doc_class, cb, device=None)
Bases:
BaseQuery
,QueryBuilderSupportMixin
,IterableQueryMixin
,AsyncQueryMixin
Represents a query that is used to locate Vulnerabiltity objects.
Initialize the VulnerabilityQuery.
- 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.
device (cbc_sdk.platform.devices.Device) – Optional Device object to indicate VulnerabilityQuery is for a specific device
- 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:
- all()
Returns all the items of a query as a list.
- Returns:
List of query items
- Return type:
list
- and_(q=None, **kwargs)
Add a conjunctive filter to this query.
- Parameters:
q (Any) – Query string or solrq.Q object
**kwargs (dict) – Arguments to construct a solrq.Q with
- Returns:
This Query object.
- Return type:
- execute_async()
Executes the current query in an asynchronous fashion.
- Returns:
A future representing the query and its results.
- Return type:
Future
- 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:
- first()
Returns the first item that would be returned as the result of a query.
- Returns:
First query item
- Return type:
obj
- not_(q=None, **kwargs)
Adds a negated filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- one()
Returns the only item that would be returned by a query.
- Returns:
Sole query return item
- Return type:
obj
- Raises:
MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items
- or_(q=None, **kwargs)
Add a disjunctive filter to this query.
- Parameters:
q (solrq.Q) – Query object.
**kwargs (dict) – Arguments to construct a solrq.Q with.
- Returns:
This Query object.
- Return type:
- 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:
- 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:
- 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