Authentication

Carbon Black Cloud APIs require authentication to secure your data.

There are several methods for authentication listed below. Every method requires one of the following type of credentials X-Auth-Token, OAuth App with Bearer or Personal API Token. See the Developer Network Authentication Guide to learn how to generate the type of credentials your implementation uses.

The SDK only uses one Authentication method at a time. It is recommended to create Authentication Methods for specific actions, and use them as needed.

For example, if using the Devices API to search for mission critical devices, and the Live Response API to execute commands on those devices, generate one API credential with appropriate permissions and access level. Store the credential with a profile name, and reference the profile when creating CBCloudAPI objects.

Example contents of credentials.cbc file used for authentication with X-Auth-Token. Read more about the credentials.cbc below.

[platform]
url=https://defense-prod05.conferdeploy.net
token=ABCDEFGHIJKLMNO123456789/ABCD123456
org_key=ABCD123456
ssl_verify=false
ssl_verify_hostname=no

Example code authentication with a profile named “platform”

# import relevant modules
>>> from cbc_sdk.platform import Device
>>> from cbc_sdk import CBCloudAPI

# create Platform API object
>>> platform_api = CBCloudAPI(profile='platform')

# search for specific devices with Platform Devices API
>>> important_devs = platform_api.select(Device).set_target_priorities(["MISSION_CRITICAL"])

# execute commands with Live Response API
>>> for device in important_devs:
...     lr_session = platform_api.live_response.request_session(device.id)
...     lr_session.create_process(r'cmd.exe /c "ping.exe 192.168.1.1"')
...     lr_session.close()

For more examples on Live Response, check Live Response

Authentication Methods

With a File:

Credentials may be stored in a credentials.cbc file. With support for multiple profiles, this method makes it easy to manage multiple API Keys for different products and permission levels.
>>> cbc_api = CBCloudAPI('~/.carbonblack/myfile.cbc', profile='default')

With Windows Registry:

Windows Registry is a secure option for storing API credentials on Windows systems.
>>> provider = RegistryCredentialProvider()
>>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

With macOS’s Keychain Access:

The Keychain Access which is built into macOS can also be used for authentication.
>>> provider = KeychainCredentialProvider('CBC API Credentials', 'default')
>>> cbc_api = CBCloudAPI(credential_provider=provider)

With Amazon Secrets Manger:

There is a support for the Amazon Secrets Manager, navigate to the section for further details of how to set it up.
>>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string')
>>> cbc_api = CBCloudAPI(credential_provider=provider)

With an External Credential Provider:

Credential Providers allow for custom methods of loading API credentials. This method requires you to write your own Credential Provider.
>>> provider = MyCredentialProvider()
>>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

Not Recommended:

At Runtime:

Credentials may be passed into CBCloudAPI() via keyword parameters. This method should be used with caution, taking care to not share your API credentials when managing code with source control.
>>> cbc_api = CBCloudAPI(url='https://defense.conferdeploy.net', token='ABCD/1234',
...     org_key='ABCDEFGH')

Not Recommended:

With Environmental Variables:

Environmental variables can be used for authentication, but pose a security risk. This method is not recommended unless absolutely necessary.

With a File

Credentials may be supplied in a file that resembles a Windows .INI file in structure, which allows for multiple “profiles” or sets of credentials to be supplied in a single file. The file format is backwards compatible with CBAPI, so older files can continue to be used.

Example of a credentials file containing two profiles

[default]
url=http://example.com
token=ABCDEFGHIJKLMNOPQRSTUVWX/12345678
org_key=A1B2C3D4
ssl_verify=false

[production]
url=http://example.com
token=QRSTUVWXYZABCDEFGHIJKLMN/76543210
org_key=A1B2C3D4
ssl_verify=false
ssl_verify_hostname=no
ssl_cert_file=foo.certs
ssl_force_tls_1_2=1
proxy=proxy.example
ignore_system_proxy=on
integration=MyApplication/1.3.1

Common fields between all types of credentials

Keyword	Default	Required
`url`		Yes
`org_key`		Yes
`ssl_verify`	1	No
`ssl_verify_hostname`	1	No
`ignore_system_proxy`	0	No
`ssl_force_tls_1_2`	0	No
`ssl_cert_file`		No
`proxy`		No
`integration`		No
`default_timeout`	300000	No

