Bash: Migrate

Bash script to migrate Falcon sensor from one CID to another through the Falcon APIs on a Linux endpoint. By default, this script will uninstall the sensor from the old CID, install it in the new CID, and migrate any existing sensor and Falcon grouping tags. The script also creates a recovery file to facilitate resuming the migration in case of failure.

Security Recommendations

Credential handling

Credentials travel on cURL’s configuration input rather than the command line, and every request and redirect is restricted to HTTPS. This works with the cURL that RHEL and CentOS 7 ship, and with current cURL.

Table of Contents

• Falcon API Permissions
• Configuration
  • Setting up Authentication
• Usage
  • Examples
• Troubleshooting

Falcon API Permissions

API clients are granted one or more API scopes. Scopes allow access to specific CrowdStrike APIs and describe the actions that an API client can perform.

Ensure the following API scopes are enabled for both the old and new CIDs:

• Sensor Download [read]

  Required for downloading the Falcon Sensor installation package.

• Installation Tokens [read]

  Required if your environment enforces installation tokens for Falcon Sensor installation.

• Sensor update policies [read]

  Required when using the FALCON_SENSOR_UPDATE_POLICY_NAME environment variable to specify a sensor update policy.

• Sensor update policies [write]

  Required if you want the script to automatically retrieve a maintenance token from the API. Not needed if you directly provide the maintenance token via the FALCON_MAINTENANCE_TOKEN environment variable. Maintenance tokens are required to uninstall sensors that have uninstall protection enabled.

• Hosts [read]

  Required for retrieving sensor and Falcon grouping tags.

• Hosts [write]

  Required for setting Falcon grouping tags and when using the FALCON_REMOVE_HOST=true environment variable.

  ⚠️ It is recommended to use Host Retention Policies in the Falcon console instead.

Configuration

Setting up Authentication

You must provide API credentials for both the old and new CIDs:

# Old CID credentials
export OLD_FALCON_CLIENT_ID="XXXXXXX"
export OLD_FALCON_CLIENT_SECRET="YYYYYYYYY"
export OLD_FALCON_CLOUD="us-1"  # Optional, defaults to us-1

# New CID credentials
export NEW_FALCON_CLIENT_ID="ZZZZZZZ"
export NEW_FALCON_CLIENT_SECRET="WWWWWWW"
export NEW_FALCON_CLOUD="us-2"  # Optional, defaults to us-1
export NEW_FALCON_CID="AAAAAAAAAAA"  # Optional, will be auto-detected if not provided

Auto-Discovery of Falcon Cloud Region

Caution

Auto-discovery is only available for [us-1, us-2, us-3, eu-1] regions.

The scripts support auto-discovery of the Falcon cloud region. If the [OLD|NEW]FALCON_CLOUD environment variable is not set, the script will attempt to auto-discover it. If you want to set the cloud region manually, or if your region does not support auto-discovery, you can set the [OLD|NEW]FALCON_CLOUD environment variable:

export [OLD|NEW]FALCON_CLOUD="us-gov-1"

Usage

Usage: falcon-linux-migrate.sh [-h|--help|--debug]

Migrates the Falcon sensor to another Falcon CID.
Version: 1.14.0

This script recognizes the following environmental variables:

Old CID Authentication:
    - OLD_FALCON_CLIENT_ID              (default: unset) [Required]
        Your CrowdStrike Falcon API client ID for the old CID.

    - OLD_FALCON_CLIENT_SECRET          (default: unset) [Required]
        Your CrowdStrike Falcon API client secret for the old CID.

    - OLD_FALCON_MEMBER_CID              (default: unset)
        Member CID, used only in multi-CID ("Falcon Flight Control") configurations and
        with a parent management CID for the old CID.

    - OLD_FALCON_CLOUD                  (default: 'us-1')
        The cloud region where your old CrowdStrike Falcon instance is hosted.
        Accepted values are ['us-1', 'us-2', 'us-3', 'eu-1', 'us-gov-1', 'us-gov-2'].

