The CBCloudAPI Object

The CBCloudAPI object is the key object used in working with the Carbon Black Cloud. It represents the connection to the Carbon Black Cloud server, to the specific organization to which you have access. It is used to search for objects representing specific data items on the server, such as devices, alerts, policies, and so forth. It also has a number of utility functions and properties providing access to additional functionality on the server, such as Live Response.

A program using the Carbon Black Cloud SDK will start by creating a CBCloudAPI object, passing it the parameters necessary to authenticate to the server. The authentication parameters may be specified as direct arguments when the object is created, or may be provided by a credential provider (see Credential Providers Package). This object is then called upon for SDK operations, or passed as a parameter to other SDK functions.

As the CBCloudAPI object relies upon REST calls to the server, it does not hold network connections open, and hence need not be explicitly closed.

CBCloudAPI Creation Examples

Authenticate to the Carbon Black Cloud server with directly-supplied parameters:

from cbc_sdk import CBCloudAPI
api = CBCloudAPI(url='https://defense.conferdeploy.net', token='ABCDEFGHIJKLMNOPQRSTUVWX/YZ12345678',
                 org_key='ABCD1234')

# as an example, get the list of all watchlist alerts
from cbc_sdk.platform import WatchlistAlert
query = api.select(WatchlistAlert)
alerts_list = list(query)

Authenticate to the Carbon Black Cloud server using a profile with the default credential provider:

from cbc_sdk import CBCloudAPI
api = CBCloudAPI(profile='my_profile')

# as an example, get the list of all watchlist alerts
from cbc_sdk.platform import WatchlistAlert
query = api.select(WatchlistAlert)
alerts_list = list(query)

Authenticate to the Carbon Black Cloud server using a profile supplied by a different credential provider:

from cbc_sdk import CBCloudAPI
from cbc_sdk.credentials import KeychainCredentialProvider
creds = KeychainCredentialProvider('keychain-to-use', 'my-username')
api = CBCloudAPI(profile='my_profile', credential_provider=creds)

# as an example, get the list of all watchlist alerts
from cbc_sdk.platform import WatchlistAlert
query = api.select(WatchlistAlert)
alerts_list = list(query)

Class Documentation

class CBCloudAPI(*args, **kwargs)

Bases: BaseAPI

A connection to the Carbon Black Cloud.

The core object for interacting with the Carbon Black Cloud SDK.

Example

>>> from cbc_sdk import CBCloudAPI
>>> cb = CBCloudAPI(profile="production")

Create a new instance of the CBCloudAPI object.

Parameters:

*args (list) – List of arguments to pass to the API object.
**kwargs (dict) – Keyword arguments to pass to the API object.

Keyword Arguments:

credential_file (str) – The name of a credential file to be used by the default credential provider.
credential_provider (cbc_sdk.credentials.CredentialProvider) – An alternate credential provider to use to find the credentials to be used when accessing the Carbon Black Cloud.
csp_api_token (str) – The CSP API Token for Carbon Black Cloud.
csp_oauth_app_id (str) – The CSP OAuth App ID for Carbon Black Cloud.
csp_oauth_app_secret (str) – The CSP OAuth App Secret for Carbon Black Cloud.
integration_name (str) – The name of the integration using this connection. This should be specified as a string in the format ‘name/version’
max_retries (int) – The maximum number of times to retry failing API calls. Default is 5.
org_key (str) – The organization key value to use when accessing the Carbon Black Cloud.
pool_block (bool) – True if the connection pool should block when no free connections are available. Default is False.
pool_connections (int) – Number of HTTP connections to be pooled for this instance. Default is 1.
pool_maxsize (int) – Maximum size of the connection pool. Default is 10.
profile (str) – Use the credentials in the named profile when connecting to the Carbon Black Cloud server. Uses the profile named ‘default’ when not specified.
proxy_session (requests.session.Session) – Proxy session to be used for cookie persistence, connection pooling, and configuration. Default is None (use the standard session).
thread_pool_count (int) – The number of threads to create for asynchronous queries. Defaults to 3.
timeout (float) – The timeout to use for for API connection requests. Default is None (no timeout).
token (str) – The API token to use when accessing the Carbon Black Cloud.
url (str) – The URL of the Carbon Black Cloud provider to use.

alert_search_suggestions(query)

Returns suggestions for keys and field values that can be used in a search.

Parameters:: query (str) – A search query to use.
Returns:: A list of search suggestions expressed as dict objects.
Return type:: list[dict]

api_json_request(method, uri, **kwargs)

Submit a request to the server.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

method (str) – HTTP method to use.
uri (str) – URI to submit the request to.
**kwargs (dict) – Additional arguments.

Keyword Arguments:

data (object) – Body data to be passed to the request, formatted as JSON.
headers (dict) – Header names and values to pass to the request.

Returns:

Result of the operation, as JSON

Return type:

object

Raises:

ServerError – If there’s an error output from the server.

api_request_iterate(method, uri, **kwargs)

Submit a request to the specified URI and iterate over the response as lines of text.

Should only be used for requests that can be expressed as large amounts of text that can be broken into lines.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

