Skip to content

Documentation

Read results and fix failures

This guide shows you how to read a rule result, find out exactly why a rule fails on a host, and fix it. It also covers the Execution page, run history, comparing runs, the host Terminal and function artifacts.

Before you start

  • You need a console account. Any role can read results. Running Terminal commands and editing rules needs an administrator.
  • A result is one run of one rule on one host. LEA Platform keeps every result, so you can always see what the host reported and why the server decided as it did.
  • Terms used here (verdict, expectation, remedy) are explained in the glossary.

How a result is decided

  1. The LEA agent on the host runs the rule's validation commands. These commands only read the current state, for example cat /etc/ssh/sshd_config.
  2. The agent sends the raw output to the server: the text the command printed (stdout), its error messages (stderr) and its exit code (return code, RC).
  3. The server compares the output with the rule's expectations. An expectation is a pattern that must appear, a pattern that must not appear, or an exit code.
  4. If every expectation is met, the verdict is PASS. If one is not met, the verdict is FAIL and the server records which one failed.

The agent never decides compliance. The decision is made on the server, so you can always explain a FAIL from the stored output.

What PASS, FAIL and INFO mean

PillMeaningWhat to do
PASSEvery expectation of the rule was met by the latest output.Nothing.
FAILAt least one expectation was not met. The result shows which one.Follow A rule fails: what to do.
INFONo PASS/FAIL verdict. The rule has no expectations and only collects data (for example a package list), or it has no usable verdict for this host yet, for example it has not run yet. It never affects compliance.For a rule without expectations: nothing. Otherwise wait one rule interval. If it stays INFO, see If something goes wrong.

On pages about whole rules you see PASSING, FAILING and INFO instead. On pages about hosts you see COMPLIANT, NON-COMPLIANT and NO RESULTS. See Check compliance.

Use the Execution page

The Execution page lists the latest result of every rule on every host. Turn off Latest Rules Only to see every run instead (see See every execution type).

  1. Open Execution in the left sidebar.
  2. Read the summary row: Results, Passing, Failing, Critical failing and Pass rate (passing results out of results with a verdict). Click a number to filter on it.
  3. Type a host name in Host or a rule name in Rule and press Enter.
  4. Click All, Passing, Failing or Info to filter by verdict. Each shows its count; All is the three added together.
  5. Click Filters for Group, Severity and Period (only results last checked within Last hour, Last 24 hours or Last 7 days; All time by default), and use its Host metadata section for host details such as the operating system. Every active filter shows once, as a chip under the filter bar; click its x to remove it.
  6. Use the two buttons next to the status buttons. A button is light blue when it is on and grey when it is off; click it to switch:
ButtonWhat it does
Latest Rules OnlyShows the latest result of every rule on every host. On by default; turn it off to see every run (see See every execution type).
Assigned OnlyShows only rules the host runs now through one of its active groups. On by default; turn it off to also see old results of rules no longer assigned, greyed out.
  • Click a row, the Status pill or the output text to open the result in a preview panel.
  • Click the arrow at the start of a row to expand it. You should see whether the result CHANGED or stayed UNCHANGED, the buttons Verdict & output and Run history, and the full stdout and stderr.
  • Click the clock icon in the Time column (View execution history) to see earlier runs.

To export the filtered list, click the export button (download arrow) at the top right, choose CSV or JSON and click Export.

Tip: The Execution button on a host page, rule page or result page opens this page filtered to that host, rule or both. The host or rule shows as a chip with the other active filters; click its x to remove it.

See every execution type

With Latest Rules Only off, the page lists every run in time order: checks, remedies, actions, function runs and one-off commands.

  1. On the Execution page, turn off Latest Rules Only next to All, Passing and Failing. It is on by default.
  2. Read the summary row: Runs, then Checks, Remedies, Actions, Functions and One-off commands. Click a number to show only that type.
  3. Click Filters to choose the Type and the Period (Last hour, Last 24 hours, Last 7 days or All time). The period is set for you: Last 24 hours for the whole fleet, All time when the page is filtered to one host or one rule. A period other than All time shows as a chip and on the Filters button.