New CID Authentication:
    - NEW_FALCON_CLIENT_ID              (default: unset) [Required]
        Your CrowdStrike Falcon API client ID for the new CID.

    - NEW_FALCON_CLIENT_SECRET          (default: unset) [Required]
        Your CrowdStrike Falcon API client secret for the new CID.

    - NEW_FALCON_MEMBER_CID              (default: unset)
        Member CID, used only in multi-CID ("Falcon Flight Control") configurations and
        with a parent management CID for the new CID.

    - NEW_FALCON_CLOUD                  (default: 'us-1')
        The cloud region where your new CrowdStrike Falcon instance is hosted.
        Accepted values are ['us-1', 'us-2', 'us-3', 'eu-1', 'us-gov-1', 'us-gov-2'].

    - NEW_FALCON_CID                    (default: unset)
        Your CrowdStrike Falcon customer ID (CID) for the new CID.
        If not specified, will be detected automatically via API.

Migration Options:
    - MIGRATE_TAGS                      (default: true)
        Migrate the host's existing tags to the target CID.
        Accepted values are ['true', 'false'].

    - LOG_PATH                          (default: /tmp)
        Location for the log and recovery files.

Other Options
    - FALCON_MAINTENANCE_TOKEN          (default: unset)
        Sensor uninstall maintenance token used to unlock sensor uninstallation.
        If not provided the script will try to retrieve the token from the API.

    - FALCON_PROVISIONING_TOKEN         (default: unset)
        The provisioning token to use for installing the sensor.
        If the provisioning token is unset, the script will attempt to retrieve it from
        the API using your authentication credentials and token requirements.

    - FALCON_REMOVE_HOST                (default: unset)
        Determines whether the host should be removed from the Falcon console after uninstalling the sensor.
        Requires API Authentication.
        NOTE: It is recommended to use Host Retention Policies in the Falcon console instead.
        Accepted values are ['true', 'false'].

    - FALCON_SENSOR_VERSION_DECREMENT   (default: 0 [latest])
        The number of versions prior to the latest release to install.
        For example, 1 would install version N-1.

    - FALCON_SENSOR_UPDATE_POLICY_NAME  (default: unset)
        The name of the sensor update policy to use for installing the sensor.

    - FALCON_TAGS                       (default: unset)
        A comma-separated list of sensor grouping tags to apply to the host.
        If MIGRATE_TAGS=true these tags will be appended to any existing sensor tags.

    - FALCON_GROUPING_TAGS              (default: unset)
        A comma-separated list of Falcon grouping tags to apply to the host.
        If MIGRATE_TAGS=true these tags will be appended to any existing grouping tags.

    - FALCON_APD                        (default: unset)
        Configures if the proxy should be enabled or disabled.

    - FALCON_APH                        (default: unset)
        The proxy host for the sensor to use when communicating with CrowdStrike.

    - FALCON_APP                        (default: unset)
        The proxy port for the sensor to use when communicating with CrowdStrike.

    - FALCON_BILLING                    (default: default)
        To configure the sensor billing type.
        Accepted values are [default|metered].

    - FALCON_BACKEND                    (default: auto)
        For sensor backend.
        Accepted values are values: [auto|bpf|kernel].

    - FALCON_SENSOR_CLOUD               (default: unset)
        To pin the cloud region for unified sensor installations.
        This allows specifying the cloud region for unified sensors at installation time.
        Accepted values are [us-1|us-2|us-3|eu-1|us-gov-1|us-gov-2].

    - ALLOW_LEGACY_CURL                 (default: false)
        Deprecated. Accepted and ignored; no longer needed.

    - USER_AGENT                        (default: unset)
        User agent string to append to the User-Agent header when making
        requests to the CrowdStrike API.

    - FALCON_DEBUG                      (default: unset)
        Print redacted progress markers to stderr: step name, HTTP status,
        cloud/region and curl exit code. Values are dropped unless the key is
        on a fixed allow-list, so secrets cannot appear. Do not use bash -x
        for support; it prints credentials.
        Accepted values are ['1', 'true'].

This script recognizes the following arguments:
    -h, --help
        Print this help message and exit.
    --debug
        Same as FALCON_DEBUG=1.

Examples

Migrate a sensor from US-1 to US-2 with tag migration