X-AUTH-TOKEN specific fields

Keyword	Default	Required
`token`		Yes

OAuth App with Bearer specific fields

Keyword	Default	Required
`csp_oauth_app_id`		Yes
`csp_oauth_app_secret`		Yes

Personal API Token specific fields

Keyword	Default	Required
`csp_api_token`		Yes

Individual profiles or sections are delimited in the file by placing their name within square brackets: [profile_name]. Within each section, individual credential values are supplied in a keyword=value format.

Unrecognized keywords are ignored.

By default, the CBC SDK looks for credentials files in the following locations:

The .carbonblack subdirectory of the current directory of the running process.
The .carbonblack subdirectory of the user’s home directory.
The /etc/carbonblack subdirectory on Unix, or the C:\Windows\carbonblack subdirectory on Windows.

Within each of these directories, the SDK first looks for the credentials.cbc file, then the credentials.psc file (the older name for the credentials file under CBAPI).

You can override the file search logic and specify the full pathname of the credentials file in the keyword parameter credential_file when creating the CBCloudAPI object.

In all cases, you will have to specify the name of the profile to be retrieved from the credentials file in the keyword parameter profile when creating the CBCloudAPI object.

Example:

>>> cbc_api = CBCloudAPI(credential_file='~/.carbonblack/myfile.cbc', profile='default')

Note on File Security: It is recommended that the credentials file be secured properly on Unix. It should be owned by the user running the process, as should the directory containing it, and neither one should specify any file permissions for “group” or “other.” In numeric terms, that means the file should have 400 or 600 permissions, and its containing directory should have 500 or 700 permissions. This is similar to securing configuration or key files for ssh. If these permissions are incorrect, a warning message will be logged; a future version of the CBC SDK will disallow access to files altogether if they do not have the correct permissions.

Credential files cannot be properly secured in this manner under Windows; if they are used in that environment, a warning message will be logged.

With Windows Registry

CBC SDK also provides the ability to use the Windows Registry to supply credentials, a method which is more secure on Windows than other methods.

N.B.: Presently, to use the Windows Registry, you must supply its credential provider as an “external” credential provider. A future version of the CBC SDK will move to using this as a default provider when running on Windows.

By default, registry entries are stored under the key HKEY_CURRENT_USER\Software\VMware Carbon Black\Cloud Credentials. Under this key, there may be multiple subkeys, each of which specifies a “profile” (as with credential files). Within these subkeys, the following named values may be specified:

Common fields between all types of credentials

Keyword	Value Type	Default	Required
`url`	`REG_SZ`		Yes
`org_key`	`REG_SZ`		Yes
`ssl_verify`	`REG_DWORD`	1	No
`ssl_verify_hostname`	`REG_DWORD`	1	No
`ignore_system_proxy`	`REG_DWORD`	0	No
`ssl_force_tls_1_2`	`REG_DWORD`	0	No
`ssl_cert_file`	`REG_SZ`		No
`proxy`	`REG_SZ`		No
`integration`	`REG_SZ`		No
`default_timeout`	`REG_DWORD`	300000	No

X-AUTH-TOKEN specific fields

Keyword	Value Type	Default	Required
`token`	`REG_SZ`		Yes

OAuth App with Bearer specific fields

Keyword	Value Type	Default	Required
`csp_oauth_app_id`	`REG_SZ`		Yes
`csp_oauth_app_secret`	`REG_SZ`		Yes

Personal API Token specific fields

Keyword	Value Type	Default	Required
`csp_api_token`	`REG_SZ`		Yes

Unrecognized named values are ignored.

To use the Registry credential provider, create an instance of it, then pass the reference to that instance in the credential_provider keyword parameter when creating CBCloudAPI. As with credential files, the name of the profile to be retrieved from the Registry should be specified in the keyword parameter profile.

Example:

>>> provider = RegistryCredentialProvider()
>>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

Advanced Usage: The parameters keypath and userkey to RegistryCredentialProvider may be used to control the exact location of the “base” registry key where the sections of credentials are located. The keypath parameter allows specification of the path from HKEY_CURRENT_USER where the base registry key is located. If userkey, which is True by default, is False, the path will be interpreted as being rooted at HKEY_LOCAL_MACHINE rather than HKEY_CURRENT_USER.

