Carbon Black Cloud APIs require authentication to secure your data.
There are a few methods for authentication listed below. Every method requires an API Key. See the Developer Network Authentication Guide to learn how to generate an API Key.
The SDK only uses one API Key at a time. It is recommeded to create API Keys for specific actions, and use them as needed.
For example, if using the Platform Devices API to search for mission critical devices, and the Platform Live Response API to execute commands on those devices, generate one API Key with Custom Access Level with appropriate permissions. Store the Key with profile name, and reference the profile name when creating CBCloudAPI objects.
# 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
Credentials may be stored in a
credentials.cbcfile. 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')
Windows Registry is a secure option for storing API credentials on Windows systems.>>> provider = RegistryCredentialProvider() >>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')
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')
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='defense.conferdeploy.net', token=ABCD/1234, ... org_key='ABCDEFGH')
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. This is an example of a credentials file:
[default] url=http://example.com token=ABCDEFGHIJKLMNOPQRSTUVWX/12345678 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_name=MyScript/0.9.0 [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_name=MyApplication/1.3.1
Individual profiles or sections are delimited in the file by placing their name within square brackets:
each section, individual credential values are supplied in a
Unrecognized keywords are ignored.
By default, the CBC SDK looks for credentials files in the following locations:
.carbonblacksubdirectory of the current directory of the running process.
.carbonblacksubdirectory of the user’s home directory.
/etc/carbonblacksubdirectory on Unix, or the
C:\Windows\carbonblacksubdirectory on Windows.
Within each of these directories, the SDK first looks for the
credentials.cbc file, then the
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
In all cases, you will have to specify the name of the profile to be retrieved from the credentials file in the
profile when creating the
>>> 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
and its containing directory should have
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
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
>>> provider = RegistryCredentialProvider() >>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')
Advanced Usage: The parameters
RegistryCredentialProvider may be used to
control the exact location of the “base” registry key where the sections of credentials are located. The
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
>>> 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.
CBCloudAPI, pass a reference to a
CredentialProvider object in the
parameter. Then pass the name of the profile you want to retrieve from the provider object using the keyword parameter
>>> 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.
The credentials may be passed into the
CBCloudAPI object when it is created via the keyword parameters
org_key, and (optionally)
>>> api = CBCloudAPI(url='https://example.com', token='ABCDEFGHIJKLMNOPQRSTUVWX/12345678', ... org_key='A1B2C3D4', ssl_verify=False, integration_name='MyScript/1.0')
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_SSL_VERIFY. For backwards compatibility with CBAPI, the environment variables
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
CBAPI_TOKEN), and the
credential_file keyword parameter to
CBCloudAPI must be either
None or left
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.
Explanation of API Credential Components¶
||The URL used to access the Carbon Black Cloud.|
||The access token to authenticate with. Same
||The organization key specifying which organization to work with.|
||A Boolean value (see below) indicating whether or not to validate the SSL connection.||
||A Boolean value (see below) indicating whether or not to verify the host name of the server being connected to.||
||A Boolean value (see below). If this is
||A Boolean value (see below). If this is
||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.|
||If specified, this is the name of a proxy host to be used in making the connection.|
||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
When supplying API credentials to the SDK with environmental variables, the credentials include these components:
Alternative keywords are available to maintain backwards compatibility with CBAPI.
Boolean values are specified by using the strings
1 to represent a
True value, or the strings
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