Migrate from Traps Endpoint Security Manager - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR Pro Administrator Guide

Cortex XDR
Creation date
Last date published
Administrator Guide

Migrate the management of your Traps agents from Endpoint Security Manager (ESM) to Cortex XDR.

You can easily migrate the management of your Traps agents from Endpoint Security Manager (ESM) to Cortex XDR.

Before you migrate to Cortex XDR:

  • Review to determine whether upgrading to Cortex XDR is right for you.

  • Upgrade your ESM and Traps agent to a version that supports migration to Cortex XDR:

    Traps agent

    Cortex XDR agent

    4.2.7 (all OS versions)

    • 5.0.10

    • Major releases starting with 7.1 (for example 7.2.0).

    • For Linux-based and macOS agents, upgrades to 7.9 or later must be performed via 7.8.x.

    • For Windows-based agents, contact Customer Support to migrate to Cortex XDR.

    4.2.8 (Windows only)

    Contact Customer Support to migrate to Cortex XDR.

    After you upgrade to a major Cortex XDR release version, you can subsequently continue to upgrade to a desired minor (maintenance) release in Cortex XDR.

  • Sanitize your Security policy. Because the policy structure for Cortex XDR is different than for ESM, you cannot migrate rules from an existing deployment. Before you migrate to Cortex XDR, Palo Alto Networks recommends that you review existing user rules for each policy type and remove any that you no longer need. For example, remove all rules that are resolved in content updates or that apply only to earlier versions of the Traps agent.

  • Review restore candidates. Before you migrate to Cortex XDR, review all quarantined files and determine whether they need to be restored or whether they require additional action to remediate the endpoint. After you upgrade the agent to an agent version supported by Cortex XDR, the agent will not communicate with ESM and, therefore, will not respond to requests from ESM to restore files.

  • Review security events. Review and address all events that require remediation before you migrate to Cortex XDR. During the migration, Cortex XDR migrates any security events the Traps agent sent to the ESM before the new Cortex XDR agent was installed on the endpoint. Any unsent security events on the endpoint will not be migrated to Cortex XDR.

  1. Activate.

    After you receive your Cortex XDR Prevent license, you can activate Cortex XDR from the hub.

    During activation, you can also associate Cortex XDR with a Directory Sync Service instance.

  2. Import hash overrides as hash exceptions in Cortex XDR.

    1. From the ESM Console, select Settings.

    2. Generate a Tech Support File and download it when it finishes.

    3. Extract the TechSupport ZIP file, which contains two zipped files (one for Core and one for Console).

    4. Extract the Console ZIP file.

    5. Open the DBQueries folder and locate the Verdict_Override_Exports.csv file.

      This file contains all the hash overrides defined in the ESM Console.

    6. Review the number of entries in the Verdict_Override_Exports.csv file.

      If you have more than 5,000 hashes, divide the hashes and verdicts into files that contain 5,000 or fewer hashes and verdicts.

    7. In Cortex XDR, Import File Hash Exceptions for each file.

  3. Migrate trusted signers and allow list paths.

    1. From Cortex XDR, Add a New Malware Security Profile for any platforms to which you want to add signers or paths to your allow list. Use the default profile settings or modify an existing profile that you already created.Add a New Malware Security Profile

    2. To allow trusted signers previously seen in your environment, add the signer name (Windows) or SHA256 of the certificate that signs the file (macOS) to the Allow List Signers list of the appropriate Malware Security Profile.

    3. Evaluate the WildFire rules for each platform on the ESM Console and identify any paths you want included in your allow list that are still relevant and add them to the Allow List Folders area of the appropriate Malware Security Profile on Cortex XDR.


      There may be more than one WildFire rules with the allow list. While ESM merges WildFire rules, this capability is not available in Cortex XDR.

      Ensure that you migrate paths to the appropriate Malware Security Profile for each platform:

      • Copy paths in macOS WildFire rules to the Mach-O Files whitelist in a macOS profile.

      • Copy paths in Windows WildFire rules for Executables and DLL files to the Portable Executables and DLLs allow list in a Windows profile.

      • Copy paths in Windows WildFire rules for Office files to the Office Files allow list in a Windows profile.

    4. Apply Security Profiles for each group of target objects to which the profile (and any associated hash exceptions) applies.

      You can return to the Malware Profile to specify the target objects after you upgrade the Traps agent.

  4. Migrate rules which disable protection on processes.

    For each remaining rule that disables protection on a specific process or that disables a specific protection module on the process, record the target endpoints to which the exception applies. After you upgrade the Traps agent, you can return to Cortex XDR to apply any exceptions for specific endpoints.

  5. Upgrade the Traps agent to a Cortex XDR agent version that supports migration.


    See the Supported Migration Paths table above to learn about the ESM and Traps versions that support migration to Cortex XDR. If you use an earlier ESM and Traps version that does not have direct migration support, you have three options for migration:

    • Upgrade the earlier version to a version that supports migration using action rules and then use the workflow below to upgrade the Traps agent.

    • Upgrade the Traps agent using a third-party software deployment tool, such as JAMF or SCCM. With this method, you must uninstall the agent and install a fresh installation package of Traps 5.0 instead of an upgrade package.

    • Manually uninstall the earlier Traps agent and install a fresh installation package of Traps 5.0.

    To upgrade from a Traps agent version that supports migration, continue with the following workflow:

    1. From Cortex XDR, Create an Agent Installation Package with the installation type set to Upgrade from ESM.


      For Linux endpoints, you must use the default shell package instead of the package manager.

    2. Download the package to a location reachable from the ESM.

    3. From the ESM Console, disable service protection.

    4. Create an agent action rule to upgrade the Traps agent using the package created from Cortex XDR. If you need the agent to communicate through a proxy server, you can specify a Proxy List in the action rule. The list supports up to ten proxy servers, comma-separated, and in the format <serverIPaddress>:<port>.


      Because this procedure is valid only for a specific version of Traps agents, we recommend that you use a condition for the action rule to upgrade the agents matching the Traps agent version.

    5. Save and Apply the rule.

  6. Customize your Endpoint Security Policy and set exceptions, as needed, for specific endpoints.

    If you have policy exceptions, you can either configure global endpoint policy exceptions or add conditions to the allow list within endpoint security profiles that apply to the specific endpoints.