Example:

>>> provider = RegistryCredentialProvider('Software\\Contoso\\My CBC Application')
>>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

Note the use of doubled backslashes to properly escape them under Python.

With an External Credential Provider

Credentials may also be supplied by writing a class that conforms to the CredentialProvider interface protocol. When creating CBCloudAPI, pass a reference to a CredentialProvider object in the credential_provider keyword parameter. Then pass the name of the profile you want to retrieve from the provider object using the keyword parameter profile.

Example:

>>> provider = MyCredentialProvider()
>>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

Details of writing a credential provider may be found in the Developing a Custom Credential Provider document.

At Runtime

The credentials may be passed into the CBCloudAPI object when it is created via the keyword parameters url, token, org_key, and (optionally) ssl_verify and integration_name.

Example:

>>> api = CBCloudAPI(url='https://example.com', token='ABCDEFGHIJKLMNOPQRSTUVWX/12345678',
...                  org_key='A1B2C3D4', ssl_verify=False, integration_name='MyScript/1.0')

The integration_name may be specified even if using another credential provider. If specified as a parameter, this overrides any integration name specified by means of the credential provider.

With Environmental Variables

The credentials may be supplied to CBC SDK via the environment variables CBC_URL, CBC_TOKEN, CBC_ORG_KEY, and CBC_SSL_VERIFY. For backwards compatibility with CBAPI, the environment variables CBAPI_URL, CBAPI_TOKEN, CBAPI_ORG_KEY, and CBAPI_SSL_VERIFY may also be used; if both are specified, the newer CBC_xxx environment variables override their corresponding CBAPI_xxx equivalents. To use the environment variables, they must be set before the application is run (at least CBC_URL or CBAPI_URL, and CBC_TOKEN or CBAPI_TOKEN), and the credential_file keyword parameter to CBCloudAPI must be either None or left unspecified. (The profile keyword parameter will be ignored.)

N.B.: Passing credentials via the environment can be insecure, and, if this method is used, a warning message to that effect will be generated in the log.

With macOS’s Keychain Access

The SDK also supports the usage of macOS’s Keychain Access. It works in a similar manner as our other authentication methods. Keychain Access is a key-value based password storage and since we have more than one key-value based entry we are going to use JSON to store our other entries, the JSON is going to be stored under the password value.

Note

You can start first by creating the JSON object, you can do that by using our CLI tool(<SDK_ROOT>/bin/set-macos-keychain.py) or by manually creating it. The tool can:

Automatically import all of your profiles set in the credentials.cbc file. Or by setting a custom path to a file.

Manually input the values of your credentials via prompt or by using system arguments.

Find out how to use the script in its docstring or by using --help.

You can remove the keys that you won’t be using or leave them empty. Reference our Explanation of API Credential Components.

{
    "url": "<URL>",
    "token" : "<TOKEN>",
    "org_key": "<ORG_KEY>",
    "ssl_verify": true,
    "ssl_verify_hostname": true,
    "ssl_cert_file": "<FILE_PATH>",
    "ssl_force_tls_1_2": true,
    "proxy": "<NAME_OF_THE_PROXY_HOST>",
    "ignore_system_proxy": true,
    "integration": "<INTEGRATION_NAME>",
    "default_timeout": 300000
}

Note

