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.

api_json_request(method, uri, **kwargs)¶

Submit a request to the server.

Args:: method (str): HTTP method to use. uri (str): URI to submit the request to. **kwargs (dict): Additional arguments.
Returns:: object: Result of the operation.
Raises:: ServerError: If there’s an error output from the server.

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)¶

Create a new object.

Args:: cls (class): The Model class (only some models can be created, for example, Feed, Notification, …) data (object): The data used to initialize the new object
Returns:: Model: An empty instance of the model class.
Raises:: ApiError: If the Model cannot be created.

delete_object(uri)¶

Send a DELETE request to the specified URI.

Args:: uri (str): The URI to send the DELETE request to.
Returns:: object: The return data from the DELETE request.

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.

get_object(uri, query_parameters=None, default=None)¶

Submit a GET request to the server and parse the result as JSON before returning.

Args:: uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response.
Returns:: object: Result of the GET request.

get_raw_data(uri, query_parameters=None, default=None, **kwargs)¶

Submit a GET request to the server and return the result without parsing it.

Args:: uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response. **kwargs:
Returns:: object: Result of the GET request.

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.

post_object(uri, body, **kwargs)¶

Send a POST request to the specified URI.

Args:: uri (str): The URI to send the POST request to. body (object): The data to be sent in the body of the POST request. **kwargs:
Returns:: object: The return data from the POST request.

put_object(uri, body, **kwargs)¶

Send a PUT request to the specified URI.

Args:: uri (str): The URI to send the PUT request to. body (object): The data to be sent in the body of the PUT request. **kwargs:
Returns:: object: The return data from the PUT request.

raise_unless_json(ret, expected)¶

Raise a ServerError unless we got back an HTTP 200 response with JSON containing all the expected values.

Args:: ret (object): Return value to be checked. expected (dict): Expected keys and values that need to be found in the JSON response.
Raises:: ServerError: If the HTTP response is anything but 200, or if the expected values are not found.

select(cls, unique_id=None, *args, **kwargs)¶

Prepare a query against the Carbon Black data store.

Args:: 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 *args: **kwargs:
Returns:: object: An instance of the Model class if a unique_id is provided, otherwise a Query object

url¶

Return the connection URL.

Returns:: str: The connection URL.

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¶