Latest Updates: Cb Customer Spotlight Series: Q & A with Integral’s Sean McFeely

Getting Started with the Python CbAPI

Introduction

These instructions will take you from a standard Windows, Linux or macOS 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 install Python on your workstation or server. For best compatibility, install the latest version of Python 3.6.x (as of this writing, that is version 3.6.5). Linux and macOS systems will most likely have Python installed; it will have to be installed on Windows separately.

Note: While Linux and macOS will have Python installed, it might not be an older Python 2.x version. You should install the latest Python 3.x in addition or in a virtualenv. DO NOT replace the original Python installed on your system.

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

$ python --version
Python 3.6.5

$ pip --version
pip 10.0.1 from c:\python36-32\lib\site-packages\pip (python 3.6)

If python --version reports back a version of 3.6.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 3.6.5 installer for Windows 64-bit platforms can be found here.

Install the executable 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 (current version - v1.3.6) introduces a simple command-line script to do this for you. On Linux/macOS, just type cbapi-response configure (or cbapi-protection configure for Cb Protection or cbapi-defense configure for Cb Defense) and follow the prompts. On Windows, open a command prompt and type python c:\python36-32\scripts\cbapi-response configure (where c:\python36-32 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.

Additional Links

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

Cb Response query language: Query Overview

Carbon Black User eXchange Developer community: https://community.carbonblack.com/community/resources/developer-relations

Last modified on June 27, 2018