Loading

Install and update prebuilt rules in air-gapped environments

Kibana downloads Elastic prebuilt rules from the Elastic Package Registry. In air-gapped environments without internet access, you can use one of the following methods to install and update prebuilt rules:

  • Use a self-hosted Elastic Package Registry: Host your own Elastic Package Registry to provide rules to your air-gapped environment. This is the recommended approach for ongoing rule management and updates.
  • Manually transfer prebuilt rules: Export rules from an internet-connected Elastic Security instance and import them into your air-gapped environment. This is a simpler approach for one-time transfers or when container infrastructure isn't available.
Note

A set of prebundled detection rules that you can install without a Elastic Package Registry are included when xpack.fleet.isAirGapped is set to true. However, to receive rule updates beyond whats bundled with your Kibana version, use one of the methods described on this page.

This method requires hosting your own Elastic Package Registry to provide prebuilt rules to your air-gapped Kibana instance. After setting up your registry, you can install and update prebuilt rules the same way as in a connected environment.

Before you can install prebuilt rules, you need to set up and run a self-hosted Elastic Package Registry in your air-gapped environment.

Note

The examples in this section use Docker commands. You can adapt them for other container runtimes.

  1. Choose your registry image

    The Elastic Package Registry is available as a Docker image with different tags. Choose the appropriate image based on your update strategy.

    Important

    When choosing an Elastic Package Registry image for production air-gapped environments, we recommend using one of the following options:

    • Versioned images: Use images that match your Elastic Stack version (for example, docker.elastic.co/package-registry/distribution:9.3.0), as described in the Fleet documentation. This is the safest option for environments where you cannot immediately upgrade your Elastic Stack when new versions are released.
    • Production images: Use an image like docker.elastic.co/package-registry/distribution:production only if you keep your air-gapped Elastic Stack up-to-date. If you want to rely on the production image for the most recent Fleet packages and prebuilt detection rules, upgrade your Elastic Stack as soon as new versions are released. This minimizes the risk of encountering breaking changes between the Elastic Package Registry and your Elastic Stack version.

  2. Pull and transfer the image

    1. On a system with internet access, pull your chosen Elastic Package Registry distribution image:

      docker pull docker.elastic.co/package-registry/distribution:9.3.1

      Or, if using the production image:

      docker pull docker.elastic.co/package-registry/distribution:production

    2. Save the Docker image to a file:

      docker save -o package-registry.tar docker.elastic.co/package-registry/distribution:<image-tag>

      Replace <image-tag> with your chosen tag (for example, 9.3.0 or production).

    3. Transfer the image file to your air-gapped environment using your organization's approved file transfer method.

    4. Load the image into your container runtime:

      docker load -i package-registry.tar

  3. Start the Elastic Package Registry container

    Run the Elastic Package Registry container:

    docker run -d -p 8080:8080 --name package-registry docker.elastic.co/package-registry/distribution:<image-tag>

    Replace <image-tag> with your chosen tag.

    For more setup options and details, refer to Host your own Elastic Package Registry.

  4. Configure Kibana

    Configure Kibana to use your self-hosted Elastic Package Registry and enable air-gapped mode. Add the following to your kibana.yml configuration file, then restart Kibana:

    xpack.fleet.registryUrl: "http://<your-registry-host>:8080"
xpack.fleet.isAirGapped: true
    • xpack.fleet.registryUrl: Points Kibana to your self-hosted registry. Replace <your-registry-host> with the hostname or IP address of your registry.
    • xpack.fleet.isAirGapped: Enables air-gapped mode, which allows Fleet to skip requests or operations that require internet access.

After your self-hosted Elastic Package Registry is running and Kibana is configured to use it, you can install prebuilt rules:

  1. In your air-gapped Elastic Security instance, find Detection rules (SIEM) in the navigation menu or by using the global search field, then go to the Rules table.

  2. Click Add Elastic rules. The available prebuilt rules from your self-hosted registry are displayed.

  3. Install the prebuilt rules you need:

    • To install all available rules, click Install all.
    • To install specific rules, select them and click Install x selected rule(s).
    • To install and immediately enable rules, click the options menu (Vertical boxes button) and select Install and enable.

For more details about enabling installed rules, refer to Install and enable Elastic prebuilt rules.

To update your prebuilt rules, first update your self-hosted Elastic Package Registry with a newer distribution image, then install the rule updates in Elastic Security.

Important

Elastic releases prebuilt rule updates continuously. To receive the latest updates in an air-gapped environment, we recommend updating your self-hosted Elastic Package Registry at least monthly. Prebuilt rule updates are version-specific. Updating your Elastic Package Registry provides rule updates designed for your current Elastic Stack version, not rules designed for newer versions. To receive rules designed for a newer version, you must upgrade your entire Elastic Stack.

  1. Update your self-hosted Elastic Package Registry

    1. Follow the same process described in Pull and transfer the image to pull a newer image version, save it, transfer it to your air-gapped environment, and load it.

    2. Restart the Elastic Package Registry container with the updated image:

      docker stop <container-name>
docker rm <container-name>
docker run -d -p 8080:8080 --name <container-name> docker.elastic.co/package-registry/distribution:<image-tag>

      Replace <container-name> with your container's name and <image-tag> with the appropriate version tag.

  2. Install rule updates

    After updating your registry, install the rule updates in your air-gapped Elastic Security instance:

    1. Find Detection rules (SIEM) in the navigation menu or by using the global search field, then go to the Rules table.

    2. If updates are available, the Rule Updates tab appears. Click it to view available updates.

    3. Review the updates and install them:

      • To update all rules, click Update all.
      • To update specific rules, select them and click Update x selected rule(s).
      • To review changes before updating, click a rule name to open the rule details flyout and compare versions.

    For more details about updating prebuilt rules, refer to Update Elastic prebuilt rules.

If you cannot set up a self-hosted Elastic Package Registry, you can manually export prebuilt rules from an internet-connected Elastic Security instance and import them into your air-gapped environment.

This method is useful when you don't have container infrastructure to host an Elastic Package Registry, need to transfer a specific subset of rules, or want a simpler one-time transfer without ongoing registry maintenance.

Note

When using the export import method:

  • Rule actions and connectors are imported, but you must re-add sensitive connector credentials.
  • Value lists that are used for rule exceptions are not included. You must export and import them separately. Refer to Manage value lists for more details.

For more details on exporting and importing rules, refer to Export and import rules.

  1. Export rules from an internet-connected instance

    1. On an internet-connected Elastic Security instance, install the prebuilt rules you need.

    2. Export the prebuilt rules:

      1. Find Detection rules (SIEM) in the navigation menu or by using the global search field, then go to the Rules table.
      2. Select the rules you want to export, or click Select all to select all rules.
      3. Click Bulk actions → Export.

    3. Transfer the exported .ndjson file to your air-gapped environment using your organization's approved file transfer method.

  2. Import rules into your air-gapped instance

    1. In your air-gapped Elastic Security instance, find Detection rules (SIEM) in the navigation menu or by using the global search field, then go to the Rules table.

    2. Click Import rules above the Rules table.

    3. Drag and drop the .ndjson file containing the exported rules.

    4. (Optional) Select overwrite options if you're updating existing rules.

    5. Click Import to add the rules.

  3. Update rules

    1. To get rule updates, repeat this export import process after updating your prebuilt rules on the internet-connected instance.
    2. When importing rules, select Overwrite existing detection rules with conflicting "rule_id" to update existing rules.