The Host, Rule, Group, Severity and Host metadata filters and Assigned Only still apply. Passing, Failing and Info count runs, and every run is in exactly one of them:

FilterChecks, remedies, actionsFunctionsOne-off commands
PassingPASSOKDONE (exit code 0)
FailingFAILERROR, TIMEOUTEXIT with another code, NO RESULT, EXPIRED
InfoINFOPENDINGQUEUED, RUNNING, CANCELLED

A rule filter (Rule, Severity) hides one-off commands, because they belong to no rule; Assigned Only keeps them. One-off commands are shown to administrators only.

The table keeps its columns. Each row is one run, and the Rule column says what kind of run it is:

Tag in the Rule columnWhat ran
(none)A check: the rule's validation commands.
REMEDYThe rule's remediation, then its validation. Hover the tag to see whether a function released it.
ACTIONA rule action that a function chose (its name is shown after the rule), then the validation. It does not count as a remedy.
FUNCTIONA server-side function that ran on this result (its name is shown after the rule). Status shows OK, ERROR, TIMEOUT or PENDING, and Output its summary, or its error in red.
ONE-OFFA command sent from the Terminal; the Rule column shows the command. Status shows DONE or EXIT with the return code.

Last check becomes When, the time of each run. Assignment is empty for one-off commands. The columns cannot be sorted: runs are always newest first. Click a row to open the result (or the host, for a one-off command); expand it to see the full output. Click Latest Rules Only again to return to the latest results.

Read the Execution table

The table shows Status, Host, Rule, Severity, RC, Output, Agent Version, Last check and Assignment, in the same order and style as the host page's results and run history. Distribution, Version, IP Address and Last Seen can be turned on with the gear icon (Table settings).

ColumnWhat it shows
StatusWhether the latest run of this rule on this host met the rule's expectations. It reads PASS, FAIL or INFO. Click it to see why.
HostThe host the rule ran on.
RuleThe rule that ran. The version chip on the right shows the rule version that run used, only for rules with more than one version; it is orange when the rule has a newer version now.
SeverityHow serious it is when this rule fails, as set in the rule, from Critical down to Informative.
RCThe return code (exit code) of the rule's command in its latest run; 0 usually means the command ran without error.
OutputWhat the rule's command printed in its latest run, all lines joined into one, in red when it printed only errors. Multi-line output such as JSON stays readable. Expand the row for the full stdout and stderr.
Agent VersionThe version of the LEA agent installed on the host. Shows — when the agent has not reported it.
Last checkWhen the latest result arrived. Click the clock icon for earlier runs.
AssignmentWhether the host still runs this rule through one of its active groups: "assigned" or "not assigned". Rows that are not assigned are greyed out; their result is history.
DistributionThe operating system the host reported, for example Ubuntu or Red Hat Enterprise Linux. Shows — when the host has not reported it.
VersionThe version of the host's operating system, for example 22.04, not the version of the rule or the agent. Shows — when the host has not reported it.
IP AddressThe address the host reported.
Last SeenWhen the LEA agent on this host last contacted the server, which can be later than the result's Last check.

An expanded row shows one of these pills:

PillMeaning
CHANGEDThe latest run gave a different verdict than the run before it, for example PASS became FAIL.
UNCHANGEDThe latest run gave the same verdict as the run before it.

Open the result of one rule on one host

Each rule on each host has its own result page at /hosts/<host id>/rules/<rule id>. Open it in any of these ways:

  • Click a rule in the host preview or on the host's Rule results tab, then click Open result page.
  • Click a row on the Execution page, then Open result page.
  • Click a host on the rule's Hosts tab.

