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