Skip to content
Sean McFeely edited this page Apr 20, 2021 · 6 revisions

CbInterface

cbinterface is a command line tool and library for interfacing with Carbon Black environments.

This Wiki documents functionality and includes some examples in a How-To Guide for common use cases and problems.

Please read the README before proceeding in this wiki.

Who is this tool for?

IDR teams seeking to maximize the value of their Carbon Black deployment(s), analysts who are command line first, developers tasked with enabling IDR Analysts.

Why did I create this tool?

I originally built this tool for myself a few years ago when we onboarded one of the first versions of the Carbon Black Response product. I wanted to master the dataset and that meant asking questions of the dataset (searching), and diving into the results (carving and making sense of process events), as fast as possible. This meant NOT using the GUI. The power of the command line enables us to dive, dissect, carve, and automate... and that's what I needed to turn the dataset it into the tip of an agile detection spear.

Now cbinterface enables analysts to rapidly ask and answer questions of the Carbon Black dataset, to quickly investigate non-automated correlations, and then automate answers into new correlations that can populate results into their favorite SOAR or SOAR-like detection platform, like the Analysis Correlation Engine. Next, they identify and tune bad detections, as well as, rapidly create new ones.

However, more than that, cbinterface:

  • allows for routine Live Response actions to be scripted into playbooks. For example, when a detection is made an event trigger can point to a LR script to perform (ex: collect a file) on an endpoint.
  • Endpoints to be contained for safe investigations.
  • Endpoints to be remediated of malicious infections in a scripted manner (which helps defeat watchdog processes and tricky persistent mechanisms).
  • Help managing intel and detections.
  • Migrating Response Watchlists to PSC EDR.
  • and more that this wiki intends to document.

Not satisfied by that why? On Information Security ...

The endpoint metadata provided by Carbon Black tools provides fantastic visibility into what's happening on organization endpoints. However, you have to make sense of all of the noise and all of the signals to capture the most value, and that value is in the form of capturing attack surface coverage while routinely minimizing false positive signals. Keep in mind that you do not have to look at every alert a platform generates. IDR or CSIRT teams should be treating platform alerts like signals and "hunting" those signals programmatically for what you deem is suspicious enough that a human should look at it. You have to decide what is worthy of a human's time, and then call those your "alerts". After you've done that, the postulate remains that 99% of those "alerts" will be some form of false positive. Knowing this, we must enable analysts to disposition (make a determination) about the alerts they look at as fast as humanly possible. Otherwise, coverage of your attack surface will suffer and true positives will get lost in the noise. This is of course where SOAR comes in to help by adding as much context as possible to the alerts humans are looking at. Due to the nature of computers and user behavior, this context can be tricky to capture for endpoint process metadata. For this reason, tools like cbinterface allow analysts to "look under the hood" and perform their manual analysis and correlations when an alert raises their suspicions but they're still lacking confidence on the vitality of their suspicions. cbinterface enables analyst to go faster, and the time savings are of great value.

CLI Navigation

The tool has a lot of nested options, so -h is your friend and tabbed auto-completion works. There are also command aliases.

NOTE: If you only have PSC configured, you will only see PSC specific functionality; if you only have Response configured, you will only see Response specific functionality. This means you will not see the following base level commands unless you have both a Response and PSC environment configured.

The base level command entry point:

$ cbinterface -h
usage: cbinterface [-h] [-d] [-e {response:acme,psc:acme}]
                          [-sde {response:acme,psc:acme}]
                          [-tz TIME_ZONE]
                          [--set-default-timezone SET_DEFAULT_TIMEZONE]
                          {query,pq,q,investigate,proc,i,live-response,lr,session,enumerate,e,sensor-query,sq,response_watchlist,rwl,device,d,ubs,intel}
                          ...

Interface to Carbon Black for IDR teams.

positional arguments:
  {query,pq,q,investigate,proc,i,live-response,lr,session,enumerate,e,sensor-query,sq,response_watchlist,rwl,device,d,ubs,intel}
    query (pq, q)       Execute a process search query. 'query -h' for more
    investigate (proc, i)
                        Investigate process events and metadata.
    live-response (lr)  Perform live response actions on a device/sensor.
    session             Interact with Cb live response server sessions.
    enumerate (e)       Data enumerations for answering common questions.
    sensor-query (sq)   Execute a sensor query (Response). Valid search
                        fields: 'ip', 'hostname', and 'groupid'
    response_watchlist (rwl)
                        Work with response watchlists.
    device (d)          Execute a device query (PSC).
    ubs                 Interface with the Universal Binary Store (UBS) to
                        download files and/or get information.
    intel               Intel Feeds, Watchlists, Reports, & IOCs

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           Turn on debug logging.
  -e {response:acme,psc:acme}, --environment {response:acme,psc:acme}
                        specify an environment to work with.
                        Default=psc:acme
  -sde {response:acme,psc:acme}, --set-default-environment {response:acme,psc:acme}
                        configure your default Cb environment
  -tz TIME_ZONE, --time-zone TIME_ZONE
                        specify the timezone to override defaults. ex.
                        "US/Eastern" or "Europe/Rome"
  --set-default-timezone SET_DEFAULT_TIMEZONE
                        configure your default timezone. ex. "US/Eastern" or
                        "Europe/Rome"