The top of the page shows the rule name "on" the host name, the verdict pill and the rule's severity. The line below links to the host and the rule and tells you when the rule last ran (last check) and how long the result has been in its current state (in this state since).

Buttons at the top right:

ButtonWhat it does
ExecutionOpens the Execution page filtered to this host and rule.
Edit ruleOpens the rule editor (administrators).
Ask AIAsks the AI assistant about this result, when the assistant is turned on.
Link iconCopies a link to this page.
More actions (three dots)Pin, copy name and other actions.

The page has two tabs: Latest result and Run history.

Read the latest result

The Latest result tab has four panels.

Last check (left, top):

  • The time of the run, the return code (rc) and the verdict pill.
  • A red box when the result failed. The first line is the failure message. Each line below names one failed expectation, for example "expected a match for (?mi)^[ \t]*PermitRootLogin[ \t]+no\b in stdout" or "expected no match for ... in stdout".
  • STDOUT: the raw output of the validation command.
  • STDERR: error messages, shown in red, only when there are any.
  • An Artifact panel when a server-side function ran on this result. See Read function artifacts.

If you see "This rule is not currently assigned to the host through any active group", the result is old. The host no longer runs this rule.

Last remedy (left, below; only when the rule has remediation): when the remedy last ran, its return code, REMEDIATED or REMEDY FAILED, and its output. See Fix hosts automatically.

Track record (right, top): the number of Runs, the Pass rate, the number of Remedies, the groups the rule comes from (Assigned via), any Pending remedy, and the list of Status changes.

What is checked (right, below): the rule description, its Commands for each operating system and its Expectations. Click Full definition to see the whole rule.

Search and copy the output

Long outputs, such as a full configuration file, have a search box in the header of the output panel.

  1. Type text in Find. Matches are highlighted and the box shows "1/5" (first of five matches).
  2. Press Enter for the next match and Shift+Enter for the previous one, or use the up and down arrows.
  3. Click the copy icon (Copy stdout) to copy the whole output.

Tip: Copy the real output and paste it into the rule editor's Regex Builder as sample text. You can then test a pattern against exactly what the host sends. See Write and edit rules.

Read raw output against the expectation

Compare the failed expectation with the output. The type of the failed expectation tells you what went wrong.

Failed expectationWhat it meansTypical causes
"expected a match for ..." (regex must match)The expected text is not in the output.The setting is missing or has another value. The file is in another place on this distribution. The command could not read the file.
"expected no match for ..." (regex must not match)Forbidden text is in the output.The insecure setting, process or module is present.
Return codeThe command exited with another code than expected.1 often means "not found". 126 or 127 mean "not executable" or "not installed". "Permission denied" in stderr means the agent may not read the file.

Patterns are Python regular expressions. Some parts you will see often:

Part of a patternMeaning
(?m) at the start^ and $ match at the start and end of each line, not only of the whole output.
(?i) at the startIgnore upper and lower case.
^[ \t]*Start of a line, then optional spaces or tabs. Lines that start with # (comments) do not match.
\bWord boundary: \bsshd\b matches "sshd" but not "sshd-keygen".
\SAny character that is not a space. \S alone means "the output is not empty".
A|BA or B.

Example. The rule "SSH Root Login Disabled" expects a match for (?mi)^[ \t]*PermitRootLogin[ \t]+no\b|LEA_RULE_no_service in stdout. The host sends:

# Authentication:
#PermitRootLogin prohibit-password
PermitRootLogin yes

There is no line that starts with PermitRootLogin no, so the expectation fails. The line PermitRootLogin yes is the cause. The commented line does not count.

LEA_RULE_no_service is a marker that some rules print when the service they check is not running. A rule that accepts the marker passes on hosts without that service. See Write and edit rules.

