CB Defense API¶

This page documents the public interfaces exposed by cbapi when communicating with a CB Defense server.

Main Interface¶

To use cbapi with Carbon Black Defense, you will be using the CBDefenseAPI. The CBDefenseAPI object then exposes two main methods to select data on the Carbon Black server:

class cbapi.psc.defense.rest_api.CbDefenseAPI(*args, **kwargs)¶

The main entry point into the Cb Defense 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 CbDefenseAPI
>>> cb = CbDefenseAPI(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.

get_notifications()¶

Retrieve queued notifications (alerts) from the Cb Defense server. Note that this can only be used with a ‘SIEM’ key generated in the Cb Defense console.

Returns:	list of dictionary objects representing the notifications, or an empty list if none available.

notification_listener(interval=60)¶: Generator to continually poll the Cb Defense server for notifications (alerts). Note that this can only be used with a ‘SIEM’ key generated in the Cb Defense console.

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

Queries¶

class cbapi.psc.defense.rest_api.Query(doc_class, cb, query=None)¶

Represents a prepared query to the Cb Defense server.

This object is returned as part of a CbDefenseAPI.select() operation on models requested from the Cb Defense server. You should not have to create this class yourself.

The query is not executed on the server until it’s accessed, either as an iterator (where it will generate values on demand as they’re requested) or as a list (where it will retrieve the entire result set and save to a list). You can also call the Python built-in len() on this object to retrieve the total number of items matching the query.

Examples:

>>> from cbapi.psc.defense import CbDefenseAPI
>>> cb = CbDefenseAPI()

Notes:

The slicing operator only supports start and end parameters, but not step. [1:-1] is legal, but [1:2:-1] is not.
You can chain where clauses together to create AND queries; only objects that match all where clauses will be returned.

and_(q)¶

Add a filter to this query. Equivalent to calling where() on this object.

Parameters:	q (str) – Query string
Returns:	Query object
Return type:	`Query`

where(q)¶

Add a filter to this query.

Parameters:	q (str) – Query string
Returns:	Query object
Return type:	`Query`

Models¶

class cbapi.psc.defense.models.DefenseMutableModel(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶: Represents a DefenseMutableModel object in the Carbon Black server.

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

Represents a Device object in the Carbon Black server.

activationCode = None¶

activationCodeExpiryTime = datetime.datetime(1970, 1, 1, 0, 0)¶

assignedToId = None¶

assignedToName = None¶

avEngine = None¶

avLastScanTime = datetime.datetime(1970, 1, 1, 0, 0)¶

avMaster = None¶

avStatus = []¶

avUpdateServers = []¶

createTime = datetime.datetime(1970, 1, 1, 0, 0)¶

deregisteredTime = datetime.datetime(1970, 1, 1, 0, 0)¶

deviceGuid = None¶

deviceId = None¶

deviceOwnerId = None¶

deviceSessionId = None¶

deviceType = None¶

email = None¶

firstName = None¶

firstVirusActivityTime = datetime.datetime(1970, 1, 1, 0, 0)¶

info_key = 'deviceInfo'¶

lastContact = datetime.datetime(1970, 1, 1, 0, 0)¶

lastExternalIpAddress = None¶

lastInternalIpAddress = None¶

lastLocation = None¶

lastName = None¶

lastReportedTime = datetime.datetime(1970, 1, 1, 0, 0)¶

lastResetTime = datetime.datetime(1970, 1, 1, 0, 0)¶

lastShutdownTime = datetime.datetime(1970, 1, 1, 0, 0)¶

lastVirusActivityTime = datetime.datetime(1970, 1, 1, 0, 0)¶

linuxKernelVersion = 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

messages = []¶

middleName = None¶

name = None¶

organizationId = None¶

organizationName = None¶

osVersion = None¶

passiveMode = None¶

policyId = None¶

policyName = None¶

primary_key = 'deviceId'¶

quarantined = None¶

registeredTime = datetime.datetime(1970, 1, 1, 0, 0)¶

rootedByAnalytics = None¶

rootedByAnalyticsTime = datetime.datetime(1970, 1, 1, 0, 0)¶

rootedBySensor = None¶

rootedBySensorTime = datetime.datetime(1970, 1, 1, 0, 0)¶

scanLastActionTime = datetime.datetime(1970, 1, 1, 0, 0)¶

scanLastCompleteTime = datetime.datetime(1970, 1, 1, 0, 0)¶

scanStatus = None¶

sensorStates = []¶

sensorVersion = None¶

status = None¶

targetPriorityType = None¶

testId = None¶

uninstalledTime = datetime.datetime(1970, 1, 1, 0, 0)¶

urlobject = '/integrationServices/v3/device'¶

vdiBaseDevice = None¶

windowsPlatform = None¶

class cbapi.psc.defense.models.Event(cb, model_unique_id, initial_data=None)¶

Represents a Event object in the Carbon Black server.

info_key = 'eventInfo'¶

primary_key = 'eventId'¶

urlobject = '/integrationServices/v3/event'¶

class cbapi.psc.defense.models.Policy(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)¶

Represents a Policy object in the Carbon Black server.

add_rule(new_rule)¶

delete_rule(rule_id)¶

description = None¶

id = None¶

info_key = 'policyInfo'¶

latestRevision = None¶

name = None¶

policy = {}¶

priorityLevel = None¶

replace_rule(rule_id, new_rule)¶

rules¶

systemPolicy = None¶

urlobject = '/integrationServices/v3/policy'¶

version = None¶