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")
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
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
assignedToId = None
assignedToName = None
avEngine = None
avLastScanTime
avMaster = None
avStatus = []
avUpdateServers = []
createTime
deregisteredTime
deviceGuid = None
deviceId = None
deviceOwnerId = None
deviceSessionId = None
deviceType = None
email = None
firstName = None
firstVirusActivityTime
info_key = 'deviceInfo'
lastContact
lastExternalIpAddress = None
lastInternalIpAddress = None
lastLocation = None
lastName = None
lastReportedTime
lastResetTime
lastShutdownTime
lastVirusActivityTime
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
rootedByAnalytics = None
rootedByAnalyticsTime
rootedBySensor = None
rootedBySensorTime
scanLastActionTime
scanLastCompleteTime
scanStatus = None
sensorStates = []
sensorVersion = None
status = None
targetPriorityType = None
testId = None
uninstalledTime
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