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.

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 prebuilt rules the same way as in a connected environment.

Note

The versioned Elastic Package Registry distribution images (such as docker.elastic.co/package-registry/distribution:{{version.stack}}) include prebuilt rules. However, rule updates are released continuously, so you might need to update your registry to get the latest rules.

Before you can install or update prebuilt rules using a self-hosted registry, you must:

  • Set up a self-hosted Elastic Package Registry. Refer to Host your own Elastic Package Registry for setup instructions.

  • 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.

  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 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.

Note

The following examples use Docker commands. You can adapt them for other container runtimes.

  1. Update your self-hosted Elastic Package Registry

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

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

      Alternatively, use the production or lite image tags to get the most recent package updates:

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

    2. Save the Docker image to a file:

      docker save -o package-registry-9.3.0.tar docker.elastic.co/package-registry/distribution:9.3.0

    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-9.3.0.tar

    5. 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. Update rules

    After updating your registry, update the rules 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 a 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 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 (use 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.