API Access

Configuring API Access

This section includes

1. How to create an API Key

2. Adding your API Key to your configuration file

If you have already set up CBAPI, skip ahead to Getting Started Out of the Box.

API Key

The toolkit uses CBAPI to communicate with the Carbon Black Cloud. CBAPI requires an API Key. This toolkit communicates with the Unified Binary Store (UBS) and ThreatHunter Feeds. Therefore, your API Key must have access to UBS and Feeds.

This can be achieved by creating a key with API Access Level Type, or with a Custom (RBAC) Access Level with threathunter.feeds , ubs.org.sha256 and ubs.org.file permissions.

Option 1: Create an API Key with API Access Level

Use the preset API Access Level Type to create a new API Key.

Settings -> API Access -> API Keys Tab -> + Add API Key -> Access Level Type Dropdown [API]

Option 2: Create a Custom (RBAC) Access Level

Create a Custom Access Level.

Settings -> API Access -> Access Levels Tab -> + Add Access Level

Select the following permissions:

Dot Notation Name for Permission	Access Levels
threathunter.feeds	READ and UPDATE
ubs.org.sha256	READ
ubs.org.file	READ

Option 2 (continued): Create an API Key with a Custom (RBAC) Access Level

Use the Custom (RBAC) Access Level created above to make a new API Key.

Settings -> API Access -> API Keys Tab -> + Add API Key -> Access Level Type Dropdown [Custom] -> Custom access level dropdown [level with Feeds and UBS permissions]

Once an API Key with the required permissions has been created, it can be used in the toolkit.

Credentials in Configuration File

After creating an API Key with UBS and Feeds access, you must put the key in your configuration file. The toolkit expects an api_token, which is a concatenation of an API Key's Secret Key and Key ID. The values below can be found in your Carbon Black Cloud console, and are unique to your organization and API Key.

Name	Example Value
Org Key	P1Q2R3S4
API Secret Key	ABCDEFGH
API Key ID	1234
api_token	ABCDEFGH/1234

In this example, the carbonblackcloud section of the toolkit configuration file would look similar to this:

carbonblackcloud:
  url: https://defense-prod05.conferdeploy.net
  api_token: ABCDEFGH/1234
  org_key: P1Q2R3S4
  ssl_verify: True
  expiration_seconds: 3600

The toolkit configuration file is covered in detail further down in the guide.

Additional Authentication Information

For more information on API Keys, Access Level Types, and RBAC Permissions, visit the Developer Network Authentication Guide.