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


>>> from cbapi import CbDefenseAPI
>>> cb = CbDefenseAPI(profile="production")
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

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.

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.

  • 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

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


class cbapi.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.


>>> from cbapi.defense import CbDefenseAPI
>>> cb = CbDefenseAPI()
  • 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.

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

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

Add a filter to this query.

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


class cbapi.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.defense.models.Device(cb, model_unique_id, initial_data=None)

Represents a Device object in the Carbon Black server.

activationCode = None
activationCodeExpiryTime = None
assignedToId = None
assignedToName = None
avEngine = None
avLastScanTime = None
avMaster = None
avStatus = []
avUpdateServers = []
createTime = None
deregisteredTime = None
deviceGuid = None
deviceId = None
deviceOwnerId = None
deviceSessionId = None
deviceType = None
email = None
firstName = None
firstVirusActivityTime = None
info_key = 'deviceInfo'
lastContact = None
lastExternalIpAddress = None
lastInternalIpAddress = None
lastLocation = None
lastName = None
lastReportedTime = None
lastResetTime = None
lastShutdownTime = None
lastVirusActivityTime = None
linuxKernelVersion = None

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 = None
rootedByAnalytics = None
rootedByAnalyticsTime = None
rootedBySensor = None
rootedBySensorTime = None
scanLastActionTime = None
scanLastCompleteTime = None
scanStatus = None
sensorStates = []
sensorVersion = None
status = None
targetPriorityType = None
testId = None
uninstalledTime = None
urlobject = '/integrationServices/v3/device'
vdiBaseDevice = None
windowsPlatform = None
class cbapi.defense.models.Event(cb, model_unique_id, initial_data=None)

Represents a Event object in the Carbon Black server.

primary_key = 'eventId'
urlobject = '/integrationServices/v3/event'