Skip to content

Commit 752acbe

Browse files
nastasha-solomonnatasha-moore-elastic
nastasha-solomon
and
natasha-moore-elastic
committed
[Security][Alerting]: Add docs for installing and updating prebuilt rules in air-gapped environments (#4972)
<!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> This PR creates [a dedicated page](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4972/solutions/security/detect-and-alert/prebuilt-rules-airgapped) for installing and updating Elastic prebuilt detection rules in air-gapped environments. The following methods are covered: - Using a self-hosted Package Registry (recommended) - Manually transferring prebuilt rules using the export/import process Fixes: - elastic/security-docs#4652 - elastic/security-docs#2932 <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> Cursor, claude-4.5-opus-high --------- Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>
1 parent a2ae128 commit 752acbe

File tree

3 files changed

+232
-0
lines changed

3 files changed

+232
-0
lines changed

‎solutions/security/detect-and-alert/install-prebuilt-rules.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,5 +88,6 @@ Some prebuilt rules serve special purposes: [Endpoint protection rules](/solutio
8888
After installing prebuilt rules:
8989

9090
* **Keep rules current**: Elastic regularly updates prebuilt rules to detect new threats. Refer to [Update Elastic prebuilt rules](/solutions/security/detect-and-alert/update-prebuilt-rules.md) to learn how to apply updates.
91+
* **Air-gapped environments**: If your deployment doesn't have internet access, refer to [Prebuilt rules in air-gapped environments](/solutions/security/detect-and-alert/prebuilt-rules-airgapped.md).
9192
* **Customize rules**: Adapt prebuilt rules to your environment by editing them directly (Enterprise) or duplicating and modifying copies. Refer to [Customize Elastic prebuilt rules](/solutions/security/detect-and-alert/customize-prebuilt-rules.md).
9293
* **Build custom rules**: Create detection logic tailored to your infrastructure. Refer to [Author rules](/solutions/security/detect-and-alert/author-rules.md).

‎solutions/security/detect-and-alert/prebuilt-rules-airgapped.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
---
2+
navigation_title: Prebuilt rules in air-gapped environments
3+
applies_to:
4+
deployment:
5+
self: ga
6+
ece: ga
7+
eck: ga
8+
products:
9+
- id: security
10+
description: Learn how to install and update Elastic prebuilt detection rules in air-gapped environments using a self-hosted Package Registry or manual export and import.
11+
---
12+
13+
# Install and update prebuilt rules in air-gapped environments [prebuilt-rules-airgapped]
14+
15+
{{kib}} downloads Elastic prebuilt rules from the {{package-registry}}. In air-gapped environments without internet access, you can use one of the following methods to install and update prebuilt rules:
16+
17+
* **[Use a self-hosted {{package-registry}}](#install-prebuilt-rules-self-hosted-epr)**: Host your own {{package-registry}} to provide rules to your air-gapped environment. This is the recommended approach for ongoing rule management and updates.
18+
* **[Manually transfer prebuilt rules](#import-export-airgapped)**: Export rules from an internet-connected {{elastic-sec}} 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.
19+
20+
::::{note}
21+
A set of prebundled detection rules that you can install without a {{package-registry}} are included when [`xpack.fleet.isAirGapped`](kibana://reference/configuration-reference/fleet-settings.md#general-fleet-settings-kb) is set to `true`. However, to receive rule updates beyond whats bundled with your {{kib}} version, use one of the methods described on this page.
22+
::::
23+
24+
## Install prebuilt rules from your self-hosted registry [install-prebuilt-rules-self-hosted-epr]
25+
26+
This method requires hosting your own {{package-registry}} to provide prebuilt rules to your air-gapped {{kib}} instance. After setting up your registry, you can install and update prebuilt rules the same way as in a connected environment.
27+
28+
### Set up your self-hosted {{package-registry}} [setup-self-hosted-epr]
29+
30+
Before you can install prebuilt rules, you need to set up and run a self-hosted {{package-registry}} in your air-gapped environment.
31+
32+
::::{note}
33+
The examples in this section use Docker commands. You can adapt them for other container runtimes.
34+
::::
35+
36+
:::::{stepper}
37+
38+
::::{step} Choose your registry image
39+
40+
The {{package-registry}} is available as a Docker image with different tags. Choose the appropriate image based on your update strategy.
41+
42+
::::{important}
43+
When choosing an {{package-registry}} image for production air-gapped environments, we recommend using one of the following options:
44+
45+
* **Versioned images**: Use images that match your {{stack}} version (for example, `docker.elastic.co/package-registry/distribution:9.3.0`), as described in the [{{fleet}} documentation](/reference/fleet/air-gapped.md#air-gapped-diy-epr). This is the safest option for environments where you cannot immediately upgrade your {{stack}} when new versions are released.
46+
* **Production images**: Use an image like `docker.elastic.co/package-registry/distribution:production` _only_ if you keep your air-gapped {{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 {{stack}} as soon as new versions are released. This minimizes the risk of encountering breaking changes between the {{package-registry}} and your {{stack}} version.
47+
::::
48+
::::
49+
50+
::::{step} Pull and transfer the image
51+
52+
1. On a system with internet access, pull your chosen {{package-registry}} distribution image:
53+
54+
```sh subs=true
55+
docker pull docker.elastic.co/package-registry/distribution:{{version.stack}}
56+
```
57+
58+
Or, if using the production image:
59+
60+
```sh
61+
docker pull docker.elastic.co/package-registry/distribution:production
62+
```
63+
64+
2. Save the Docker image to a file:
65+
66+
```sh subs=true
67+
docker save -o package-registry.tar docker.elastic.co/package-registry/distribution:<image-tag>
68+
```
69+
70+
Replace `<image-tag>` with your chosen tag (for example, `9.3.0` or `production`).
71+
72+
3. Transfer the image file to your air-gapped environment using your organization's approved file transfer method.
73+
74+
4. Load the image into your container runtime:
75+
76+
```sh
77+
docker load -i package-registry.tar
78+
```
79+
::::
80+
81+
::::{step} Start the {{package-registry}} container
82+
83+
Run the {{package-registry}} container:
84+
85+
```sh
86+
docker run -d -p 8080:8080 --name package-registry docker.elastic.co/package-registry/distribution:<image-tag>
87+
```
88+
89+
Replace `<image-tag>` with your chosen tag.
90+
91+
For more setup options and details, refer to [Host your own {{package-registry}}](/reference/fleet/air-gapped.md#air-gapped-diy-epr).
92+
::::
93+
94+
::::{step} Configure {{kib}}
95+
96+
Configure {{kib}} to use your self-hosted {{package-registry}} and enable air-gapped mode. Add the following to your [`kibana.yml`](/deploy-manage/deploy/self-managed/configure-kibana.md) configuration file, then restart {{kib}}:
97+
98+
```yaml
99+
xpack.fleet.registryUrl: "http://<your-registry-host>:8080"
100+
xpack.fleet.isAirGapped: true
101+
```
102+
103+
* [`xpack.fleet.registryUrl`](kibana://reference/configuration-reference/fleet-settings.md#fleet-data-visualizer-settings): Points {{kib}} to your self-hosted registry. Replace `<your-registry-host>` with the hostname or IP address of your registry.
104+
* [`xpack.fleet.isAirGapped`](kibana://reference/configuration-reference/fleet-settings.md#general-fleet-settings-kb): Enables air-gapped mode, which allows {{fleet}} to skip requests or operations that require internet access.
105+
::::
106+
107+
:::::
108+
109+
### Install the prebuilt rules
110+
111+
After your self-hosted {{package-registry}} is running and {{kib}} is configured to use it, you can install prebuilt rules:
112+
113+
1. In your air-gapped {{elastic-sec}} instance, find **Detection rules (SIEM)** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the Rules table.
114+
115+
2. Click **Add Elastic rules**. The available prebuilt rules from your self-hosted registry are displayed.
116+
117+
3. Install the prebuilt rules you need:
118+
119+
* To install all available rules, click **Install all**.
120+
* To install specific rules, select them and click **Install *x* selected rule(s)**.
121+
* To install and immediately enable rules, click the options menu (![Vertical boxes button](/solutions/images/security-boxesVertical.svg "")) and select **Install and enable**.
122+
123+
For more details about enabling installed rules, refer to [Install and enable Elastic prebuilt rules](/solutions/security/detect-and-alert/install-prebuilt-rules.md#load-prebuilt-rules).
124+
125+
## Update prebuilt rules using your self-hosted registry [update-prebuilt-rules-self-hosted-registry]
126+
127+
To update your prebuilt rules, first update your self-hosted {{package-registry}} with a newer distribution image, then install the rule updates in {{elastic-sec}}.
128+
129+
::::{important}
130+
Elastic releases prebuilt rule updates continuously. To receive the latest updates in an air-gapped environment, we recommend updating your self-hosted {{package-registry}} at least monthly. Prebuilt rule updates are version-specific. Updating your {{package-registry}} provides rule updates designed for your current {{stack}} version, not rules designed for newer versions. To receive rules designed for a newer version, you must upgrade your entire {{stack}}.
131+
::::
132+
133+
:::::{stepper}
134+
135+
::::{step} Update your self-hosted {{package-registry}}
136+
:anchor: update-air-gapped-epr
137+
138+
1. Follow the same process described in [Pull and transfer the image](#setup-self-hosted-epr) to pull a newer image version, save it, transfer it to your air-gapped environment, and load it.
139+
140+
2. Restart the {{package-registry}} container with the updated image:
141+
142+
```sh
143+
docker stop <container-name>
144+
docker rm <container-name>
145+
docker run -d -p 8080:8080 --name <container-name> docker.elastic.co/package-registry/distribution:<image-tag>
146+
```
147+
148+
Replace `<container-name>` with your container's name and `<image-tag>` with the appropriate version tag.
149+
::::
150+
151+
::::{step} Install rule updates
152+
:anchor: install-rule-updates-airgapped
153+
154+
After updating your registry, install the rule updates in your air-gapped {{elastic-sec}} instance:
155+
156+
1. Find **Detection rules (SIEM)** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the Rules table.
157+
158+
2. If updates are available, the **Rule Updates** tab appears. Click it to view available updates.
159+
160+
3. Review the updates and install them:
161+
162+
* To update all rules, click **Update all**.
163+
* To update specific rules, select them and click **Update *x* selected rule(s)**.
164+
* To review changes before updating, click a rule name to open the rule details flyout and compare versions.
165+
166+
For more details about updating prebuilt rules, refer to [Update Elastic prebuilt rules](/solutions/security/detect-and-alert/update-prebuilt-rules.md#update-prebuilt-rules).
167+
::::
168+
169+
:::::
170+
171+
## Manually transfer prebuilt rules to an air-gapped environment [import-export-airgapped]
172+
173+
If you cannot set up a self-hosted {{package-registry}}, you can manually export prebuilt rules from an internet-connected {{elastic-sec}} instance and import them into your air-gapped environment.
174+
175+
This method is useful when you don't have container infrastructure to host an {{package-registry}}, need to transfer a specific subset of rules, or want a simpler one-time transfer without ongoing registry maintenance.
176+
177+
::::{note}
178+
When using the export import method:
179+
180+
* Rule actions and connectors are imported, but you must re-add sensitive connector credentials.
181+
* Value lists that are used for rule exceptions are not included. You must export and import them separately. Refer to [Manage value lists](/solutions/security/detect-and-alert/create-manage-value-lists.md#edit-value-lists) for more details.
182+
183+
For more details on exporting and importing rules, refer to [Export and import rules](/solutions/security/detect-and-alert/manage-detection-rules.md#import-export-rules-ui).
184+
::::
185+
186+
:::::{stepper}
187+
188+
::::{step} Export rules from an internet-connected instance
189+
:anchor: export-rules-airgapped
190+
191+
1. On an internet-connected {{elastic-sec}} instance, [install the prebuilt rules](/solutions/security/detect-and-alert/install-prebuilt-rules.md#load-prebuilt-rules) you need.
192+
193+
2. Export the prebuilt rules:
194+
195+
1. Find **Detection rules (SIEM)** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the Rules table.
196+
2. Select the rules you want to export, or click **Select all** to select all rules.
197+
3. Click **Bulk actions** → **Export**.
198+
199+
3. Transfer the exported `.ndjson` file to your air-gapped environment using your organization's approved file transfer method.
200+
::::
201+
202+
::::{step} Import rules into your air-gapped instance
203+
:anchor: import-rules-airgapped
204+
205+
1. In your air-gapped {{elastic-sec}} instance, find **Detection rules (SIEM)** in the navigation menu or by using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the Rules table.
206+
207+
2. Click **Import rules** above the Rules table.
208+
209+
3. Drag and drop the `.ndjson` file containing the exported rules.
210+
211+
4. (Optional) Select overwrite options if you're updating existing rules.
212+
213+
5. Click **Import** to add the rules.
214+
::::
215+
216+
::::{step} Update rules
217+
:anchor: update-rules-export-import
218+
219+
1. To get rule updates, repeat this export import process after [updating your prebuilt rules](/solutions/security/detect-and-alert/update-prebuilt-rules.md#update-prebuilt-rules) on the internet-connected instance.
220+
2. When importing rules, select **Overwrite existing detection rules with conflicting "rule_id"** to update existing rules.
221+
::::
222+
223+
:::::
224+
225+
## Related documentation [prebuilt-rules-airgapped-related]
226+
227+
* [Run {{agents}} in an air-gapped environment](/reference/fleet/air-gapped.md): Guidance for setting up {{fleet}} and integrations in air-gapped environments.
228+
* [Air gapped install](/deploy-manage/deploy/self-managed/air-gapped-install.md): An overview of air-gapped setup for the entire {{stack}}.
229+
* [Configure offline endpoints and air-gapped environments](/solutions/security/configure-elastic-defend/configure-offline-endpoints-air-gapped-environments.md): How to set up {{elastic-endpoint}} artifact updates in air-gapped environments.
230+

‎solutions/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -578,6 +578,7 @@ toc:
578578
children:
579579
- file: security/detect-and-alert/install-prebuilt-rules.md
580580
- file: security/detect-and-alert/update-prebuilt-rules.md
581+
- file: security/detect-and-alert/prebuilt-rules-airgapped.md
581582
- file: security/detect-and-alert/customize-prebuilt-rules.md
582583
- file: security/detect-and-alert/mitre-attack-coverage.md
583584
- file: security/detect-and-alert/author-rules.md

0 commit comments

Comments
 (0)