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:

Job

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:

Process

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:

Job

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:

AlertSearchQuery

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:

Query

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:

Job

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:
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:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
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:

Query

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

Job

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.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

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:

Job

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:

Process

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:

Job

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:

Job

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:

Process

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:

Job

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:

Job

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:

Process

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:

Job

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 instances

  • policy_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:

AlertSearchQuery

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:

Alert

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:

AlertSearchQuery

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:

Query

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:
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:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
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:

Query

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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:

AlertSearchQuery

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.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

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:

Job

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:

Process

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:

Job

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:

Job

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:

NetworkThreatMetadata

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:

Process

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:

Job

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:

Job

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:

Process

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:

Job

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 (using AssetGroupQuery) before they can be operated

on. 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 or Device 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:

AssetGroup

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 is True if the group member is there due to the group’s dynamic query, and the boolean element manual which is True if the group member was manually added. (It is possible for both dynamic and manual to be True.)

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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 and remove_policy_id is False, contains the ID of the policy to be assigned to the specified groups. Default is None.

  • query (str) – If this is not None and remove_query is False, contains the new query string to be assigned to the specified groups. Default is None.

  • remove_policy_id (bool) – If this is True, indicates that the specified groups will have their policy ID removed entirely. Default is False.

  • remove_query (bool) – If this is True, indicates that the specified groups will have their query strings removed entirely. Default is False.

Returns:

A list of DevicePolicyChangePreview objects representing the assets

that change which policy is effective as the result of this operation.

Return type:

list[DevicePolicyChangePreview]

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 or Device 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:

MutableBaseModel

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 the select() method on CBCloudAPI. 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 standard add_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:

Query

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:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
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:

Query

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:

AssetGroupQuery

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:

AssetGroupQuery

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.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

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 (using DeviceSearchQuery) 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 or Device 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:

VulnerabilityQuery

lr_session(async_mode=False)

Retrieve a Live Response session object for this Device.

Required Permissions:

org.liveresponse.session(CREATE)

Returns:

Live Response session for the Device.

Return type:

LiveResponseSession

Raises:

ApiError – If there is an error establishing a Live Response session for this Device.

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. Default True.

Returns:

The object representing all running jobs. None if the operation is a no-op.

Return type:

NSXRemediationJob

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

Return type:

list[DevicePolicyChangePreview]

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.

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 the select() method on CBCloudAPI. 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:

Query

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:

Job

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:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
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:

Query

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:

DeviceSearchQuery

set_auto_scaling_group_name(group_names)

Restricts the devices that this query is performed on to the specified auto scaling group names.

Parameters:

group_names (list) – List of group names to restrict search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_cloud_provider_account_id(account_ids)

Restricts the devices that this query is performed on to the specified cloud provider account IDs.

Parameters:

account_ids (list) – List of account IDs to restrict search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_deployment_type(deployment_type)

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

Parameters:

deployment_type (list) – List of deployment types to restrict search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_device_ids(device_ids)

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

Parameters:

device_ids (list) – List of device IDs to restrict the search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_exclude_sensor_versions(sensor_versions)

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

Parameters:

sensor_versions (list) – List of sensor versions to be excluded.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_last_contact_time(*args, **kwargs)

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

Parameters:
  • *args (list) – Not used, retained for compatibility.

  • **kwargs (dict) – Keyword arguments to this function. The critical ones are “start” (the start time), “end” (the end time), and “range” (the range value).

Returns:

This instance.

Return type:

DeviceSearchQuery

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:

DeviceSearchQuery

set_os(operating_systems)

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

Parameters:

operating_systems (list) – List of operating systems to restrict search to. Valid values in this list are “WINDOWS”, “ANDROID”, “MAC”, “IOS”, “LINUX”, and “OTHER”.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_policy_ids(policy_ids)

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

Parameters:

policy_ids (list) – List of policy IDs to restrict the search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_status(statuses)

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

Parameters:

statuses (list) – List of statuses to restrict search to. Valid values in this list are “PENDING”, “REGISTERED”, “UNINSTALLED”, “DEREGISTERED”, “ACTIVE”, “INACTIVE”, “ERROR”, “ALL”, “BYPASS_ON”, “BYPASS”, “QUARANTINE”, “SENSOR_OUTOFDATE”, “DELETED”, and “LIVE”.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_target_priorities(target_priorities)

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

Parameters:

target_priorities (list) – List of priorities to restrict search to. Valid values in this list are “LOW”, “MEDIUM”, “HIGH”, and “MISSION_CRITICAL”.

Returns:

This instance.

Return type:

DeviceSearchQuery

set_virtual_private_cloud_id(cloud_ids)

Restricts the devices that this query is performed on to the specified virtual private cloud IDs.

Parameters:

cloud_ids (list) – List of cloud IDs to restrict search to.

Returns:

This instance.

Return type:

DeviceSearchQuery

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Example

>>> cb.select(Device).sort_by("status")
Parameters:
  • key (str) – The key in the schema to sort by.

  • direction (str) – The sort order, either “ASC” or “DESC”.

Returns:

This instance.

Return type:

DeviceSearchQuery

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

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

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 with EventFacet.Terms.fields().

Access all of the Ranges facet data with EventFacet.Ranges.facets() or see just the field names with EventFacet.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:

Query

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:

Query

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:

Query

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")