When you are storing a JSON object under the password’s input in Keychain it is possible to see only the { in the input field, you can navigate with the arrows to check if the rest of the JSON is there.

Then we can move to storing that entry into the Keychain, create a new entry which looks like that:

Storing a new entry into the Keychain Access

After we’ve set the entry in the Keychain Access we can now authenticate our SDK using the KeychainCredentialProvider.

>>> from cbc_sdk.credential_providers import KeychainCredentialProvider
>>> provider = KeychainCredentialProvider('CBC API Credentials', 'default')
>>> cbc_api = CBCloudAPI(credential_provider=provider)

You will be prompted to type your password so that python can access the keychain in order to obtain the credentials.

With Amazon Secrets Manger

Configure the AWS credentials

A full and comprehensive guide configuring the files and credentials regarding AWS can be found in their official documentation.

Adding a secret to the AWS Secrets Manager

There is an official guide for creating a secret by AWS.

Note

Add your secrets as a key/value pairs. In the Explanation of API Credential Components you can find full information on required fields and their purpose.

Using our credential provider for the SDK

After the configuration of the AWS Credentials and storing your secret in the AWS Secret Manager, we can start using the credential provider.

>>> from cbc_sdk.credential_providers import AWSCredentialProvider
>>> from cbc_sdk import CBCloudAPI
>>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string')
>>> cbc_api = CBCloudAPI(credential_provider=provider)

AWS Single Sign-On Provider (SSO)

If you wish to set the SSO provider follow this tutorial for setting the config.

Then you can use the profile_name attribute in the AWSCredentialProvider like so:

>>> from cbc_sdk.credential_providers import AWSCredentialProvider
>>> from cbc_sdk import CBCloudAPI
>>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string', profile_name="my-sso-profile")
>>> cbc_api = CBCloudAPI(credential_provider=provider)

Explanation of API Credential Components

When supplying API credentials to the SDK at runtime, with a file, or with Windows Registry, the credentials include these components:

Common fields between X-Auth-Token, OAuth App with Bearer and Personal API Token authentication methods

Keyword	Definition	Default	Required
`url`	The URL used to access the Carbon Black Cloud.		Yes
`org_key`	The organization key specifying which organization to work with.		Yes
`ssl_verify`	A Boolean value (see below) indicating whether or not to validate the SSL connection.	`True`	No
`ssl_verify_hostname`	A Boolean value (see below) indicating whether or not to verify the host name of the server being connected to.	`True`	No
`ignore_system_proxy`	A Boolean value (see below). If this is `True`, any system proxy settings will be ignored in making the connection to the server.	`False`	No
`ssl_force_tls_1_2`	A Boolean value (see below). If this is `True`, the connection will be forced to use TLS 1.2 rather than any later version.	`False`	No
`ssl_cert_file`	The name of an optional certificate file used to validate the certificates of the SSL connection. If not specified, the standard system certificate verification will be used.		No
`proxy`	If specified, this is the name of a proxy host to be used in making the connection.		No
`integration`	The name of the integration to use these credentials. The string may optionally end with a slash character, followed by the integration’s version number. Passed as part of the `User-Agent:` HTTP header on all requests made by the SDK.		No
`default_timeout`	The default timeout for search queries, specified in milliseconds. This value may never be greater than the default of 300000 milliseconds.	300000	No

X-AUTH-TOKEN specific fields

Keyword	Definition	Required
`token`	The access token to authenticate with. Same structure as `X-Auth-Token` defined in the Developer Network Authentication Guide. Derived from an API Key’s Secret Key and API ID.	Yes

OAuth App with Bearer specific fields

Keyword	Definition	Required
`csp_oauth_app_id`	Client ID, enter the Client ID that you set in Create OAuth 2.0 Client.	Yes
`csp_oauth_app_secret`	Client Secret, enter the secret that was generated in Create OAuth 2.0 Client.	Yes

Personal API Token specific fields

Keyword	Definition	Required
`csp_api_token`	API tokens are issued by users in an organization and are associated with the user’s account and the organization from which they generated the API token.	Yes

When supplying API credentials to the SDK with environmental variables, the credentials include these components:

Keyword	Legacy	Default
`CBC_URL`	`CBAPI_URL`
`CBC_TOKEN`	`CBAPI_TOKEN`
`CBC_ORG_KEY`	`CBAPI_ORG_KEY`
`CBC_SSL_VERIFY`	`CBAPI_SSL_VERIFY`	`True`

Alternative keywords are available to maintain backwards compatibility with CBAPI.

Boolean Values

Boolean values are specified by using the strings true, yes, on, or 1 to represent a True value, or the strings false, no, off, or 0 to represent a False value. All of these are case-insensitive. Any other string value specified will result in an error.

For example, to disable SSL connection validation, any of the following would work:

ssl_verify=False
ssl_verify=false
ssl_verify=No
ssl_verify=no
ssl_verify=Off
ssl_verify=off
ssl_verify=0