Cb Response

Getting Started with the CbAPI

Getting Started with the Carbon Black Python API

These instructions will take you from a standard Windows, Linux or Mac OS X installation to a working Carbon Black API setup from start to finish in three easy steps! For development purposes, we strongly recommend installing the Python API on a workstation or server that is separate from your Carbon Black server.

Get Your REST API token

To get started, you need to acquire a REST API token from the Carbon Black user interface. Log into your Carbon Black server and click your name on the black bar in the top right corner. A popup will appear; click Profile to jump to your user profile page. From there, on the left hand side, you will see a link for API Token. Click that link and a textbox will appear populated with your user’s API token. Each user receives their own, unique API token. This token has the same power and privileges attached to your user and does not expire; so protect it like a password! If your API token is compromised, you can generate a new token by clicking the Reset API Token button; this will also revoke your old, compromised token so it can no longer be used to authenticate to the server.

Install Python

Obviously you’ll need to do is install Python on your workstation or server. For best compatibility, install the latest version of Python 2.7 (as of this writing, that is version 2.7.11). Linux and Mac OS X systems will most likely have Python installed; it will have to be installed on Windows separately.

If you believe you have Python installed already, run the following two commands at a command prompt:

$ python --version
Python 2.7.10

$ pip --version
pip 7.1.2 from /Users/jgarman/Desktop/Reno/homebrew/lib/python2.7/site-packages (python 2.7)

If “python” reports back a version of 2.7.x, you’re in luck. If “pip” is not found, don’t worry, we’ll install that shortly.

On Windows, download the latest Python installer from the python.org website. The direct link for the Python 2.7.11 installer for Windows 64-bit platforms can be found here.

Install the MSI for “all users” and in the configuration options ensure that the “add python.exe to Path” option is installed (you will have to scroll to the end of the customization options to find this).

Install the Python Carbon Black API Python bindings

From a command line prompt, use “pip” to install the API bindings.

$ pip install cbapi

If the “pip” command is not found, use “easy_install” to install pip first, then re-run the “pip” command above:

$ easy_install pip

Configure the API

CbAPI 0.9.3 introduces a simple command-line script to do this for you. On Linux/Mac OS X, just type “cbapi-response configure” (or “cbapi-protection configure” for Cb Protection) and follow the prompts. On Windows, open a command prompt and type “python c:\python27\scripts\cbapi-response configure” (where c:\python27 is the install directory of your Python distribution)

For more details about configuring cbapi credentials file visit our readthedocs

Other Resources

Now that cbapi is installed, you can download some additional tools to aid development

  1. Jupyter (IPython Notebook)
  2. PyCharm
  3. Example scripts on GitHub

Walkthrough of an example script

Let’s go over a simple, but powerful example using the cbapi. Let’s create a csv file with all newly written files and number of executions in the last day. We will go over the example script step-by-step found here

Import the appropriate models and functions needed for our script

from cbapi.response.models import Process, Binary
from cbapi.response import CbEnterpriseResponseAPI

Lets create our query string. Notice how our query string is using an argument passed into the script.

query = "filewrite_md5:* last_update:[" + opts.date + "T00:00:00 TO *]"

So if we want to query for all binaries written in the past day we can do this (Today is 09/30/16):

query = "filewrite_md5:* last_update:["2016-09-29T00:00:00 TO *]"

Initial our query:

process_query = cb.select(Process).where(query)

Note that we haven’t sent the query to the Cb Response Server yet. We only send the query to the Cb Response server when it is absolutely necessary. This is for performance reasons. Now lets create a python set object since we don’t want duplicates.

#
# Create a set so we don't have duplicates
#
md5_list = set()

Let’s iterate through all the queried processes and filemods, then add them to our python set.

#
# Iterate through all the processs
#
for proc in process_query:
    #
    # Iterate through all the filemods
    #
    for fm in proc.filemods:
        #
        # if an md5 exists then save it to our set
        #
        if fm.md5:
            md5_list.add(fm.md5)

Now we need to create a csv file and csv header. Notice that the output file can be an argument.

#
# CSV
#
if not opts.output_file:
    output_file = open("new_binaries_after_date.csv", 'wb')
else:
    output_file = open(opts.output_file, 'wb')

csv_writer = csv.writer(output_file)
csv_writer.writerow(("Binary MD5", 
                     "Binary Link", 
                     "Signature Status", 
                     "Company",
                     "Observed Date", 
                     "Host Count", 
                     "Binary TimeStamp", 
                     "Number of Executions"))

Iterate through our set of md5’s:

#
# Iterate through our set
#
for i, md5 in enumerate(md5_list):

Get a binary object for the md5:

binary = cb.select(Binary, md5)

Now lets see if this binary was executed.

number_of_times_executed = len(cb.select(Process).where("process_md5:{0:s}".format(md5)))

Finally let’s write our to our csv file

csv_writer.writerow((binary.md5,
                     binary.webui_link,
                     binary.digsig_result if binary.digsig_result else "UNSIGNED",
                     binary.company_name,
                     binary.server_added_timestamp,
                     binary.host_count,
                     binary_timestamp,
                     number_of_times_executed))

In summary this script provides a great use case of finding newly created binaries that have potentially executed on your endpoints. It can also provide a good baseline of what kind of binaries are created in your enterprise in the last day.

Carbon Black API GitHub: https://github.com/carbonblack

Cb Response query language: Query overview

Carbon Black User eXchange Developer community: https://community.bit9.com/groups/developer-relations

Last modified on September 30, 2016