cbapi: Carbon Black API for Python¶
CBAPI provides a straightforward interface to the VMware Carbon Black products: Carbon Black EDR, Carbon Black App Control, and Carbon Black Cloud Endpoint Standard(formerly CB Response, CB Protection, and CB Defense). This library provides a Pythonic layer to access the raw power of the REST APIs of all Carbon Black products, making it easier to query data from any platform or on-premise APIs, combine data from multiple API calls, manage all API credentials in one place, and manipulate data as Python objects. Take a look:
>>> from cbapi.response import CbResponseAPI, Process, Binary, Sensor >>> # >>> # Create our EDR API object >>> # >>> c = CbResponseAPI() >>> # >>> # take the first process that ran notepad.exe, download the binary and read the first two bytes >>> # >>> c.select(Process).where('process_name:notepad.exe').first().binary.file.read(2) 'MZ' >>> # >>> # if you want a specific ID, you can put it straight into the .select() call: >>> # >>> binary = c.select(Binary, "24DA05ADE2A978E199875DA0D859E7EB") >>> # >>> # select all sensors that have ran notepad >>> # >>> sensors = set() >>> for proc in c.select(Process).where('process_name:evil.exe'): ... sensors.add(proc.sensor) >>> # >>> # iterate over all sensors and isolate >>> # >>> for s in sensors: ... s.network_isolation_enabled = True ... s.save()
If you’re a Carbon Black App Control customer (formerly CB Protection), you may use:
>>> from cbapi.protection.models import FileInstance >>> from cbapi.protection import CbProtectionAPI >>> # >>> # Create our App Control API object >>> # >>> p = CbProtectionAPI() >>> # >>> # Select the first file instance >>> # >>> fi = p.select(FileInstance).first() >>> # >>> # print that computer's hostname. This automatically "joins" with the Computer API object. >>> # >>> fi.computer.name u'DOMAIN\\MYHOSTNAME' >>> # >>> # change the policy ID >>> # >>> fi.computer.policyId = 3 >>> fi.computer.save()
As of version 1.2, CBAPI also supports Carbon Black Cloud Endpoint Standard (formerly CB Defense):
>>> from cbapi.psc.defense import * >>> # >>> # Create our Cloud Endpoint Standard API object >>> # >>> p = CbDefenseAPI() >>> # >>> # Select any devices that have the hostname WIN-IA9NQ1GN8OI and an internal IP address of 192.168.215.150 >>> # >>> devices = c.select(Device).where('hostNameExact:WIN-IA9NQ1GN8OI').and_("ipAddress:192.168.215.150").first() >>> # >>> # Change those devices' policy into the Windows_Restrictive_Workstation policy. >>> # >>> for dev in devices: >>> dev.policyName = "Restrictive_Windows_Workstation" >>> dev.save()
- Enhanced Live Response API
- The new CBAPI now provides a robust interface to the Carbon Black EDR Live Response capability. Easily create Live Response sessions, initiate commands on remote hosts, and pull down data as necessary to make your Incident Response process much more efficient and automated.
- Consistent API across VMware Carbon Black platforms
- CBAPI supports Carbon Black EDR, Carbon Black App Control, and Carbon Black Cloud Endpoint Standard customers from a single API layer. Even better, the object model is the same for all three, and if you know one API, you can easily transition to another. CBAPI manages the differences among the three REST APIs behind a single, consistent Python-like interface.
- Enhanced Performance
- CBAPI now provides a built in caching layer to reduce the query load on the Carbon Black server. This is especially useful when taking advantage of CBAPI’s new “joining” features. You can transparently access, for example, the binary associated with a given process in Carbon Black EDR. Since many processes may be associated with the same binary, it does not make sense to repeatedly request the same binary information from the server over and over again. Therefore CBAPI now caches this information to avoid unnecessary requests.
- Reduce Complexity
- CBAPI provides a friendly interface for accessing Carbon Black data. This greatly improves developer productivity and lowers the bar to entry.
- Python 3 and Python 2 compatible
- Use all the new features and modules available in Python 3 with CBAPI. This module is compatible with Python versions 2.6.6 and above, 2.7.x, 3.4.x, and 3.5.x.
- Better support for multiple CB servers
- CBAPI introduces the concept of Credential Profiles; named collections of URL, API keys, and optional proxy configuration for connecting to any number of Carbon Black EDR, Carbon Black App Control, or Carbon Black Cloud Endpoint Standard servers.
CBAPI version 0.9.0 enforces the use of credential files.
In order to perform any queries via the API, you will need to get the API token for your CB user. See the documentation on the Developer Network website on how to acquire the API token for Carbon Black EDR (CB Response), Carbon Black App Control (CB Protection), or Carbon Black Cloud Endpoint Standard (CB Defense).
Once you acquire your API token, place it in one of the default credentials file locations:
For distinction between credentials of different Carbon Black products, use the following naming convention for your credentials files:
credentials.pscfor Carbon Black Cloud Endpoint Standard, Audit & Remediation, and Enterprise EDR (CB Defense, CB LiveOps, and CB ThreatHunter)
credentials.responsefor Carbon Black EDR (CB Response)
credentials.protectionfor Carbon Black App Control (CB Protection)
For example, if you use a Carbon Black Cloud product, you should have created a credentials file in one of these locations:
Credentials found in a later path will overwrite earlier ones.
The credentials are stored in INI format. The name of each credential profile is enclosed in square brackets, followed by key-value pairs providing the necessary credential information:
[default] url=https://localhost token=abcdef0123456789abcdef ssl_verify=False [prod] url=https://cbserver.prod.corp.com token=aaaaaa ssl_verify=True [otheruser] url=https://localhost token=bbbbbb ssl_verify=False
The possible options for each credential profile are:
- url: The base URL of the Carbon Black server. This should include the protocol (https) and the hostname, and nothing else.
- token: The API token for the user ID. More than one credential profile can be specified for a given server, with different tokens for each.
- ssl_verify: True or False; controls whether the SSL/TLS certificate presented by the server is validated against the local trusted CA store.
- org_key: The organization key. This is required to access the Carbon Black Cloud, and can be found in the console. The format is
- proxy: A proxy specification that will be used when connecting to the Carbon Black server. The format is:
http://myusername:firstname.lastname@example.org:8001/where the hostname of the proxy is
proxy.company.com, port 8001, and using username/password
- ignore_system_proxy: If you have a system-wide proxy specified, setting this to True will force CBAPI to bypass the proxy and directly connect to the Carbon Black server.
Future versions of CBAPI will also provide the ability to “pin” the TLS certificate so as to provide certificate verification on self-signed or internal CA signed certificates.
Environment Variable Support
The latest CBAPI for Python supports specifying API credentials in the following three environment variables:
CBAPI_TOKEN the envar for holding the EDR (CbR) or App Control (CbP) api token or the ConnectorId/APIKEY combination for Endpoint Standard (CB Defense)/Carbon Black Cloud.
The CBAPI_URL envar holds the FQDN of the target, an EDR (CbR), CBD, or CbD/Carbon Black Cloud server specified just as they are in the configuration file format specified above.
The optional CBAPI_SSL_VERIFY envar can be used to control SSL validation(True/False or 0/1), which will default to ON when not explicitly set by the user.
For environments where complex outbound network filters and proxy configurations are used (eg. anything other than an unauthenticated or basic password authenticated proxy) a prepared requests.Session object may be supplied as a proxy_session parameter. This session will then be used for all communication with the API. Construction of such a Session is beyond the scope of this document, consult your local network/security administrators for assistance.
Backwards & Forwards Compatibility¶
The previous versions (0.8.x and earlier) of CBAPI and bit9Api are now deprecated and will no longer receive updates. However, existing scripts will work without change as CBAPI includes both in its legacy package. The legacy package is imported by default and placed in the top level CBAPI namespace when the CBAPI module is imported on a Python 2.x interpreter. Therefore, scripts that expect to import cbapi.CbApi will continue to work exactly as they had previously.
Since the old API was not compatible with Python 3, the legacy package is not importable in Python 3.x and therefore legacy scripts cannot run under Python 3.
Once CBAPI 1.0.0 is released, the old
cbapi.legacy.CbApi will be deprecated and removed entirely no earlier
than January 2017.
New scripts should use the
(for Carbon Black EDR (CB Response)),
(for Carbon Black App Control (CB Protection)), or
cbapi.defense.rest_api.CbDefenseAPI API entry points.
The API is frozen as of version 1.0; any changes in the 1.x version branch will be additions/bug fixes only. Breaking changes to the API will increment the major version number (2.x).
Get started with CBAPI here. For detailed information on the objects and methods exposed by CBAPI, see the full API Documentation below.
- Getting Started
- Logging & Diagnostics
- EDR (CB Response) API Examples
- CbAPI and Live Response
- CbAPI Changelog
- CbAPI 1.7.7 - Release Jan 28, 2022
- CbAPI 1.7.6 - Release Dec 20, 2021
- CbAPI 1.7.5 - Released June 16, 2021
- CbAPI 1.7.4 - Released April 7, 2021
- CbAPI 1.7.3 - Released January 15, 2021
- CbAPI 1.7.2 - Released July 22, 2020
- CbAPI 1.7.1 - Released July 22, 2020
- CbAPI 1.7.0 - Released July 14, 2020
- CbAPI 1.6.2 - Released April 08, 2020
- CbAPI 1.6.1 - Released January 13, 2020
- CbAPI 1.6.0 - Released December 3, 2019
- CbAPI 1.5.6 - Released November 19, 2019
- CbAPI 1.5.5 - Released November 12, 2019
- CbAPI 1.5.4 - Released October 24, 2019
- CbAPI 1.5.3 - Released October 15, 2019
- CbAPI 1.5.2 - Released September 9, 2019
- CbAPI 1.5.1 - Released July 23, 2019
- CbAPI 1.5.0 - Released July 23, 2019
- CbAPI 1.4.5 - Released July 11, 2019
- CbAPI 1.4.4 - Released July 3, 2019
- CbAPI 1.4.3 - Released May 7, 2019
- CbAPI 1.4.2 - Released March 27, 2019
- CbAPI 1.4.1 - Released January 10, 2019
- CbAPI 1.4.0 - Released January 10, 2019
- CbAPI 1.3.6 - Released February 14, 2018
- CbAPI 1.3.5 - Released February 2, 2018
- CbAPI 1.3.4 - Released September 14, 2017
- CbAPI 1.3.3 - Released September 1, 2017
- CbAPI 1.3.2 - Released August 10, 2017
- CbAPI 1.3.1 - Released August 3, 2017
- CbAPI 1.3.0 - Released July 27, 2017
- CbAPI 1.2.0 - Released June 22, 2017
- CbAPI 1.1.1 - Released June 2, 2017
Once you have read the User Guide, you can view examples on GitHub or try writing code of your own. You can use the full API documentation below to see all the methods available in CBAPI and unlock the full functionality of the SDK.
- EDR (CB Response) API
- Carbon Black App Control (CB Protection) API
- Cloud Endpoint Standard API
- VMware Carbon Black Cloud Enterprise EDR API
- VMware Carbon Black Cloud API
- CB LiveQuery API