Concepts

Platform Devices vs Endpoint Standard Devices

For most use cases, Platform Devices are sufficient to access information about devices and change that information. If you want to connect to a device using Live Response, then you must use Endpoint Standard Devices and a Live Response API Key.

# Device information is accessible with Platform Devices
>>> api = CBCloudAPI(profile='platform')
>>> platform_devices = api.select(platform.Device).set_os(["WINDOWS", "LINUX"])
>>> for device in platform_devices:
...   print(
      f'''
      Device ID: {device.id}
      Device Name: {device.name}

      '''
Device ID: 1234
Device Name: Win10x64

Device ID: 5678
Device Name: UbuntuDev


# Live Response is accessible with Endpoint Standard Devices
>>> api = CBCloudAPI(profile='live_response')
>>> endpoint_standard_device = api.select(endpoint_standard.Device, 1234)
>>> endpoint_standard_device.lr_session()
url: /integrationServices/v3/cblr/session/428:1234 -> status: PENDING
[...]

Queries

Generally, to retrieve information from your Carbon Black Cloud instance you will:

  1. Create a Query
  2. Refine the Query
  3. Execute the Query

Create Queries with CBCloudAPI.select()

Data is retrieved from the Carbon Black Cloud with CBCloudAPI.select() statements. A select() statement creates a query, which can be further refined with parameters or criteria, and then executed.

# Create a query for devices
>>> device_query = api.select(platform.Device).where('avStatus:AV_ACTIVE')

# The query has not yet been executed
>>> type(device_query)
<class cbc_sdk.platform.devices.DeviceSearchQuery>

This query will search for Platform Devices with antivirus active.

Refine Queries with where(), and_(), and or_()

Queries can be refined during or after declaration with where(), and_(), and or_().

# Create a query for events
>>> event_query = api.select(endpoint_standard.Event).where(hostName='Win10').and_(ipAddress='10.0.0.1')

# Refine the query
>>> event_query.and_(applicationName='googleupdate.exe')
>>> event_query.and_(eventType='REGISTRY_ACCESS')
>>> event_query.and_(ownerNameExact='DevRel')

This query will search for Endpoint Standard Events created by the application googleupdate.exe accessing the registry on a device with a hostname containing Win10, an IP Address of 10.0.0.1, and owned by DevRel.

Be Consistent When Refining Queries

All queries are of type QueryBuilder(), with support for either raw string-based queries , or keyword arguments.

# Equivalent queries
>>> string_query = api.select(platform.Device).where("avStatus:AV_ACTIVE")
>>> keyword_query = api.select(platform.Device).where(avStatus="AV_ACTIVE").

Queries must be consistent in their use of strings or keywords; do not mix strings and keywords.

# Not allowed
>>> mixed_query = api.select(platform.Device).where(avStatus='Win7x').and_("virtualMachine:true")
cbc_sdk.errors.ApiError: Cannot modify a structured query with a raw parameter

Execute a Query

A query is not executed on the server until it’s accessed, either as an iterator (where it will generate results on demand as they’re requested) or as a list (where it will retrieve the entire result set and save to a list).

# Create and Refine a query
>>> device_query = api.select(platform.Device).where('avStatus:AV_ACTIVE').set_os(["WINDOWS"])

# Execute the query by accessing as a list
>>> matching_devices = [device for device in device_query]

>>> print(f"First matching device ID: {matching_devices[0].id}")
First matching device ID: 1234

# Or as an iterator
>>> for matching_device in device_query:
...   print(f"Matching device ID: {matching_device.id})
Matching device ID: 1234
Matching device ID: 5678

You can also call the Python built-in len() on this object to retrieve the total number of items matching the query.

# Retrieve total number of matching devices
>>> len(device_query)
2

In this example, the matching device ID’s are accessed with device.id. If using Endpoint Standard Devices, the device ID’s are accessed with device.deviceId.

Query Parameters vs Criteria

For queries, some Carbon Black Cloud APIs use GET requests with parameters, and some use POST requests with criteria.

Parameters

Parameters modify a query. When modifying a query with where(), and_(), and or_(), those modifications become query parameters when sent to Carbon Black Cloud.

>>> device_query = api.select(endpoint_standard.Device).where(hostName='Win7').and_(ipAddress='10.0.0.1')

Executing this query results in an API call similar to GET /integrationServices/v3/device?hostName='Win7'&ipAddress='10.0.0.1'

Criteria

Criteria also modify a query, and can be used with or without parameters. When using CBC SDK, there are API-specific methods you can use to add criteria to queries.

# Create a query for alerts
>>> alert_query = api.select(cbc_sdk.Platform.Alert)

# Refine the query with parameters
>>> alert_query.where(alert_severity=9).or_(alert_severity=10)

# Refine the query with criteria
>>> alert_query.set_device_os(["MAC"]).set_device_os_versions(["10.14.6"])

Executing this query results in an API call to POST /appservices/v6/orgs/{org_key}/alerts/_search with this JSON Request Body:

{
  "query": "alert_severity:9 OR alert_severity:10",
  "criteria": {
    "device_os": ["MAC"],
    "device_os_version": ["10.14.6"]
  }
}

The query parameters are sent in "query", and the criteria are sent in "criteria".

Modules with Support for Criteria

Run
  • cbc_sdk.audit_remediation.base.RunQuery.device_ids()
  • cbc_sdk.audit_remediation.base.RunQuery.device_types()
  • cbc_sdk.audit_remediation.base.RunQuery.policy_id()

Result and Device Summary

  • cbc_sdk.audit_remediation.base.ResultQuery.set_device_ids()
  • cbc_sdk.audit_remediation.base.ResultQuery.set_device_names()
  • cbc_sdk.audit_remediation.base.ResultQuery.set_device_os()
  • cbc_sdk.audit_remediation.base.ResultQuery.set_policy_ids()
  • cbc_sdk.audit_remediation.base.ResultQuery.set_policy_names()
  • cbc_sdk.audit_remediation.base.ResultQuery.set_status()

ResultFacet and DeviceSummaryFacet

  • cbc_sdk.audit_remediation.base.FacetQuery.set_device_ids()
  • cbc_sdk.audit_remediation.base.FacetQuery.set_device_names()
  • cbc_sdk.audit_remediation.base.FacetQuery.set_device_os()
  • cbc_sdk.audit_remediation.base.FacetQuery.set_policy_ids()
  • cbc_sdk.audit_remediation.base.FacetQuery.set_policy_names()
  • cbc_sdk.audit_remediation.base.FacetQuery.set_status()

Alert

  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_categories()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_create_time()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_device_ids()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_device_names()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_device_os()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_device_os_versions()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_device_username()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_group_results()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_alert_ids()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_legacy_alert_ids()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_minimum_severity()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_policy_ids()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_policy_names()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_process_names()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_process_sha256()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_reputations()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_tags()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_target_priorities()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_threat_ids()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_types()
  • cbc_sdk.platform.alerts.BaseAlertSearchQuery.set_workflows()

WatchlistAlert

  • cbc_sdk.platform.alerts.WatchlistAlertSearchQuery.set_watchlist_ids()
  • cbc_sdk.platform.alerts.WatchlistAlertSearchQuery.set_watchlist_names()

CBAnalyticsAlert

  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_blocked_threat_categories()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_device_locations()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_kill_chain_statuses()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_not_blocked_threat_categories()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_policy_applied()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_reason_code()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_run_states()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_sensor_actions()
  • cbc_sdk.platform.alerts.CBAnalyticsAlertSearchQuery.set_threat_cause_vectors()

VMwareAlert

  • cbc_sdk.platform.alerts.VMwareAlertSearchQuery.set_group_ids()

Modules not yet Supported for Criteria

RunHistory Event Process