A rule fails: what to do

  1. Open the result page of the rule on the host. See Open the result of one rule on one host.
  2. Read the red box. Note which expectation failed and on which stream (stdout or stderr).
  3. Read STDOUT and STDERR. Use Find to look for the setting named in the pattern.
  4. Decide what is wrong:
    • The output shows an insecure or missing setting: the host is wrong. Go to step 5.
    • STDERR says "Permission denied", or STDOUT is empty: the agent cannot read the data. The LEA agent runs as an unprivileged user. Give that user read access to the file, or ask whoever maintains the rule. Do not add sudo to the rule.
    • The output is correct but the pattern does not match it (for example the setting is in another file, or written differently): the rule is wrong for this host. Go to step 8.
  5. Look at the host if you need more detail. Use the host Terminal tab to read the live value, for example cat /etc/ssh/sshd_config. See Run a one-off command on a host.
  6. Fix the setting on the host with your normal tools, for example edit /etc/ssh/sshd_config and reload the SSH service. If the rule has a remedy, LEA Platform may already try to fix it. See Fix hosts automatically.
  7. Wait for the next run of the rule. The rule runs again after its interval (shown as Interval (seconds) in the rule; often 3600, one hour). You should see the verdict change to PASS and a new line under Status changes.
  8. If the rule itself is wrong, click Edit rule. Test the new pattern against the output you copied, in the Regex Builder. See Write and edit rules.

Note: Changing a rule's commands or expectations opens a rollout dialog. Choose All hosts now to apply the fix everywhere. See Write and edit rules.

Look at earlier runs

  1. Open the Run history tab of the result page. The tab shows the number of runs.
  2. Use Type to show Everything, or only Checks, Remedies, Actions or Functions.
  3. Turn on Only runs that changed status to see only the moments the verdict changed.
  4. Click a row to expand it. You should see the full output of that run and, if a function ran, its artifact. For a function row you see the function's answer.
ColumnWhat it shows
StatusWhether that one run met the rule's expectations: PASS, FAIL or INFO. A function row shows OK, ERROR, TIMEOUT or PENDING. A one-off command shows DONE, EXIT with its return code, or the state from the Terminal.
ChangeWhether the verdict flipped in this run compared with the run before it. BROKE: PASS became FAIL (red bar on the left). FIXED: FAIL became PASS (green bar). Empty when nothing changed.
TypeWhat ran and why. check: the rule's validation commands. remedy: the rule's remediation, then the validation; remedy · via name when a function released it. action name: a rule action that a function chose, then the validation; an action is a step a function asked for, not a fix attempt, so it does not count as a remedy. function name: a server-side function that ran on this result (it runs on the LEA server, not on the host). one-off: a command sent from the Terminal tab.
VersionThe version of the rule this run used, shown only for rules that have more than one version. It is orange when the rule has a newer version now.
VerdictWhy the run passed or failed: the failure message, "expectations met", or "no expectations" for a rule that only collects data. For a function: its error, its summary or the action it chose. For a one-off command: the command.
OutputWhat the command printed in that run, or its error messages when it printed nothing else, with all lines joined into one line. Expand the row for the full text.
RCThe return code (exit code) of the command in that run; 0 usually means the command ran without error.
WhenThe date and time. Hover to see how long ago.

Run history on host and rule pages

The host page and the rule page also have a Run history tab, with all rules of the host or all hosts of the rule. Its columns follow the Execution table with Latest Rules Only off: Status, Host (rule page), Rule with the type tag, Severity, RC, Output, When and Assignment. On the host page, administrators also see the one-off commands sent to that host (Type → One-off commands). Turn on Status changes only there to list only the changes.

ColumnWhat it shows
ChangeHow the status changed at that moment, old → new, for example PASS → FAIL. UNASSIGNED means the host stopped running the rule. A row with Host status instead of a rule is the host's overall status.

Compare two runs

Comparing shows exactly what changed on the host between a PASS and a FAIL.

  1. Open the Run history tab of the result page.
  2. Tick the checkbox (Select to compare) of two runs, for example the last PASS and the first FAIL.
  3. Click Compare 2/2.

