Porting Applications from CBAPI to Carbon Black Cloud SDK¶
This guide will help you migrate from CBAPI to the Carbon Black Cloud Python SDK.
Note: CBAPI applications using Carbon Black EDR (Response) or Carbon Black App Control (Protection) cannot be ported, as support for on-premise products is not present in the CBC SDK. Continue to use CBAPI for these applications.
Overview¶
CBC SDK has changes to package names, folder structure, and functions. Import statements will need to change for the packages, modules, and functions listed in this guide.
Package Name Changes¶
A number of packages have new name equivalents in the CBC SDK. Endpoint Standard and Enterprise EDR have had parts replaced to use the most current API routes.
Top-level Package Name Change¶
The top-level package name has changed from CBAPI to CBC SDK.
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cbapi.psc |
cbc_sdk |
Product Name Changes¶
Carbon Black Cloud product names have been updated in the SDK.
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cbapi.psc.defense |
cbc_sdk.endpoint_standard |
cbapi.psc.livequery |
cbc_sdk.audit_remediation |
cbapi.psc.threathunter |
cbc_sdk.enterprise_edr |
cbapi.psc |
cbc_sdk.platform |
Import statements will need to change:
# Endpoint Standard (Defense)
# CBAPI
from cbapi.psc.defense import Device, Event, Policy
# CBC SDK
# note that the original "Event" has been decommissioned
from cbc_sdk.endpoint_standard import Device, EnrichedEvent, Policy
# Audit and Remediation (LiveQuery)
# CBAPI
from cbapi.psc.livequery import Run, RunHistory, Result, DeviceSummary
# CBC SDK
from cbc_sdk.audit_remediation import Run, RunHistory, Result, DeviceSummary
# Enterprise EDR (ThreatHunter)
# CBAPI
from cbapi.psc.threathunter import Feed, Report, Watchlist
# CBC SDK
from cbc_sdk.enterprise_edr import Feed, Report, Watchlist
Moved Packages and Models¶
Some modules have been moved to a more appropriate location.
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cbapi.example_helpers |
cbc_sdk.helpers |
cbapi.psc.alerts_query |
cbc_sdk.platform |
cbapi.psc.devices_query |
cbc_sdk.platform |
Import statements will need to change:
# Example Helpers
# CBAPI
from cbapi.example_helpers import build_cli_parser
# CBC SDK
from cbc_sdk.helpers import build_cli_parser
# Alerts
# CBAPI
from cbapi.psc.alerts_query import *
# CBC SDK
from cbc_sdk.platform import *
# Devices
# CBAPI
from cbapi.psc.devices_query import *
# CBC SDK
from cbc_sdk.platform import *
Replaced Modules¶
With the new Unified Platform Experience, Carbon Black Cloud APIs have been updated to provide a more consistent search experience. Platform search is replacing Endpoint Standard Event searching, and Enterprise EDR Process and Event searching.
For help beyond import statement changes, check out these resources:
- Unified Platform Experience: What to Expect
- Migration Guide: Carbon Black Cloud Events API
- Advanced Search Tips for Carbon Black Cloud Platform Search
Endpoint Standard¶
Endpoint Standard Events have been replaced with Enriched Events and the old event functionality has been decommissioned.
# Endpoint Standard Enriched Events
# CBAPI
from cbapi.psc.defense import Event
# CBC SDK (decommissioned--do not use)
from cbc_sdk.endpoint_standard import Event
# CBC SDK
from cbc_sdk.endpoint_standard import EnrichedEvent
Enterprise EDR¶
Enterprise EDR Processes and Events have been removed and replaced with Platform Processes and Events.
# Enterprise EDR Process and Event
# CBAPI
from cbapi.psc.threathunter import Process, Event
# CBC SDK
from cbc_sdk.platform import Process, Event
Folder Structure Changes¶
The directory structure for the SDK has been refined compared to CBAPI.
- Addition of the Platform folder
- Removal of Response and Protection folders
- Consolidation of model objects and query objects
- Product-specific
rest_api.py
files replaced with package levelrest_api.py
from cbapi.psc.threathunter import CbThreatHunterAPI
becomesfrom cbc_sdk import CBCloudAPI
, etc.
Directory Tree Changes¶
In general, each module’s models.py
and query.py
files were combined into their respective base.py
files.
CBAPI had the following abbreviated folder structure:
src
└── cbapi
└── psc
├── defense
│ ├── models.py
│ │ ├── Device
│ │ ├── Event
│ │ └── Policy
│ └── rest_api.py
│ └── CbDefenseAPI
├── livequery
│ ├── models.py
│ │ ├── Run
│ │ ├── RunHistory
│ │ ├── Result
│ │ ├── ResultFacet
│ │ ├── DeviceSummary
│ │ └── DeviceSummaryFacet
│ └── rest_api.py
│ └── CbLiveQueryAPI
└── threathunter
├── models.py
│ ├── Process
│ ├── Event
│ ├── Tree
│ ├── Feed
│ ├── Report
│ ├── IOC
│ ├── IOC_V2
│ ├── Watchlist
│ ├── ReportSeverity
│ ├── Binary
│ └── Downloads
└── rest_api.py
└── CbThreatHunterAPI
Each product had a models.py
and rest_api.py
file.
CBC SDK has the following abbreviated folder structure:
src
└── cbc_sdk
├── audit_remediation
│ └── base.py
│ ├── Run
│ ├── RunHistory
│ ├── Result
│ ├── ResultFacet
│ ├── DeviceSummary
│ └── DeviceSummaryFacet
├── endpoint_standard
│ └── base.py
│ ├── Device
│ ├── Event
│ ├── Policy
│ ├── EnrichedEvent
│ └── EnrichedEventFacet
├── enterprise_edr
│ ├── base.py
│ ├── threat_intelligence.py
│ │ ├── Watchlist
│ │ ├── Feed
│ │ ├── Report
│ │ ├── ReportSeverity
│ │ ├── IOC
│ │ └── IOC_V2
│ └── ubs.py
│ ├── Binary
│ └── Downloads
└── platform
│ ├── alerts.py
│ │ ├── WatchlistAlert
│ │ ├── CBAnalyticsAlert
│ │ ├── Workflow
│ │ └── WorkflowStatus
│ ├── processes.py
│ │ ├── Process
│ │ ├── ProcessFacet
│ ├── events.py
│ │ ├── Event
│ │ └── EventFacet
│ └── devices.py
│ └── Device
└── rest_api.py
└── CBCloudAPI.py
Now, each product has either a base.py
file with all of its objects, or categorized files like platform.alerts.py
and platform.devices.py
.
The package level rest_api.py
replaced each product-specific rest_api.py
file.
Function Changes¶
Helper Functions:
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cbapi.example_helpers.get_cb_defense_object()
cbapi.example_helpers.get_cb_livequery_object()
cbapi.example_helpers.get_cb_threathunter_object()
cbapi.example_helpers.get_cb_psc_object() |
cbc_sdk.helpers.get_cb_cloud_object() |
Audit and Remediation Queries:
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cb.query(sql_query) |
cb.select(Run).where(sql=sql_query) |
cb.query_history(query_string) |
cb.select(RunHistory).where(query_string) |
cb.query(sql_query).policy_ids() |
cb.select(Run).policy_id() |
API Objects:
CBAPI Name (old) | CBC SDK Name (new) |
---|---|
cbapi.psc.defense.CbDefenseAPI
cbapi.psc.livequery.CbLiveQueryAPI
cbapi.psc.threathunter.CbThreatHunterAPI
cbapi.psc.CbPSCBaseAPI |
cbc_sdk.CBCloudAPI |