Harnessing the full power of the Carbon Black API

We work with Carbon Black every day at Red Canary. We are excited to announce the open sourcing of our Python API that allows for deeper and intuitive exploration of the Carbon Black datastore. This “CbApi2” is available at GitHub so everyone can enjoy easy and efficient programmatic access to Carbon Black data.

There are two major design goals behind this API implementation: first, simplify the interface to Carbon Black and remove as much boilerplate code as possible. All results are Python objects with properties (for example a CbBinary or CbProcess) rather than string-based dictionaries. All data types are converted to their native types–for example, date/time stamps are automatically converted to native Python timezone-aware datetime objects. These features greatly simplify code we’ve written to use the Carbon Black API.

The second major design goal is to minimize the number of API queries required to obtain information from the Cb server. This results in increased performance and decreased load on the server. All results are cached, so a script that enumerates many objects doesn’t have to manually track whether a process has been requested already. If a process is requested repeatedly within a period of time, a cached version of that process document is returned rather than requesting the same data from the server again. All queries are lazily evaluated and all attributes lazily requested from the server. A request is only made to the Cb server when the program requests an attribute that’s not already present in the result set.

In summary, these two design goals greatly reduce the amount of code you have to write in order to use the Carbon Black REST API to its full potential. Let’s look at a simple example adapted from the Carbon Black API reference that prints some metadata about every svchost.exe process that executed from a non-system path:

[gist 69834eaf0f681f539b6a]

Note that this program from the API reference has two pain points:

• Almost 50% of the code (3 out of the 8 total lines of code) is boilerplate to enumerate the result set.
• Each process “detail” record results in another request to the server.

The same program using Red Canary’s CbApi2 would look like:
[gist daa877875f63fe1c7d3f]

As you can see in this example, CbApi2 minimizes complexity and allows you to efficiently work with the powerful endpoint data provided by Carbon Black. Stay tuned for future posts around how we use the Carbon Black API in our threat detection service and response. Get the code from Github.