method (str) – HTTP method to use.
uri (str) – The URI to send the request to.
**kwargs (dict) – Additional arguments for the request.

Keyword Arguments:

data (object) – Body data to be passed to the request, formatted as JSON.
headers (dict) – Header names and values to pass to the request.

Yields:

str – Each line of text in the returned data.

api_request_stream(method, uri, stream_output, **kwargs)

Submit a request to the specified URI and stream the results back into the given stream object.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

method (str) – HTTP method to use.
uri (str) – The URI to send the request to.
stream_output (RawIOBase) – The output stream to write the data to.
**kwargs (dict) – Additional arguments for the request.

Keyword Arguments:

data (object) – Body data to be passed to the request, formatted as JSON.
headers (dict) – Header names and values to pass to the request.

Returns:

The return data from the request.

Return type:

object

audit_remediation(sql)

Run an audit-remediation query.

Parameters:: sql (str) – The SQL for the query.
Returns:: The query object.
Return type:: cbc_sdk.base.Query

audit_remediation_history(query=None)

Run an audit-remediation history query.

Parameters:: query (str) – The SQL for the query.
Returns:: The query object.
Return type:: cbc_sdk.base.Query

bulk_threat_dismiss(threat_ids, remediation=None, comment=None)

Dismiss the alerts associated with multiple threat IDs.

The alerts will be left in a DISMISSED state.

Parameters:

threat_ids (list[str]) – List of string threat IDs.
remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID of the pending request, which may be used to select a WorkflowStatus object.

Return type:

str

bulk_threat_update(threat_ids, remediation=None, comment=None)

Update the alert status of alerts associated with multiple threat IDs.

The alerts will be left in an OPEN state

Parameters:

threat_ids (list[str]) – List of string threat IDs.
remediation (str) – The remediation state to set for all alerts.
comment (str) – The comment to set for all alerts.

Returns:

The request ID of the pending request, which may be used to select a WorkflowStatus object.

Return type:

str

convert_feed_query(query)

Converts a legacy CB Response query to a ThreatHunter query.

Parameters:: query (str) – The query to convert.
Returns:: The converted query.
Return type:: str

create(cls, data=None)

Creates a new model.

Parameters:

cls (class) – The model being created.
data (dict) – The data to pre-populate the model with. Default None.

Returns:

An instance of cls.

Return type:

object

Examples

>>> feed = cb.create(Feed, feed_data)

property custom_severities: List of active ReportSeverity instances.

delete_object(uri)

Send a DELETE request to the specified URI.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:: uri (str) – The URI to send the DELETE request to.
Returns:: The return data from the DELETE request, as JSON.
Return type:: object

device_background_scan(device_ids, scan)

Set the background scan option for the specified devices.

Parameters:

device_ids (list[int]) – List of IDs of devices to be set.
scan (bool) – True to turn background scan on, False to turn it off.

Returns:

The parsed JSON output from the request.

Return type:

dict

Raises:

ServerError – If the API method returns an HTTP error code.

device_bypass(device_ids, enable)

Set the bypass option for the specified devices.

Parameters:

device_ids (list[int]) – List of IDs of devices to be set.
enable (bool) – True to enable bypass, False to disable it.

Returns:

The parsed JSON output from the request.

Return type:

dict

Raises:

ServerError – If the API method returns an HTTP error code.

device_delete_sensor(device_ids)

Delete the specified sensor devices.

Parameters:: device_ids (list[int]) – List of IDs of devices to be deleted.
Returns:: The parsed JSON output from the request.
Return type:: dict
Raises:: ServerError – If the API method returns an HTTP error code.

device_quarantine(device_ids, enable)

Set the quarantine option for the specified devices.

Parameters:

device_ids (list[int]) – List of IDs of devices to be set.
enable (bool) – True to enable quarantine, False to disable it.

Returns:

The parsed JSON output from the request.

Return type:

dict

Raises:

ServerError – If the API method returns an HTTP error code.

device_uninstall_sensor(device_ids)

Uninstall the specified sensor devices.

Parameters:: device_ids (list[int]) – List of IDs of devices to be uninstalled.
Returns:: The parsed JSON output from the request.
Return type:: dict
Raises:: ServerError – If the API method returns an HTTP error code.

device_update_policy(device_ids, policy_id)

Set the current policy for the specified devices.

Parameters:

device_ids (list[int]) – List of IDs of devices to be changed.
policy_id (int) – ID of the policy to set for the devices.

Returns:

The parsed JSON output from the request.

Return type:

dict

Raises:

ServerError – If the API method returns an HTTP error code.

device_update_sensor_version(device_ids, sensor_version)

Update the sensor version for the specified devices.

Parameters:

device_ids (list[int]) – List of IDs of devices to be changed.
sensor_version (dict) – New version properties for the sensor.

Returns:

The parsed JSON output from the request.

Return type:

dict

Raises:

ServerError – If the API method returns an HTTP error code.

fetch_process_queries(): Retrieves a list of query IDs, active or complete, known by the ThreatHunter server.

get_auditlogs()

Retrieve queued audit logs from the Carbon Black Cloud Endpoint Standard server.