export OLD_FALCON_CLIENT_ID="XXXXXXX"
export OLD_FALCON_CLIENT_SECRET="YYYYYYYYY"
export OLD_FALCON_CLOUD="us-1"
export NEW_FALCON_CLIENT_ID="ZZZZZZZ"
export NEW_FALCON_CLIENT_SECRET="WWWWWWW"
export NEW_FALCON_CLOUD="us-2"
curl -L https://raw.githubusercontent.com/crowdstrike/falcon-scripts/v1.14.0/bash/migrate/falcon-linux-migrate.sh | sudo bash

Migrate a sensor to EU-1 with removal from old console

export OLD_FALCON_CLIENT_ID="XXXXXXX"
export OLD_FALCON_CLIENT_SECRET="YYYYYYYYY"
export OLD_FALCON_CLOUD="us-1"
export NEW_FALCON_CLIENT_ID="ZZZZZZZ"
export NEW_FALCON_CLIENT_SECRET="WWWWWWW"
export NEW_FALCON_CLOUD="eu-1"
export FALCON_REMOVE_HOST="true"
curl -L https://raw.githubusercontent.com/crowdstrike/falcon-scripts/v1.14.0/bash/migrate/falcon-linux-migrate.sh | sudo bash

Migrate a sensor with custom tags

export OLD_FALCON_CLIENT_ID="XXXXXXX"
export OLD_FALCON_CLIENT_SECRET="YYYYYYYYY"
export NEW_FALCON_CLIENT_ID="ZZZZZZZ"
export NEW_FALCON_CLIENT_SECRET="WWWWWWW"
export FALCON_TAGS="department/it,location/hq"
export FALCON_GROUPING_TAGS="environment/production,criticality/high"
curl -L https://raw.githubusercontent.com/crowdstrike/falcon-scripts/v1.14.0/bash/migrate/falcon-linux-migrate.sh | sudo bash

Migrate a sensor from one CID to another within the same cloud

export OLD_FALCON_CLIENT_ID="XXXXXXX"
export OLD_FALCON_CLIENT_SECRET="YYYYYYYYY"
export OLD_FALCON_CLOUD="us-1"
export NEW_FALCON_CLIENT_ID="ZZZZZZZ"
export NEW_FALCON_CLIENT_SECRET="WWWWWWW"
export NEW_FALCON_CLOUD="us-1"
curl -L https://raw.githubusercontent.com/crowdstrike/falcon-scripts/v1.14.0/bash/migrate/falcon-linux-migrate.sh | sudo bash

Troubleshooting

Use the redacted debug mode. It prints, to stderr: the detected OS, architecture, kernel and package manager; both clouds and which credentials are present; the exact sensor query filter and how many installers matched; the old AID before removal and the new AID after registration; how many sensor and Falcon grouping tags were migrated; and whether the run resumed from the tag recovery file or started fresh. Note there is no automatic rollback on failure — the recovery file only preserves the old AID and tags so a retry can reapply them. Values are dropped unless the key is on a fixed allow-list, so neither the old nor the new CID credentials can appear in the output you send to support.

FALCON_DEBUG=1 ./falcon-linux-migrate.sh

or pass the flag:

./falcon-linux-migrate.sh --debug

or over a pipe:

curl -L https://raw.githubusercontent.com/crowdstrike/falcon-scripts/v1.14.0/bash/migrate/falcon-linux-migrate.sh | FALCON_DEBUG=1 bash

Do not use bash -x for support. It prints every expanded command, including OLD_FALCON_CLIENT_SECRET, NEW_FALCON_CLIENT_SECRET, access tokens, maintenance tokens and Authorization headers. This script turns tracing off at startup and warns when it does, but a trace enabled before that point can still expose credentials.

The script creates a log file at the location specified by LOG_PATH (defaults to /tmp) with the name format falcon_migration_YYYYMMDD_HHMMSS.log. This log contains detailed information about each step of the migration process.

If the migration process is interrupted, the script creates a recovery file at $LOG_PATH/falcon_migration_recovery.csv that contains information about the previous sensor’s AID and tags. When rerunning the script, it will detect this file and attempt to continue the migration process.