Configuration & Setup

cbinterface will use the same configuration files that CBAPI-Python, and other Carbon Black python libraries use to connect to your configured Carbon Black environments.

First, if you don't already have your environment configured, look here for help configuring the underlying cbapi to work with whatever Carbon Black product and environment setup you have.

Configurations that are specific to cbinferace, such as your default Carbon Black environment (if you have more than one), and your timezone will be saved to a ~/.carbonblack/cbinterface.ini file for persistence.

For Live Response functions, you will need to add a lr_token to your respective Carbon Black profile configurations (instructions below).

API Access

You will need API keys with appropriate permissions to use cbinterface functionality.

If you're using Carbon Black Response, API access is simple to set-up. See these instructions for help.

PSC API Permissions

See the Carbon Black documentation for help creating API keys and Access Levels.

The following table maps what API permissions are required for each area of CbInterface PSC functionality to work. This is for all non-Live Response functionality. Any "DELETE" access level can be omitted if you don't want an analyst to have that capability. If you don't need or want all cbinterface functionality, grant the API permissions necessary for the cbinterface functionality you do want or need.

cbinterface functionality	API Permission Name	Access Level
Process Search & Investigation	org.search.events	READ, CREATE, UPDATE
Universal Binary Store	ubs.org.file, ubs.org.sha256	READ
PSC Device Info	device	READ
PSC Device Quarantine	device.quarantine	Execute
Intel: Feeds	org.feeds	READ
Intel: Watchlists	org.watchlists	READ, UPDATE, CREATE, DELETE
Intel: Migrations	org.watchlists	READ, UPDATE, CREATE
Intel: Alerts	org.alerts*	READ, Execute

NOTE: If you want Live Response functionality, you will need a separate Live Response API key with the LIVE_RESPONSE_API Access Level Type. Instructions are provided, in the next section, for supplying a Live Response token to your configuration.

PSC Adding Live Response Credentials

After you've created a Live Response API credential, you must supply the API Secret Key and API Key ID as the value to a lr_token config item. These credentials should be supplied to your configuration profile like lr_token={API Secret Key}/{API Key ID}.

See the contents of my ~/.carbonblack/credentials.psc config file and notice where a Live Response API token as been provided to my default profile.

$ cat ~/.carbonblack/credentials.psc
[default]
url = https://defense-prod05.conferdeploy.net
token = ABCDEFGHIJKLMNOPQRSTUVWX/ABCDE12345
org_key = ABCDEFGH
ssl_verify = True
lr_token = LMNOPQRSTUVWXABCDEFGHIJK/12345ABCDE

Carbon Black Environment Selection

If you only have a single Carbon Black environment, you likely can skip this section entirely.

If you have more than one environment or your default environment is not named default, you'll have to select/set the environment you want to work with.

You can specify the environment you want to work with via the following argument:

cbinterface -e psc:default

Additionally, you can save your default environment persistence:

cbinterface --set-default-enviroment response:default

# shorthand:
cbinterface -sde response:default

Note that because CbInterface works with multiple Carbon Black products and multiple product environments, the environments are identified as "product:profile" when cbinterface loads the Carbon Black configuration files.

Your Timezone

The default time zone is UTC. You can set your time zone persistence to whatever you want with the --set-default-timezone option:

cbinterface --set-default-timezone Europe/Rome

You can also specify a time zone to convert all timestamps to with the -tz option. This is helpful if you want to see events in different time zones. For example, our team standardized on UTC for Incident Response time-lines.