Cortex XDR collector migration guide

[ 1 Overview ] [ 2 List of changes ] [ 3 Preparing for migration ] [ 4 Migration Steps ]

Overview

This guide will walk you through the process of updating your Cortex XDR collector configuration from versions 1.x.x to new versions 2.x.x. The new versions introduce significant improvements and changes to the configuration style to enhance performance, usability, and security.

List of changes

The new configuration format introduces several key changes:

New Services: The configuration now supports new services (all_alerts, audit_managements)
Have changed the existing devo_tag (edr.cortex_xdr.alerts to edr.cortex_xdr.incident_alert)
We are no longer using table edr.cortex_xdr.alerts_multi_event for alerts service and ingesting all the alerts data in edr.cortex_xdr.alerts_multi
alerts service now uses v2 endpoint instead of v1 for /alerts/get_alerts_multi_events.
- old endpoint - v2/alerts/get_alerts_multi_events
- new endpoint - v1/alerts/get_alerts_multi_events
There is no separate puller for any services all the services have a unified puller

Preparing for migration

Before starting the migration process, we recommend the following steps:

Backup your current configuration: Always ensure you have a backup of your existing configuration files to prevent any data loss.
Review the new configuration documentation: Familiarize yourself with the new configuration options available in version 2.0.0.

Migration Steps

Step 1: Update the service configuration parameter field name

An example of the old and new configuration is shown below:

# Old Version (1.4.0)
services:
      incidents:
        request_period_in_seconds : <request_period_in_seconds_value>
        api_fqdn: <api_fqdn_value>
        api_endpoint: <api_endpoint_value>
        incident_extra_data_endpoint: <incident_extra_data_endpoint_value>
      alerts:
        start_time: <start_time_value> # Example 2024-01-01T01:50:00Z
        request_period_in_seconds: <request_period_in_seconds_value>
        api_fqdn: <api_fqdn_value>
        api_endpoint: <api_endpoint_value>

↓

# New Version (2.0.0)
    services:
      incidents:
        api_fqdn: <api_fqdn_value>
        request_period_in_seconds : <request_period_in_seconds_value> #optional
        start_time: <start_time> #optional
        override_devo_tag: <override_devo_tag_value> #optional
        override_incident_tag: <override_incident_tag> #optional
      alerts:
        api_fqdn: <api_fqdn_value>
        start_time: <start_time> # Example 2024-01-01T01:50:00Z
        request_period_in_seconds: <request_period_in_seconds> #optional
        override_devo_tag: <override_devo_tag> #optional
      all_alerts:
        api_fqdn: <api_fqdn_value>
        start_time: <start_time_value> # Example 2024-01-01T01:50:00Z , optional
        request_period_in_seconds: <request_period_in_seconds_value> #optional
        override_devo_tag: <override_devo_tag_value> #optional
      audit_managements:
        api_fqdn: <api_fqdn_value>
        start_time: <start_time_value> # Example 2024-01-01T01:50:00Z #optional
        request_period_in_seconds: <request_period_in_seconds_value> #optional
        override_devo_tag: <override_devo_tag_value> #optional

There are some changes in the params we are providing for each services in old and new configurations.

For incidents service there is no need to provide api_endpoint and incident_extra_data_endpoint in the config. we have included these endpoints in the collector definitions.
For alerts service there is no need to provide api_endpoint in the config. We have added it in collector definitions.
For rest of the service, same pattern is followed. No need to provide api_endpoint in the params.

Step 2: Update in the services configuration

The new services have been added to the Cortex XDR collector like all_alerts, audit_managements

An example of the new configuration is shown below:

# New version (2.0.0)
  services:
     all_alerts:
        api_fqdn: <api_fqdn_value>
        start_time: <start_time_value> # Example 2024-01-01T01:50:00Z , optional
        request_period_in_seconds: <request_period_in_seconds_value> #optional
        override_devo_tag: <override_devo_tag_value> #optional
     audit_managements:
        api_fqdn: <api_fqdn_value>
        start_time: <start_time_value> # Example 2024-01-01T01:50:00Z #optional
        request_period_in_seconds: <request_period_in_seconds_value> #optional
        override_devo_tag: <override_devo_tag_value> #optional

Each of the services have override_devo_tag, start_time, request_period_in_seconds as an optional parameter. start_time to params which gives us the time when we want to get the data from.

Step 3: Before and after configuration

Putting it all together, see below for an example of the old and new configuration:

↓

Step 4: Changes in the tags and table of the old services

alerts service will have only one table edr.cortex_xdr.alerts_multi for new version i.e 2.0.0 and above.
alerts service no longer uses edr.cortex_xdr.alerts_multi_event table to ingest events field of alert data. All the events of alerts service will be ingested in edr.cortex_xdr.alerts_multi.
incidents service using a modified table edr.cortex_xdr.incident_alert for ingesting data of alerts for incidents endpoint. To override this incident alert tag we need override_incident_tag . The changes in that table as written below.
- old tag/table - edr.cortex_xdr.alerts
- Modified tag/table - edt.cortex_xdr.incident_alert