API and Schema Migration
Overview
As Carbon Black Cloud develops new functionality, new APIs are needed. This leads to the deprecation and eventual deactivation of older APIs.
In this document, you will find:
- The Migration Summary table, including step-by-step migration guides to help you seamlessly transition
- New Features that will be unlocked when you migrate
- A Migration Checklist with common migration tasks
- Resources for additional support
Migration Summary
Are you using a supported integration?
- IBM QRadar App - Update to v2.3
- Instructions
- Earlier versions used Alerts v6 API, Data Forwarder Alert Schema v1 and
APItype Access Level
- Splunk SIEM - Update to v2.x.x
- Instructions
- Earlier versions used Alerts v6 API, Data Forwarder Alert Schema v1, Live response v3 API and
APItype Access Level
- Splunk SOAR - Update to v2.x
- Instructions
- Earlier versions used Alerts v6 API and Enriched Events API
- ServiceNow - Update to ITSM App v3.0.0, SecOps App v3.0.0, Vulnerability Response v2.0.0
- Instructions
- Earlier versions used Alerts v6 API and Data Forwarder Alert Schema v1
- Carbon Black Cloud SDK - Update to Carbon Black Cloud SDK v1.5.x
- Instructions
- Earlier versions used the Alerts v6 API
- CBAPI - Update to Carbon Black Cloud SDK v1.5.x
- This is the very early python SDK that pre-dated Carbon Black Cloud SDK.
- It uses Alerts v6 API, Policy v3 API, Live Response v3 API (live response),
- Instructions
APIs which were deactivated on September 5th 2024
If you are using a custom integration, review the APIs that are being used and make changes as necessary.
| Migration Guide | Deprecated API | Replacement API | Deprecated Date | Targeted Deactivation Date |
|---|---|---|---|---|
| Alerts Forwarder Schema Migration | Alerts Forwarder v1 Schema | Alerts Forwarder v2 Schema | July 2023 | September 5th, 2024 |
| Alerts Migration | Alerts v6 API | Alerts v7 API | June 2023 | September 5th, 2024 |
| Devices Migration | Devices v3 REST API | Devices v6 API | August 2020 | September 5th, 2024 |
| Live Response Migration | Live Response v3 API | Live Response v6 API | April 2021 | September 5th, 2024 |
| Observations Migration | Enriched Events Search API | Observations API | July 2023 | September 5th, 2024 |
| Policy Migration | Policy v3 REST API | Policy Service v1 API | July 2022 | September 5th, 2024 |
| Process Search Suggestions v1 | Process Search Suggestions v2 | April 2023 | September 5th, 2024 | |
| POST Process Search Validation | GET Process Search Validation v1 | POST Process Search Validation v2 | April 2023 | September 5th, 2024 |
| Sensor Update Services Migration | Sensor Update Services v2 API | Sensor Update Services v3 API | July 2023 | September 5th, 2024 |
APIs to be deactivated on October 31st 2024:
| Migration Guide | Deprecated API | Replacement API | Deprecated Date | Targeted Deactivation Date |
|---|---|---|---|---|
| Audit Log Access Level Migration | Use of API Access Level Type |
Use of Custom Access Level Type |
June 2023 | October 31, 2024 |
| Notification Migration | Notifications v3 API | Alerts v7 API or Data Forwarder - Alert Schema 2.0.0 | September 2023 | October 31, 2024 |
APIs to be deactivated on November 18th 2024:
| Migration Guide | Deprecated API | Replacement API | Deprecated Date | Targeted Deactivation Date |
|---|---|---|---|---|
| Data Forwarder Config Migration | Data Forwarder Config v1 | Data Forwarder Config v2 | July 2023 | November 18, 2024 |
SDK impacted by deactivation of APIs
| Migration Guide | Deprecated SDK | Replacement SDK | Deprecated Date | Deactivation Date of APIs |
|---|---|---|---|---|
| CBAPI - legacy python SDK Migration | CBAPI SDK | Carbon Black Cloud Python SDK (CBC SDK) | January 2021 | September 5th, 2024 |
| Carbon Black Cloud Python SDK Changelog | CBC SDK 1.4.3 and earlier | CBC SDK 1.5.0 onwards | October 24, 2023 | September 5th, 2024 |
Access Level Deactivation
After the APIs above have been deactivated, the legacy Access Level types of API, LIVE_RESPONSE and SIEM will not be required
and they will also be deactivated. All supported APIs will use the Access Level type Custom with fine grained permission controls.
| Access Level Type | All dependent APIs will be deactivated by | Targeted API Key Deactivation Date | Related Migration Guides |
|---|---|---|---|
| API | September 5th, 2024 | October 31, 2024 | Audit Log Access Level Migration
Devices Migration Policy Migration |
| LIVE_RESPONSE | September 5th, 2024 | October 31, 2024 | Live Response Migration
and those for API type: Audit Log Access Level Migration Devices Migration Policy Migration |
| SIEM | October 31, 2024 | December 18, 2024 | Notification Migration |
API Usage
You can determine if you are using APIs that are being deactivated by navigating to Settings > API Access in your Carbon Black Cloud console.
- If the access level type is
API, use the session renewal time to determine the last time that key called one of the following APIs, and migrate if needed.- integrationServices/v3/devices - move to devices v6 and a custom access level
- integrationServices/v3/policy - move to Policy Service and a custom access level
- integrationServices/v3/auditlogs - update the integration to use a custom API key and a custom access level
- If the access level type is
LIVE_RESPONSE, use the session renewal time to determine the last time that key called one of the following APIs and migrate if needed.- The same routes as for API key - follow migration instructions above
- integrationServices/v3/cblr - Legacy Live Response - update to Live Response and a custom API key
- If the access level type is
SIEM- integrationServices/v3/notifications - see the migration guide to determine whether the data forwarder, syslog connector using the Alerts v7 API, or another option is right for you
- integrationServices/v3/notifications - see the migration guide to determine whether the data forwarder, syslog connector using the Alerts v7 API, or another option is right for you
New Features
Migrating to the latest APIs and Schemas will unlock several new features including:
- Fine-grained access control for Live Response means you can limit the API key to only the specific operations that should be performed
- Policies now include the ability to turn data collection for auth events and XDR data on or off and configure Host Based Firewall rules - more policy settings are in the works
- Getting all details about an alert, such as process command line, in the alert record - no need to make follow-up calls to search for the process details
- Data schema consistency across the Alert v7 API and Data Forwarder Alert v2 schema - same fields and same field names
Migration Checklist
- Check the migration guides to determine if you need to update your authentication.
- Find out which endpoints your organization uses, and utilize the migration guides to find the equivalent endpoints in the new APIs.
- View the schema mapping tables in the migration guides to verify any field changes and ensure you are taking advantage of newly added fields.
- Update your app’s code to use the latest version of the API or Schema.
Support and Resources
- Use the CB Developer Network community forum to discuss issues and get answers from other API developers in the CB Developer Network
- Report bugs and product issues to Broadcom Support
- View all API and integration offerings on the Developer Network along with reference documentation, video tutorials, and how-to guides.
Last modified on September 23, 2024