Data Forwarder Config v1 Migration

The Data Forwarder Config v1 API will be deactivated on October 31, 2024.

Overview

This guide is to assist Carbon Black Cloud customers in migrating from the event_forwarder_config/v1/ API to the data_forwarder/v2 API.

Note: These APIs are only used to manage Forwarders, so if your Forwarder configuration changes are always made through the Carbon Black Cloud console, no action is required. If you use the API to create new Forwarders, a use case more frequently used by MSSPs, the calls will need to be updated to use the v2 APIs.

New Features

  • version_constraint has been added as an optional parameter to the Data Forwarder Alert Config to support the latest Alert API v7 schema. When not specified, it defaults to the lowest supported constraint value.
  • Lucene-based Data Filtering Support has been added to the Endpoint Event Data Forwarder type. To reduce the volume of your forwarded data, one or more filters can be applied to the events emitted by a data forwarder configuration.

Guides and Resources

API Endpoints

Config v1 API Endpoint Equivalencies and new v2 API Endpoints

Operation Legacy event_forwarder_config/v1/ Endpoint New data_forwarder/v2 API Endpoint
Create Forwarder POST {cbc-hostname}/event_forwarder_config/v1/orgs/{cb_org_key}/configs POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs
Forwarder Health Check GET {cbc-hostname}/event_forwarder_config/v1/orgs/{cb_org_key}/configs/{cb_forwarder_id}/health_check GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}/health_check
Delete Forwarder DELETE {cbc-hostname}/event_forwarder_config/v1/orgs/{cb_org_key}/configs/{cb_forwarder_id} DELETE {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}
Edit Forwarder PUT {cbc-hostname}/event_forwarder_config/v1/orgs/{cb_org_key}/configs/{cb_forwarder_id} PUT {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{config_id}
Get Configured Forwarders GET {cbc-hostname}/event_forwarder_config/v1/orgs/{cb_org_key}/configs GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs
Get Specific Forwarder New in v2 GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}
Get Available Data Versions New in v2 GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/versions

New Filter Endpoints in v2

The v1 API supported only basic filters for Endpoint Event Forwarders, and the filters were part of the POST, PUT and GET Forwarders endpoints. The new v2 API supports complex filters using lucene query syntax for Endpoint Event Forwarders, and filters are now managed through separate endpoints. The table below lists the new endpoints for v2 filtering. You can find out more information on v2 filtering here.

Operation Data Forwarder v2 API Endpoint
Filterable Event Schema GET {cbc-hostname}/data_forwarder/v2/schemas/events?filterable=true
Validate Filter POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/validate_filter
Create Filter on Forwarder POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters
Get Filters on Forwarder GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters
Get Specific Filter on Forwarder GET {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/{id}
Edit Filter on Forwarder PUT {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/{id}
Delete Filter on Forwarder DELETE {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/{id}
Bulk Filters POST {cbc-hostname}/data_forwarder/v2/orgs/{org_key}/configs/{id}/filters/_bulk

Schema Changes

The following table contains the new fields available when migrating to the v2 Data Forwarder API. The fields or sub-fields not captured here remain the same for their respective API endpoints.

New Fields

Operation New Fields
Config version_constraint
Filter action, enabled, name, query

Converting v1 Forwarders to v2

With the new v2 API, you can easily convert your v1 forwarders and access all the new features of v2. To convert your existing forwarders, simply log into the Carbon Black Cloud console, open your forwarder configuration, and re-save it. The forwarder will be instantly converted to v2, and the filters will be available in the v2 filter endpoints. Forwarders that are not updated will be automatically migrated when the API is deactivated.

Deactivation Timeline

The v1 Event Forwarder Config API will not be deactivated earlier than 12 months after deprecation, which was November 2021. The expected deactivation timeframe is mid 2024.


Last modified on September 6, 2023