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. The file must be encoded as UTF-8, or as UTF-16 using either
big-endian or little-endian format.
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 |
---|---|---|
|
Yes |
|
|
Yes |
|
|
1 |
No |
|
1 |
No |
|
0 |
No |
|
0 |
No |
|
No |
|
|
No |
|
|
No |
|
|
300000 |
No |
X-AUTH-TOKEN specific fields
Keyword |
Default |
Required |
---|---|---|
|
Yes |
OAuth App with Bearer specific fields
Keyword |
Default |
Required |
---|---|---|
|
Yes |
|
|
Yes |
Personal API Token specific fields
Keyword |
Default |
Required |
---|---|---|
|
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 theC:\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 |
---|---|---|---|
|
|
Yes |
|
|
|
Yes |
|
|
|
1 |
No |
|
|
1 |
No |
|
|
0 |
No |
|
|
0 |
No |
|
|
No |
|
|
|
No |
|
|
|
No |
|
|
|
300000 |
No |
X-AUTH-TOKEN specific fields
Keyword |
Value Type |
Default |
Required |
---|---|---|---|
|
|
Yes |
OAuth App with Bearer specific fields
Keyword |
Value Type |
Default |
Required |
---|---|---|---|
|
|
Yes |
|
|
|
Yes |
Personal API Token specific fields
Keyword |
Value Type |
Default |
Required |
---|---|---|---|
|
|
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:
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 |
---|---|---|---|
|
The URL used to access the Carbon Black Cloud. |
Yes |
|
|
The organization key specifying which organization to work with. |
Yes |
|
|
A Boolean value (see below) indicating whether or not to validate the SSL connection. |
|
No |
|
A Boolean value (see below) indicating whether or not to verify the host name of the server being connected to. |
|
No |
|
A Boolean value (see below). If this is |
|
No |
|
A Boolean value (see below). If this is |
|
No |
|
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 |
|
|
If specified, this is the name of a proxy host to be used in making the connection. |
No |
|
|
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 |
No |
|
|
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 |
---|---|---|
|
The access token to authenticate with. Same
structure as |
Yes |
OAuth App with Bearer specific fields
Keyword |
Definition |
Required |
---|---|---|
|
Client ID, enter the Client ID that you set in Create OAuth 2.0 Client. |
Yes |
|
Client Secret, enter the secret that was generated in Create OAuth 2.0 Client. |
Yes |
Personal API Token specific fields
Keyword |
Definition |
Required |
---|---|---|
|
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 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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