CB PSC API

This page documents the public interfaces exposed by cbapi when communicating with the Carbon Black Predictive Security Cloud (PSC).

Main Interface

To use cbapi with the Carbon Black PSC, you use CbPSCBaseAPI objects.

class cbapi.psc.rest_api.CbPSCBaseAPI(*args, **kwargs)

The main entry point into the Cb PSC API.

Parameters:profile (str) – (optional) Use the credentials in the named profile when connecting to the Carbon Black server. Uses the profile named ‘default’ when not specified.

Usage:

>>> from cbapi import CbPSCBaseAPI
>>> cb = CbPSCBaseAPI(profile="production")
alert_search_suggestions(query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:str (query) – A search query to use.
Returns:A list of search suggestions expressed as dict objects.
bulk_threat_dismiss(threat_ids, remediation=None, comment=None)

Dismiss the alerts associated with multiple threat IDs. The alerts will be left in a DISMISSED state after this request.

Parameters:
  • list (threat_ids) – List of string threat IDs.
  • str (comment) – The remediation state to set for all alerts.
  • str – The comment to set for all alerts.
Returns:

The request ID, which may be used to select a WorkflowStatus object.
bulk_threat_update(threat_ids, remediation=None, comment=None)

Update the alert status of alerts associated with multiple threat IDs. The alerts will be left in an OPEN state after this request.

Parameters:
  • list (threat_ids) – List of string threat IDs.
  • str (comment) – The remediation state to set for all alerts.
  • str – The comment to set for all alerts.
Returns:

The request ID, which may be used to select a WorkflowStatus object.
create(cls, data=None)

Creates a new object.

Parameters:cls (class) – The Model class (only some models can be created, for example, Feed, Notification, …)
Returns:An empty instance of the Model class
Raises:ApiError – if the Model cannot be created
device_background_scan(device_ids, scan)

Set the background scan option for the specified devices.

Parameters:
  • device_ids (list) – List of IDs of devices to be set.
  • scan (boolean) – True to turn background scan on, False to turn it off.
device_bypass(device_ids, enable)

Set the bypass option for the specified devices.

Parameters:
  • device_ids (list) – List of IDs of devices to be set.
  • enable (boolean) – True to enable bypass, False to disable it.
device_delete_sensor(device_ids)

Delete the specified sensor devices.

Parameters:device_ids (list) – List of IDs of devices to be deleted.
device_quarantine(device_ids, enable)

Set the quarantine option for the specified devices.

Parameters:
  • device_ids (list) – List of IDs of devices to be set.
  • enable (boolean) – True to enable quarantine, False to disable it.
device_uninstall_sensor(device_ids)

Uninstall the specified sensor devices.

Parameters:device_ids (list) – List of IDs of devices to be uninstalled.
device_update_policy(device_ids, policy_id)

Set the current policy for the specified devices.

Parameters:
  • device_ids (list) – List of IDs of devices to be changed.
  • policy_id (int) – ID of the policy to set for the devices.
device_update_sensor_version(device_ids, sensor_version)

Update the sensor version for the specified devices.

Parameters:
  • device_ids (list) – List of IDs of devices to be changed.
  • sensor_version (dict) – New version properties for the sensor.
select(cls, unique_id=None, *args, **kwargs)

Prepares a query against the Carbon Black data store.

Parameters:
  • cls (class) – The Model class (for example, Computer, Process, Binary, FileInstance) to query
  • unique_id – (optional) The unique id of the object to retrieve, to retrieve a single object by ID
Returns:

An instance of the Model class if a unique_id is provided, otherwise a Query object

Device API

The PSC can be used to enumerate devices within your organization, and change their status via a control request.

You can use the select() method on the CbPSCBaseAPI to create a query object for Device objects, which can be used to locate a list of Devices.

Example:

>>> cbapi = CbPSCBaseAPI(...)
>>> devices = cbapi.select(Device).set_os("LINUX").status("ALL")

Selects all devices running Linux from the current organization.

Query Object:

Model Object:

class cbapi.psc.models.Device(cb, model_unique_id, initial_data=None)

Represents a Device object in the Carbon Black server.

Variables:
activation_code = None
activation_code_expiry_time = None
ad_group_id = None
av_ave_version = None
av_engine = None
av_last_scan_time = None
av_master = None
av_pack_version = None
av_product_version = None
av_status = []
av_update_servers = []
av_vdf_version = None
background_scan(flag)

Set the background scan option for this device.

Parameters:flag (boolean) – True to turn background scan on, False to turn it off.
bypass(flag)

Set the bypass option for this device.

Parameters:flag (boolean) – True to enable bypass, False to disable it.
current_sensor_policy_name = None
delete_sensor()

Delete this sensor device.

deregistered_time = None
device_id = None
device_meta_data_item_list = []
device_owner_id = None
email = None
encoded_activation_code = None
first_name = None
id = None
last_contact_time = None
last_device_policy_changed_time = None
last_device_policy_requested_time = None
last_external_ip_address = None
last_internal_ip_address = None
last_location = None
last_name = None
last_policy_updated_time = None
last_reported_time = None
last_reset_time = None
last_shutdown_time = None
linux_kernel_version = None
login_user_name = None
lr_session()

Retrieve a Live Response session object for this Device.

Returns:Live Response session object
Return type:cbapi.defense.cblr.LiveResponseSession
Raises:ApiError – if there is an error establishing a Live Response session for this Device
mac_address = None
middle_name = None
name = None
organization_id = None
organization_name = None
os = None
os_version = None
passive_mode = None
policy_id = None
policy_name = None
policy_override = None
primary_key = 'id'
quarantine(flag)

Set the quarantine option for this device.

Parameters:flag (boolean) – True to enable quarantine, False to disable it.
quarantined = None
registered_time = None
scan_last_action_time = None
scan_last_complete_time = None
scan_status = None
sensor_out_of_date = None
sensor_states = []
sensor_version = None
status = None
target_priority_type = None
uninstall_code = None
uninstall_sensor()

Uninstall this sensor device.

update_policy(policy_id)

Set the current policy for this device.

Parameters:policy_id (int) – ID of the policy to set for the devices.
update_sensor_version(sensor_version)

Update the sensor version for this device.

Parameters:sensor_version (dict) – New version properties for the sensor.
urlobject = '/appservices/v6/orgs/{0}/devices'
urlobject_single = '/appservices/v6/orgs/{0}/devices/{1}'
vdi_base_device = None
virtual_machine = None
virtualization_provider = None
windows_platform = None

Alerts API

Using the API, you can search for alerts within your organization, and dismiss or undismiss them, either individually or in bulk.

You can use the select() method on the CbPSCBaseAPI to create a query object for BaseAlert objects, which can be used to locate a list of alerts. You can also search for more specialized alert types:

  • CBAnalyticsAlert - Alerts from CB Analytics
  • VMwareAlert - Alerts from VMware
  • WatchlistAlert - Alerts from watch lists

Example:

>>> cbapi = CbPSCBaseAPI(...)
>>> alerts = cbapi.select(BaseAlert).set_device_os(["WINDOWS"]).set_process_name(["IEXPLORE.EXE"])

Selects all alerts on a Windows device running the Internet Explorer process.

Individual alerts may have their status changed using the dismiss() or update() methods on the BaseAlert object. To dismiss multiple alerts at once, you can use the dismiss() or update() methods on the standard query, after adding criteria to it. This method returns a request ID, which can be used to create a WorkflowStatus object; querying this object’s “finished” property will let you know when the operation is finished.

Example:

>>> cbapi = CbPSCBaseAPI(...)
>>> query = cbapi.select(BaseAlert).set_process_name(["IEXPLORE.EXE"])
>>> reqid = query.dismiss("Using Chrome")
>>> stat = cbapi.select(WorkflowStatus, reqid)
>>> while not stat.finished:
>>>     # wait for it to finish

This dismisses all alerts which reference the Internet Explorer process.

Query Objects:

Model Objects:

class cbapi.psc.models.Workflow(cb, initial_data=None)

Represents a Workflow object in the Carbon Black server.

Variables:
  • changed_by – Username of the user who changed the workflow
  • comment – Comment when updating the workflow
  • last_update_time – When the workflow was last updated
  • remediation – Alert remediation code. Indicates the result of the investigation into the alert
  • state – State of the workflow
changed_by = None
comment = None
last_update_time = None
remediation = None
state = None
class cbapi.psc.models.BaseAlert(cb, model_unique_id, initial_data=None)

Represents a BaseAlert object in the Carbon Black server.

Variables:
  • category – Alert category - Monitored vs Threat
  • create_time – Time the alert was created
  • device_id – ID of the device
  • device_name – Device name
  • device_os – Device OS
  • device_os_version – Device OS Version
  • device_username – Logged on user during the alert. This is filled on a best-effort approach. If the user is not available it may be populated with the device owner
  • first_event_time – Time of the first event in an alert
  • group_details – Group details for when alert grouping is on
  • id – Unique ID for this alert
  • last_event_time – Time of the last event in an alert
  • last_update_time – Time the alert was last updated
  • legacy_alert_id – Unique short ID for this alert. This is deprecated and only available on alerts stored in the old schema.
  • notes_present – Are notes present for this threatId
  • org_key – Unique identifier for the organization to which the alert belongs
  • policy_id – ID of the policy the device was in at the time of the alert
  • policy_name – Name of the policy the device was in at the time of the alert
  • severity – Threat ranking
  • tags – Tags for the alert
  • target_value – Device priority as assigned via the policy
  • threat_id – ID of the threat to which this alert belongs. Threats are comprised of a combination of factors that can be repeated across devices.
  • type – Type of the alert
  • workflow – User-updatable status of the alert
category = None
create_time = None
device_id = None
device_name = None
device_os = None
device_os_version = None
device_username = None
dismiss(remediation=None, comment=None)

Dismiss this alert.

Parameters:
  • str (comment) – The remediation status to set for the alert.
  • str – The comment to set for the alert.
dismiss_threat(remediation=None, comment=None)

Dismiss alerts for this threat.

Parameters:
  • str (comment) – The remediation status to set for the alert.
  • str – The comment to set for the alert.
first_event_time = None
group_details = {}
id = None
last_event_time = None
last_update_time = None
legacy_alert_id = None
notes_present = None
org_key = None
policy_id = None
policy_name = None
primary_key = 'id'
severity = None
tags = []
target_value = None
threat_id = None
type = None
update(remediation=None, comment=None)

Update this alert.

Parameters:
  • str (comment) – The remediation status to set for the alert.
  • str – The comment to set for the alert.
update_threat(remediation=None, comment=None)

Update alerts for this threat.

Parameters:
  • str (comment) – The remediation status to set for the alert.
  • str – The comment to set for the alert.
urlobject = '/appservices/v6/orgs/{0}/alerts'
urlobject_single = '/appservices/v6/orgs/{0}/alerts/{1}'
workflow = {}
workflow_
class cbapi.psc.models.CBAnalyticsAlert(cb, model_unique_id, initial_data=None)

Represents a CBAnalyticsAlert object in the Carbon Black server.

urlobject = '/appservices/v6/orgs/{0}/alerts/cbanalytics'
class cbapi.psc.models.VMwareAlert(cb, model_unique_id, initial_data=None)

Represents a VMwareAlert object in the Carbon Black server.

urlobject = '/appservices/v6/orgs/{0}/alerts/vmware'
class cbapi.psc.models.WatchlistAlert(cb, model_unique_id, initial_data=None)

Represents a WatchlistAlert object in the Carbon Black server.

urlobject = '/appservices/v6/orgs/{0}/alerts/watchlist'
class cbapi.psc.models.WorkflowStatus(cb, model_unique_id, initial_data=None)

Represents a WorkflowStatus object in the Carbon Black server.

Variables:
  • errors – Errors for dismiss alerts or threats, if no errors it won’t be included in response
  • failed_ids – Failed ids
  • id – Time based id for async job, it’s not unique across the orgs
  • num_hits – Total number of alerts to be operated on
  • num_success – Successfully operated number of alerts
  • status – Status for the async progress
  • workflow – Requested workflow change
errors = []
failed_ids = []
finished
id = None
id_
in_progress
num_hits = None
num_success = None
primary_key = 'id'
queued
status = None
urlobject_single = '/appservices/v6/orgs/{0}/workflow/status/{1}'
workflow = {}
workflow_