Rule library and updates
This guide shows you how to add ready-made rules from the rule library, how to import new signed rule packs (also on a site without internet), and how to review and roll out rule updates safely.
Before you start
- You need an administrator account to add rules, import packs and apply updates. Anyone can look at the library and the updates list.
- Words used here:
- A rule pack is a signed file
lea-rules-<version>.tgzwith many rules, plus its signature filelea-rules-<version>.tgz.sig. - A rule source is where packs come from: GSR (the LEA Open Rules library), your own sources, and local (your own edits in the console).
- A version is one stored state of a rule. Every change makes a new version; old versions are kept.
- A held host keeps running an older version of a rule until you promote it.
- A rule pack is a signed file
- See also the glossary.
How rule packs work
- A pack is imported (it ships with each LEA Platform release, or you import a newer one).
- LEA Platform checks the pack's signature. A pack that is modified or signed with an unknown key is refused.
- The rules of the pack are staged: they appear in the library and in Rules → Updates. Nothing changes on your hosts.
- You decide: add new rules from the library, and apply updates to rules you already run, to all hosts or to new hosts only.
The LEA agents are not involved. They only run what the server gives them.
Add rules from the library
- Open Rules and click Add from library at the top right, or go to Rule library.
- Use the buttons Not in use, In use and All, the search box Search the library, and Filters (Category, Framework, Platform) to find rules.
- Tick the rules you want. Select all N shown ticks the rules on the current page that are not in use yet. The list is split into pages; use the page controls under the table to move between them or change how many rules a page shows. Ticked rules stay ticked when you change page.
- Click Add N rules at the top right.
- In the dialog:
- Tick Active if hosts should start running the rules as soon as they are in a group. Leave it off to review first.
- In Add to group (optional), choose a group, or No group (decide later).
- Click Add.
You should see a message such as "3 rules added (inactive), not assigned to any group yet." It links to each new rule (up to five), so you can open it to review it, tune it or add it to a group. Show in use switches the library to the rules you already use. The rules now appear on the Rules page.
Tip: Add new rules inactive or to a small test group first, check their results, then add them to production groups. See Groups.
Library rules ship with their automatic fix switched off. See Fix hosts automatically.
Read the library table
| Column | What it shows |
|---|---|
| Severity | How serious it is when this rule fails, as the source ships it. You can change it after you add the rule. |
| Category | A word that groups similar rules, for example access control. |
| Platforms | The operating systems the rule is written for (linux, macos, windows), taken from its tags. Empty when the rule names none. |
| Frameworks | The compliance frameworks the rule is mapped to, such as CIS or ISO 27001. |
| Source | The rule source the rule comes from and the newest version of the rule there, for example GSR v3. |
| In use | Links to the rules you already made from this library rule, or NOT IN USE when you have not added it yet. |
Import a rule pack
All ways use the same checks, and none of them changes running rules.
In the console
- Open Settings → Rule sources.
- Under Import a rule pack, click Choose pack (.tgz) and pick
lea-rules-<version>.tgz. - Click Choose signature (.sig) and pick
lea-rules-<version>.tgz.sig. - In Source, choose who signed it, for example GSR.
- Click Import.
You should see a message such as "Imported lea-rules 1.2.0 into GSR (signature valid): 12 new, 30 updated, 400 unchanged, 2 retired." Click Review updates to continue in Rules → Updates.
On the LEA Platform server (air-gapped sites)
-
Copy
lea-rules-<version>.tgzandlea-rules-<version>.tgz.sigto the LEA Platform server, into the deployment directory (the folder withlea_packs.sh), for example with a USB drive. -
In that folder run:
./lea_packs.sh import lea-rules-1.2.0.tgzThe
.sigfile next to the pack is used automatically. Add--source NAMEfor a pack from your own source.
Other commands of the same script: ./lea_packs.sh sources lists the sources and their last version, ./lea_packs.sh updates counts the rules waiting in Rules → Updates.
With the LEA command line
lea rules import lea-rules-1.2.0.tgz
Add --sig FILE if the signature is not next to the pack, or --source NAME for your own source. See the CLI reference.
Automatically from a feed
A source with a Feed URL can be checked for new packs: click Check in its row, or turn on Check the feed for new packs every 6 hours and notify in the source settings. This needs network access to the feed, so it is off for the GSR source by default. A failed check shows CHECK FAILED; hover for the reason.
Manage rule sources
Settings → Rule sources has four parts.
Rollout default: what the rollout dialog preselects, and what automatic updates use: All hosts now or New hosts only (existing hosts are held).
Sources: one row per source.
| Column | What it shows |
|---|---|
| Signing key | A short fingerprint of the public key that must sign this source's packs. NO KEY: a signature is required but no key is set, so imports are refused. UNSIGNED OK: unsigned packs are accepted. |
| Policy | What happens to this source's rules after an import: they wait for review, move unmodified rules to the new version, or arrive as new inactive rules. The policies are explained below. |
| Version | The version of the last pack imported from this source. A check-only source adds → and the newer version a check found but nobody imported yet, for example 1.4 → 1.5. |
| Rules | How many different rules this source has delivered so far, retired ones included. |
| Checked | When the server last looked in this source's feed for a new pack, by hand or automatically. manual means it was never checked and automatic checks are off; pending means the first automatic check has not run yet. |
| Button | What it does |
|---|---|
| Check | Looks in the source's feed for a newer pack now. A source set to import new packs downloads and imports it straight away; a check-only source only shows the newer version in Version. |
| Import | Downloads, verifies and imports the newer pack a check-only source found. Shown only when one is waiting; nothing goes live until the update policy or you apply it. |
Click the pencil (Edit source) to change one, or Add source to add your own:
| Field | What it does |
|---|---|
| Name | The source name, used when you import. |
| Feed URL (optional) | Address of a latest.json feed. Leave empty for sources you only upload. |
| Public key (ed25519, base64) | The key that signs this source's packs. Packs signed with another key are refused. |
| Require a valid signature | On: unsigned packs are refused. Keep it on. |
| Check the feed for new packs every 6 hours and notify | Automatic checks of the feed. |
| Import new packs when a check finds them | On (default): a check downloads and imports a newer pack. Off: the source is check-only. A check shows the newer version and notifies administrators, and nothing is downloaded until someone clicks Import. |
| Update policy | See the table below. |
| Policy | What happens after an import |
|---|---|
| Manual | Everything waits in Rules → Updates. Recommended. |
| Apply to unmodified rules | Rules you did not change move to the new version with the default rollout. New rules still wait. |
| Add new rules inactive | New rules are created inactive and not in any group. Updates still wait. |
A source with signing key NO KEY cannot import anything; UNSIGNED OK accepts unsigned packs. A source can be deleted (bin icon) only while it has no rules.
Import a rule pack: see Import a rule pack.
Imported packs: every import, newest first.
| Column | What it shows |
|---|---|
| Pack | The name and version written in the pack file, for example lea-rules 1.2.0. |
| Signature | Whether the pack was proven to come unchanged from the source: VERIFIED or UNSIGNED. |
| VERIFIED | The pack's signature matched the source's public key, so nobody changed the pack after the source signed it. |
| UNSIGNED | The pack came without a signature and was accepted only because its source allows unsigned packs. |
| Changes | How many rules the import added, updated and retired, and how many the source's policy applied right away. |
| By | Who imported the pack; scheduler means the automatic feed check imported it. |
Review updates
Open Rules → Updates (also from Updates on the Rule library page, the UPDATE pill on the Rules page, or Review updates after an import).
The numbers at the top are the buckets. Click one to see its rules.
| Bucket | Meaning | What you can do |
|---|---|---|
| Updated upstream | You did not change the rule; a newer version is available. | Apply, Ignore (skip this version), Hold (stay on the current version and stop offering updates) |
| Conflicts | You changed the rule, and upstream changed it too. | Take upstream (your change is replaced, it stays in the version history) or Keep mine (skip this upstream version) |
| Retired upstream | The source no longer ships the rule. It keeps running until you deactivate it. | Deactivate or delete it on the rule page when you no longer need it. Nothing is removed automatically. |
| Ignored or held | Updates you skipped, or rules held on their version. | Track updates to be offered updates again. |
| New in the library | Rules you do not run yet. | Opens the Rule library. |
Read the updates table
| Column | What it shows |
|---|---|
| Running | The version the rule uses now: its source and version, or local edit if you changed the rule in the console. |
| Upstream | The newest version of the rule that its source offers. |
| State | Why the rule may need a second look before you apply: the source retired it, you hold it or skipped this version, or it is off. Empty when nothing applies. RETIRED: the source no longer ships the rule. HELD: you stopped updates for it. IGNORED: you skipped this version. INACTIVE: the rule is turned off. |
| Held hosts | How many hosts still run another version of this rule, because they are held or their group is pinned. |
Read the differences
Click a row to see what changed:
- In Updated upstream: one comparison "<running version> → <new version>".
- In Conflicts: two comparisons side by side. Your changes shows what you changed against the version you started from. Upstream changes shows what the source changed. Rules that existed before rule versions have no known starting point; then only your current rule against upstream is shown.
"No differences." means that part did not change.
Apply updates
The Apply N button moves the ticked rules to their newest upstream version; in Conflicts, Take upstream N also replaces your own changes. Your changes stay in the version history.
- Tick the rules, or use Select all.
- Click Apply N (or Take upstream N in Conflicts). For one rule you can also click Apply in its row.
- Choose a rollout mode in the dialog (see the next section) and click Apply.
You should see "N rules updated." With new hosts only, the message also says how many host-rule pairs are held.
When a rule is updated, its name, description, tags and severity follow the new version unless you changed them yourself. Active, interval, category, parameters and groups stay as they are. Parameters keep your values; new parameters get their default.
Choose a rollout mode
Every update and every change to a rule's commands or parameters asks how to roll it out.
| Option in the console | What it does | When to use it |
|---|---|---|
| All hosts now | Every host runs the new version from its next run. | Small or trusted changes. |
| New hosts only | Hosts that already run the rule stay on their current version (held). Hosts that get the rule later use the new version. | Changes you want to test on a few hosts first. |
| Selected hosts and groups | Only the Hosts and Groups you pick move to the new version now and are pinned to it (see Pinned hosts and groups). Every other host that runs the rule is held. Hosts that get the rule later use the new version. Offered when you apply a version from the rule's Versions tab and when you save a changed rule. | Trying a change on a test group in one step. |
Tick Use this choice as the default next time to save your choice as the default. Selected hosts and groups cannot be the default.
A safe way to update:
- Apply with New hosts only. All current hosts are held.
- Open your test group → Held rules → Update all. Only the test group moves to the new version.
- Check the results of the test group. See Read results and fix failures.
- Promote everyone: open the rule → Versions → Held hosts → Update all.
Promote held hosts
Held hosts stay on their version until you promote them. You find them in three places:
- Host page → Held rules: rules this host runs at an older version.
- Group page → Held rules: held pairs of the group's hosts and rules.
- Rule page → Versions → Held hosts: hosts that run this rule at an older version.
Read the held hosts table
Each table shows the Rule and the Host of a held pair, and:
| Column or button | What it shows or does |
|---|---|
| Runs | The version of the rule this host runs. + old parameters means it also keeps the parameter values from before the change. |
| Current | The rule's current version, the one the host moves to when you update it. |
| Why | Why the host is not on the current version: held until you promote it (HELD), or kept there by a pin (PINNED). When a group pin keeps the host there, the group is shown next to PINNED. |
| HELD | The host stayed on this version because a change was rolled out to new hosts only. It waits for you to promote it. |
| PINNED | A host or group pin keeps the host on this version on purpose, for a rollback or a test, until you update it. |
| Since | When the host was held or pinned on this version. |
| Update | Moves this host to the rule's current version from its next run, even when its own pin kept it on the old one. Not shown when a group pin keeps the host there: change the group pin on the rule's Versions tab instead, or use Update all. |
| Update all | Moves every held and pinned pair of this host, rule or group to the current version, including pairs the filter hides. On a rule or a group it also removes that rule's or that group's group pins to older versions; on a host it leaves group pins alone. You confirm in a dialog first. |
With the LEA command line: lea rules held --host web-01 lists held pairs, and lea rules promote --host web-01, --rule <rule>, --group <group> or --all promotes them.
Pin hosts or groups to a version or roll back
The rule page → Versions tab lists every version of the rule, newest first, with when it was Created.
| Column or button | What it shows or does |
|---|---|
| State | CURRENT marks the version the rule uses now; RETIRED marks a version after which the source stopped shipping the rule. Other versions have no state. |
| Origin | Where the version came from: an imported rule pack, a local edit saved in the console, or before versions (the rule as it was when versions were introduced). |
| Hosts | How many hosts run this version now. Held and pinned hosts count on the version they run. |
| By | Who created the version, by importing its rule pack or by saving a change to the rule. |
| Diff | Shows what this version changed compared with the version before it. The oldest version has no Diff. |
| Apply | Makes this version the rule's current version, forward or back. The rollout dialog asks which hosts move to it. |
| Pin hosts | Keeps the hosts and groups you choose on this version until you update them, to roll back a few hosts or to try a version on a few hosts first. A pin icon and a number, for example Pin hosts (2), show how many hosts and groups are pinned to the version. |
| Pin | Keeps the chosen hosts, and every host of the chosen groups, on this version. A group pin stays with the group: hosts that join the group later run the pinned version too, so you can pin an empty group to prepare a rollout. Hosts and groups you removed from the dialog are released. Pinning to the current version keeps them on it when the rule later moves to another version. |
To pin, click Pin hosts, choose one or more Hosts and Groups in Run vN on hosts and groups and click Pin. When the version is already pinned, the dialog opens with its pinned hosts and groups selected. Remove one and click Pin to release it.
A host can be pinned more than once for the same rule: by its own pin and through one or more groups. It then runs the lowest pinned version. The other pins stay recorded: when you remove the pin that sets the lowest version, the host moves to the lowest of its remaining pins, or to the current version when none is left. A host has one own pin per rule; pinning it directly to another version moves that pin.
Read the pinned hosts and groups table
Below Held hosts, Pinned hosts and groups lists every pin of the rule, newest version first, including pins to the current version and the hosts and groups chosen with Selected hosts and groups. Hosts pinned to the current version are not held, so they are not in Held hosts. Update all in Held hosts releases pins to older versions only.
| Column | What it shows |
|---|---|
| Version | The version the host or group is pinned to. |
| Pinned | The host, or the group, that was pinned. A group pin covers every host of the group, including hosts that join it later. |
| Hosts | How many hosts that run this rule the pin covers now. An empty group shows 0. |
| Also pinned | MULTIPLE when hosts of this pin are pinned more than once (by their own pin and by groups). The text says how many; a host pin says it is also pinned by a group. |
| MULTIPLE | Hosts of this pin are also pinned elsewhere and run the lowest of their pinned versions. Blue: they run this pin's version. Orange: some of them run a lower version from another pin; the text says how many. Removing that other pin moves them back to this one. |
| By | Who pinned it. |
| Since | When it was pinned. |
To roll back a bad change everywhere, click Apply on the previous version and choose All hosts now.
See which version a rule and a result use
When a rule has more than one version, LEA Platform marks it wherever the rule appears: the Rules page, the rule page and its preview, hover cards, group pages, the dashboard, search (⌘K) and reports.
- v3 · 4 VERSIONS (rule page and preview): the rule currently runs version 3, and 4 versions exist.
- v3 (blue, next to the rule name in lists): the current version of a rule that has several versions.
- v3 (grey, on a result): the result was evaluated with the current version.
- v2 · CURRENT v3 (orange, on a result): the result was evaluated with an older version. The host is held on that version, or it has not reported since the change.
Results show the version on the host page (Rules table), the rule page (Hosts table), the result page and preview, Execution, and in Run history. Click a version pill to open the rule's Versions tab.
With the LEA command line, lea rules list, lea rules get, lea results list and lea results get show a Version column or field for rules with several versions.
If something goes wrong
- "unknown key": the pack is signed with a key that is not the source's key. Choose the right Source, or check the source's public key.
- "bad signature" or "tampered content": the pack or signature file was changed or damaged. Copy the files again from the original.
- The source shows NO KEY: add the source's public key, or the import is refused.
- The library is empty: no pack is imported yet. Import one in Settings → Rule sources.
- A rule does not change after an update: its hosts are held. Promote them.
- CHECK FAILED on a source: the server cannot reach the feed. Hover the pill for the reason. On air-gapped sites import packs by hand.
For more, see Troubleshooting.
Related
- Write and edit rules
- Groups
- Air-gapped operation
- Rules reference
- CLI reference