Skip to content

Documentation

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>.tgz with many rules, plus its signature file lea-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.
  • See also the glossary.

How rule packs work

  1. A pack is imported (it ships with each LEA Platform release, or you import a newer one).
  2. LEA Platform checks the pack's signature. A pack that is modified or signed with an unknown key is refused.
  3. The rules of the pack are staged: they appear in the library and in Rules → Updates. Nothing changes on your hosts.
  4. 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

  1. Open Rules and click Add from library at the top right, or go to Rule library.
  2. Use the buttons Not in use, In use and All, the search box Search the library, and Filters (Category, Framework, Platform) to find rules.
  3. 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.
  4. Click Add N rules at the top right.
  5. 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).
  6. 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

ColumnWhat it shows
SeverityHow serious it is when this rule fails, as the source ships it. You can change it after you add the rule.
CategoryA word that groups similar rules, for example access control.
PlatformsThe operating systems the rule is written for (linux, macos, windows), taken from its tags. Empty when the rule names none.
FrameworksThe compliance frameworks the rule is mapped to, such as CIS or ISO 27001.
SourceThe rule source the rule comes from and the newest version of the rule there, for example GSR v3.
In useLinks 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

  1. Open Settings → Rule sources.
  2. Under Import a rule pack, click Choose pack (.tgz) and pick lea-rules-<version>.tgz.
  3. Click Choose signature (.sig) and pick lea-rules-<version>.tgz.sig.
  4. In Source, choose who signed it, for example GSR.
  5. 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)

  1. Copy lea-rules-<version>.tgz and lea-rules-<version>.tgz.sig to the LEA Platform server, into the deployment directory (the folder with lea_packs.sh), for example with a USB drive.

  2. In that folder run:

    ./lea_packs.sh import lea-rules-1.2.0.tgz
    

    The .sig file next to the pack is used automatically. Add --source NAME for 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.

ColumnWhat it shows
Signing keyA 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.
PolicyWhat 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.
VersionThe 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.
RulesHow many different rules this source has delivered so far, retired ones included.
CheckedWhen 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.
ButtonWhat it does
CheckLooks 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.
ImportDownloads, 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:

FieldWhat it does
NameThe 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 signatureOn: unsigned packs are refused. Keep it on.
Check the feed for new packs every 6 hours and notifyAutomatic checks of the feed.
Import new packs when a check finds themOn (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 policySee the table below.
PolicyWhat happens after an import
ManualEverything waits in Rules → Updates. Recommended.
Apply to unmodified rulesRules you did not change move to the new version with the default rollout. New rules still wait.
Add new rules inactiveNew 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.

ColumnWhat it shows
PackThe name and version written in the pack file, for example lea-rules 1.2.0.
SignatureWhether the pack was proven to come unchanged from the source: VERIFIED or UNSIGNED.
VERIFIEDThe pack's signature matched the source's public key, so nobody changed the pack after the source signed it.
UNSIGNEDThe pack came without a signature and was accepted only because its source allows unsigned packs.
ChangesHow many rules the import added, updated and retired, and how many the source's policy applied right away.
ByWho 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.

BucketMeaningWhat you can do
Updated upstreamYou 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)
ConflictsYou 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 upstreamThe 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 heldUpdates you skipped, or rules held on their version.Track updates to be offered updates again.
New in the libraryRules you do not run yet.Opens the Rule library.

Read the updates table

ColumnWhat it shows
RunningThe version the rule uses now: its source and version, or local edit if you changed the rule in the console.
UpstreamThe newest version of the rule that its source offers.
StateWhy 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 hostsHow 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.

  1. Tick the rules, or use Select all.
  2. Click Apply N (or Take upstream N in Conflicts). For one rule you can also click Apply in its row.
  3. 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 consoleWhat it doesWhen to use it
All hosts nowEvery host runs the new version from its next run.Small or trusted changes.
New hosts onlyHosts 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 groupsOnly 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:

  1. Apply with New hosts only. All current hosts are held.
  2. Open your test group → Held rules → Update all. Only the test group moves to the new version.
  3. Check the results of the test group. See Read results and fix failures.
  4. 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 buttonWhat it shows or does
RunsThe version of the rule this host runs. + old parameters means it also keeps the parameter values from before the change.
CurrentThe rule's current version, the one the host moves to when you update it.
WhyWhy 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.
HELDThe host stayed on this version because a change was rolled out to new hosts only. It waits for you to promote it.
PINNEDA host or group pin keeps the host on this version on purpose, for a rollback or a test, until you update it.
SinceWhen the host was held or pinned on this version.
UpdateMoves 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 allMoves 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 buttonWhat it shows or does
StateCURRENT marks the version the rule uses now; RETIRED marks a version after which the source stopped shipping the rule. Other versions have no state.
OriginWhere 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).
HostsHow many hosts run this version now. Held and pinned hosts count on the version they run.
ByWho created the version, by importing its rule pack or by saving a change to the rule.
DiffShows what this version changed compared with the version before it. The oldest version has no Diff.
ApplyMakes this version the rule's current version, forward or back. The rollout dialog asks which hosts move to it.
Pin hostsKeeps 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.
PinKeeps 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.

ColumnWhat it shows
VersionThe version the host or group is pinned to.
PinnedThe host, or the group, that was pinned. A group pin covers every host of the group, including hosts that join it later.
HostsHow many hosts that run this rule the pin covers now. An empty group shows 0.
Also pinnedMULTIPLE 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.
MULTIPLEHosts 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.
ByWho pinned it.
SinceWhen 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.