CB Response API¶

This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black Enterprise Response server.

Main Interface¶

To use cbapi with Carbon Black Response, you will be using the CbResponseAPI. The CbResponseAPI object then exposes two main methods to access data on the Carbon Black server: select and create.

class cbapi.response.rest_api.CbResponseAPI(*args, **kwargs)¶

The main entry point into the Carbon Black Enterprise Response API. Note that calling this will automatically connect to the Carbon Black server in order to verify connectivity and get the server version.

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.
url (str) – (optional, discouraged) Instead of using a credential profile, pass URL and API token to the constructor.
token (str) – (optional, discouraged) API token
ssl_verify (bool) – (optional, discouraged) Enable or disable SSL certificate verification

Usage:

>>> from cbapi import CbEnterpriseResponseAPI
>>> cb = CbEnterpriseResponseAPI(profile="production")

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.

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.

create_new_partition()¶

Create a new Solr time partition for event storage. Available in Cb Response 6.1 and above. This will force roll-over current hot partition into warm partition (by renaming it to a time-stamped name) and create a new hot partition (“writer”).

Returns:	Nothing if successful.
Raises:	ApiError – if there was an error creating the new partition. ServerError – if there was an error creating the new partition.

dashboard_statistics()¶

Retrieve dashboard statistics from the Carbon Black Enterprise Response server.

Returns:	Dictionary with information retrieved from the `/api/v1/dashboard/statistics` API route
Return type:	dict

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.

from_ui(uri)¶

Retrieve a Carbon Black Enterprise Response object based on URL from the Carbon Black Enterprise Response web user interface.

For example, calling this function with https://server/#/analyze/00000001-0000-0554-01d1-3bc4553b8c9f/1 as the uri argument will return a new :py:class: cbapi.response.models.Process class initialized with the process GUID from the URL.

Parameters:	uri (str) – Web browser URL from the Cb web interface
Returns:	the appropriate model object for the URL provided
Raises:	ApiError – if the URL does not correspond to a recognized model object

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.

info()¶

Retrieve basic version information from the Carbon Black Enterprise Response server.

Returns:	Dictionary with information retrieved from the `/api/info` API route
Return type:	dict

license_request()¶

Retrieve license request block from the Carbon Black Enterprise Response server.

Returns:	License request block
Return type:	str

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

update_license(license_block)¶

Upload new license to the Carbon Black Enterprise Response server.

Parameters:	license_block (str) – Licence block provided by Carbon Black support
Raises:	ServerError – if the license is not accepted by the Carbon Black server

url¶

Return the connection URL.

Returns:: str: The connection URL.

Queries¶

class cbapi.response.query.Query(doc_class, cb, query=None, raw_query=None)¶

Represents a prepared query to the Carbon Black Enterprise Response server.

This object is returned as part of a CbEnterpriseResponseAPI.select() operation on Process and Binary objects from the Carbon Black Enterprise Response 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.

The syntax for query :py:meth:where and :py:meth:sort methods can be found in the Query Reference posted on the Carbon Black Developer Network website.

Examples:

>>> cb = CbEnterpriseResponseAPI()
>>> query = cb.select(Process)                      # returns a Query object matching all Processes
>>> query = query.where("process_name:notepad.exe") # add a filter to this Query
>>> query = query.sort("last_update desc")          # sort by last update time, most recent first
>>> for proc in query:                              # uses the iterator to retrieve all results
>>>     print("{0} {1}".format(proc.username, proc.hostname))
>>> processes = query[:10]                          # retrieve the first ten results
>>> len(query)                                      # retrieve the total count

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_(new_query)¶

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

Parameters:	new_query (str) – Query string - see the Query Reference.
Returns:	Query object
Return type:	`Query`

facets(*args)¶

Retrieve a dictionary with the facets for this query.

Parameters:	args – Any number of fields to use as facets
Returns:	Facet data
Return type:	dict

sort(new_sort)¶

Set the sort order for this query.

Parameters:	new_sort (str) – New sort order - see the Query Reference.
Returns:	Query object
Return type:	`Query`

where(new_query)¶

Add a filter to this query.

Parameters:	new_query (str) – Query string - see the Query Reference.
Returns:	Query object
Return type:	`Query`

class cbapi.response.models.ProcessQuery(doc_class, cb, query=None, raw_query=None)¶

group_by(field_name)¶

Set the group-by field name for this query. Typically, you will want to set this to ‘id’ if you only want one result per process.