Note

While this can be used with an ‘API’ key generated in the Carbon Black Cloud console, those key types are officially deprecated. Use a Custom key type with permissions as given here.

Required Permissions:: org,audits(READ)
Deprecated:: Use AuditLog.getAuditLogs (from cbc_sdk.platform) instead.

Returns:: List of dictionary objects representing the audit logs, or an empty list if none available.
Return type:: list[dict]

get_notifications()

Retrieve queued notifications (alerts) from the Cb Endpoint Standard server.

Note

This can only be used with a ‘SIEM’ key generated in the Cb Endpoint Standard console.

Deprecated:: Use the Alerts API or the Data Forwarder to get similar notifications.

Returns:: List of dictionary objects representing the notifications, or an empty list if none available.
Return type:: list[dict]

get_object(uri, query_parameters=None, default=None)

Submit a GET request to the server and parse the result as JSON before returning.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

uri (str) – The URI to send the GET request to.
query_parameters (dict) – Parameters for the query.
default (object) – What gets returned in the event of an empty response.

Returns:

Result of the GET request, as JSON.

Return type:

object

get_policy_ruleconfig_parameter_schema(ruleconfig_id)

Returns the parameter schema for a specified rule configuration.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.
ruleconfig_id (str) – The rule configuration ID (UUID).

Returns:

The parameter schema for this particular rule configuration (as a JSON schema).

Return type:

dict

Raises:

InvalidObjectError – If the rule configuration ID is not valid.

get_raw_data(uri, query_parameters=None, default=None, **kwargs)

Submit a GET request to the server and return the result without parsing it.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

uri (str) – The URI to send the GET request to.
query_parameters (dict) – Parameters for the query.
default (object) – What gets returned in the event of an empty response.
**kwargs (dict) – Additional arguments.

Keyword Arguments:

headers (dict) – Header names and values to pass to the GET request.

Returns:

Result of the GET request.

Return type:

object

property live_response

The Live Response session manager object.

It is created if it does not yet exist when this property is read.

notification_listener(interval=60)

Continually polls the Cb Endpoint Standard server for notifications (alerts).

Note

This can only be used with a ‘SIEM’ key generated in the Cb Endpoint Standard console.

Deprecated:: Use the Alerts API or the Data Forwarder to get similar notifications.

Parameters:: interval (int) – Time period to wait in between polls for notifications, in seconds. Default is 60.
Yields:: dict – A dictionary representing a notification.

property org_urn: The URN of the current organization, based on the configured org_key.

post_multipart(uri, param_table, **kwargs)

Send a POST request to the specified URI, with parameters sent as multipart/form-data.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

uri (str) – The URI to send the POST request to.
param_table (dict) – A dict of known parameters to the underlying method, each element of which is a parameter name mapped to a dict, which contains elements ‘filename’ and ‘type’ representing the pseudo-filename to be used for the data and the MIME type of the data.
**kwargs (dict) – Arguments to pass to the API. Except for “headers,” these will all be added as parameters to the form data sent.

Keyword Arguments:

headers (dict) – Header names and values to pass to the request.

Returns:

The return data from the POST request.

Return type:

object

post_object(uri, body, **kwargs)

Send a POST request to the specified URI.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

uri (str) – The URI to send the POST request to.
body (object) – The data to be sent in the body of the POST request, as JSON.
**kwargs (dict) – Additional arguments for the HTTP POST.

Keyword Arguments:

headers (dict) – Header names and values to pass to the request.

Returns:

The return data from the POST request, as JSON.

Return type:

object

process_limits()

Returns a dictionary containing API limiting information.

Examples

>>> cb.process_limits()
{u'status_code': 200, u'time_bounds': {u'upper': 1545335070095, u'lower': 1542779216139}}

put_object(uri, body, **kwargs)

Send a PUT request to the specified URI.

Normally only used by other SDK objects; used from user code only to submit a request to the server that is not currently implemented in the SDK.

Parameters:

uri (str) – The URI to send the PUT request to.
body (object) – The data to be sent in the body of the PUT request.
**kwargs (dict) – Additional arguments for the HTTP PUT.

Keyword Arguments:

headers (dict) – Header names and values to pass to the request.

Returns:

The return data from the PUT request, as JSON.

Return type:

object

select(cls, unique_id=None, *args, **kwargs)

Prepare a query against the Carbon Black data store.

Most objects returned by the SDK are returned via queries created using this method.

Parameters:

cls (class | str) – The Model class (for example, Computer, Process, Binary, FileInstance) to query
unique_id (Any) – The unique id of the object to retrieve, to retrieve a single object by ID. Default is None (create a standard query).
*args (list) – Additional arguments to pass to a created object.
**kwargs (dict) – Additional arguments to pass to a created object or query.

Returns:

An instance of the Model class if a unique_id is provided, otherwise a Query object.

Return type:

object

property url: The connection URL.

validate_process_query(query)

Validates the given IOC query.

Parameters:: query (str) – The query to validate.
Returns:: True if the query is valid, False if not.
Return type:: bool

Examples

>>> cb.validate_process_query("process_name:chrome.exe") # True