You should see a panel "Comparing <older time> → <newer time>" with both verdicts. For stdout (and stderr, when present) it shows each line: lines with + were added in the newer run, lines with − were removed. The header says how many lines changed, or "identical". When the verdict message changed, it is shown under the comparison.

Click the x (Close comparison) to close it.

Run a one-off command on a host

The Terminal tab runs one command on one host without creating a rule. Use it to read a live value or to test a validation command before you put it in a rule. You must be an administrator.

  1. Open the host page and click the Terminal tab.
  2. Read the line at the top: when the agent last checked in and when the next check-in is due.
  3. Type a command in the box at the bottom, for example cat /etc/os-release.
  4. Press Enter or click Run.

You should see the command with the pill QUEUED. The command runs when the agent next checks in (every 30 seconds by default), then RUNNING, then the output and the return code. Sending a command makes the host check in faster for a few minutes, so the output usually arrives within seconds.

StateMeaning
QUEUEDWaiting for the agent's next check-in. Click the x to cancel it.
RUNNINGThe agent picked it up. The output follows.
NO RESULTThe agent checked in again without sending the output back.
EXPIREDThe agent did not check in within an hour, so the command was dropped.
CANCELLEDCancelled before the agent picked it up.

Good to know:

  • Use the up and down arrow keys to recall earlier commands. Click the copy icon (Copy output) next to a result to copy it.
  • You get a "Your command finished" notification when the output arrives, even if you leave the page.
  • To make the host check in faster for longer, click Speed up check-ins and choose a duration, for example Every 5s for 15 minutes. The pill FAST CHECK-INS shows while it is on.
  • Commands run as the unprivileged agent user and must not ask for input. Destructive commands (for example disk wipes, shutdown, reading /etc/shadow) are blocked, and interactive programs (editors, shells, pagers, top) are refused. Every command, also a blocked one, is recorded in the audit log.
  • Commands and their output stay on the Terminal tab and are deleted together with old results. They also show in the host's Run history and on Execution with Latest Rules Only off, with the type one-off.

From a terminal with the LEA command line installed, the same works with lea hosts exec <host> -- <command>, for example lea hosts exec web-01 -- cat /etc/os-release. See the CLI reference.

Tip: For a value you want to watch all the time, write a rule instead. See Write and edit rules.

Read function artifacts

A function is code that runs on the LEA Platform server when a rule result arrives, for example to open a ticket or prepare a fix. What a function returns is stored as an artifact next to the result.

You find artifacts in three places:

  • On the result page, in the Last check panel under the output.
  • On the result page, in the Last remedy panel, when a function prepared the remediation.
  • In Run history, when you expand a run.

An artifact panel shows:

PartMeaning
Artifact: <function name>Which function produced it.
OK, PENDING, ERROR or TIMEOUTThe function finished, is still running, failed, or ran out of time. For ERROR and TIMEOUT the error message is shown in red.
Summary and textWhat the function reported.
"Delivered to agent with remediation at ..."The artifact was sent to the host together with the remediation.
"Artifact no longer available"The artifact was deleted, for example by data retention.

Note: Artifacts are built from output that the host reported.

To set up functions, see Functions.

If something goes wrong

  • The result stays INFO (and the rule has expectations): the host may not run the rule (check the host's Groups tab and that the rule is active), the rule may have no command for this operating system, or the host is not reporting (check Last seen). See Check compliance.
  • Every host fails with empty output and "Permission denied": the agent cannot read the file. See step 4 of A rule fails: what to do.
  • A rule passes where it should fail: the pattern may match a commented line, or a "must not match" rule passes because the output is empty. See Write and edit rules.
  • The verdict did not change after a fix: the rule has not run again yet. Check last check and the rule's interval.
  • A Terminal command stays QUEUED: the agent is not checking in. See Add and manage hosts.
  • The command was refused: it is on the blocked list or is interactive. Use a plain read command such as cat.

For more, see Troubleshooting.