Functions on rules
This guide explains what functions are, when to use them instead of a remediation, and what every field in the console means. Read it once before you build your first function with Your first function.
Before you start
- You need the admin role to create, upload or attach functions. Other users can see functions and their results.
- You should know what a rule, a verdict (PASS or FAIL) and a remediation are. If not, read Write and edit rules and Fix hosts automatically first.
What a function is
A function is a small program that you write (in Python or shell) and upload to LEA Platform. It runs on the LEA server, never on your hosts. It runs when a rule result comes in from a host and that result matches the conditions you set on the rule.
The function receives the result as data: which host, which rule, the PASS or FAIL verdict, and the raw output the host sent. It does its job (for example, opens a ticket) and prints a short answer. LEA Platform stores that answer next to the result. The stored answer is called the artifact. Every console user can read it on the result.
A function attached to a rule is called a hook. One rule can have up to 8 hooks, each with a different function.
Why use a function
Use a function when the work must happen on the server side, not on the host:
- Reach systems only the LEA server can reach. Your ticketing system, CMDB, internal certificate authority (CA) or chat server are often on a network your hosts cannot reach. The LEA server can.
- Keep secrets off the hosts. API tokens and passwords for those systems are stored encrypted in LEA Platform as function secrets. They are given only to the function, only while it runs. Hosts never see them.
- Decide per host. The function can look at the host's output and work out what that host needs (a certificate, a configuration file with its own values, which of two fixes to run).
- Record or enrich. Add the host owner, a ticket number or an inventory value to the result, so the people reading it have what they need.
How a function runs
1. Host runs the rule's validation command and sends the raw output
|
v
2. LEA server checks the output, decides PASS or FAIL (the verdict)
|
v
3. Hook on the rule does this result match? (verdict, kind of result, output conditions)
| yes
v
4. Your function runs on the LEA server, in a sandbox, with its secrets
|
v
5. Artifact the function's answer, stored next to the result
|
v (only if the hook is set to send something to the host)
6. Host, next check-in gets the remediation or one of the rule's actions,
plus the artifact as a file (lea_artifact.json)
and any files the function returned
Step 6 is optional. Most functions only record (step 5). When a function sends work back, the host does not get new commands from the function. It gets the rule's own remediation, or one of the rule's own actions (named command lists you define in the rule). The function only chooses and supplies data files.
Every step shows in the result's Run history: the function as type function name, the work it sent as action name or remedy · via name. An action does not count as a remediation: it is not part of the remedy success rate, and a failing check after an action does not raise a Remediation failed notification. See Look at earlier runs.
Functions or remediation?
| You want to | Use | Why |
|---|---|---|
| Fix a setting on the host with a fixed command | A remediation | The host can do it alone. No server code needed |
| Open a ticket, post to chat, update a CMDB | A function, Record only | Only the server can reach those systems |
| Add the host owner or other data to a failing result | A function, Record only | The data lives in an internal system |
| Fix the host with values that differ per host (from a CMDB, a site table) | A function with Run the remediation with the output | The function computes the values; the remediation applies them |
| Choose between several fixes depending on what is wrong | A function with Let the function pick an action | The function reads the output and picks one of the rule's actions |
| Issue a certificate from an internal CA | A function with Let the function pick an action | Needs the CA (server only) and two steps on the host |
| Record a value every time it changes (inventory) | A function with Verdict passes and Record only | Runs only when the output changes |
Tip: Start with Record only. It cannot change anything on your hosts, so it is safe to try on any rule.
The Functions section of the rule editor
Open a rule, click Edit, then click Functions in the list of sections on the left. To add a hook, click Add function. Each hook is a card with the fields below, top to bottom. Manage functions (top right of the section) opens Settings → Functions in a new tab.
If the section says "No functions uploaded yet", upload a function first. See Your first function.
Function
The function this hook runs. The list shows every uploaded function with its description. A function that cannot run is greyed out and shows Unavailable with the reason. A function can be attached to a rule only once.
If the card shows Function "name" is not uploaded, the rule refers to a function that does not exist on this server (for example, a rule imported from another site). Upload the function, or remove the hook, before you save.
Run when
Which verdicts start the function.
| Option in the console | The function runs when | Typical use |
|---|---|---|
| Verdict fails | The result is FAIL | Tickets, alerts, fixes |
| Verdict passes | The result is PASS | Inventory, closing tickets |
| Every result | Any result, including rules without expectations (no verdict) | Recording output of informational rules |
Note: A rule without expectations is informational: its results are neither PASS nor FAIL. Only Every result runs on them.
for results of
Which kind of host result starts the function. Tick one or both boxes:
- validations: the normal, scheduled check of the rule.
- remediations and actions: the result the host sends after it ran the rule's remediation or one of its actions. The host runs the remediation or action, then the validation again, and reports both as one result.
Tick both only when the function must react to the result of its own action. The certificate example in Function recipes does this: the first action asks the host for a certificate request, and the function must see the answer.
Only when the output matches
Optional conditions on the host's output. With no conditions, the function runs on every result with the chosen verdict. Click Add condition to add one. All conditions must match.
| Condition | Meaning | Example value |
|---|---|---|
| contains (regex) on stdout or stderr | The output contains text matching this regular expression | BEGIN CERTIFICATE REQUEST |
| does not contain on stdout or stderr | The output does not contain text matching this regular expression | LEA_RULE_no_service |
| return code is | The command's return code equals this number | 0 |
The regular expressions use Python syntax, the same as the rule's expectations. A small icon in the field shows whether
the expression is valid. Use (?m) to make ^ and $ match at line starts and ends, and (?i) to ignore case.
Function arguments
If the function declares arguments, a field for each one appears below the conditions (a switch for true/false values). The help text under a field shows its description and default. Leave a field empty to use the default. Arguments let one function serve several rules with different settings, for example a ticket queue name.
Then on the host
What the host gets after the function finished.
| Option in the console | What happens | When to use it |
|---|---|---|
| Record only | The artifact is stored next to the result. Nothing is sent to the host. If the rule has a remediation, it still runs as usual | Tickets, chat messages, CMDB lookups, inventory, notes |
| Run the remediation with the output | The rule's remediation waits for the function. On the host's next check-in, the remediation runs with the artifact as the file lea_artifact.json and every file the function returned in its working folder | The fix needs values only the function can compute |
| Let the function pick an action | The function answers with the name of one of the rule's actions (or remedy for the remediation) and optional files. The host runs that action on its next check-in. If the function names no action, nothing is sent | Several possible fixes, or a fix in several steps |
Rules for these options. The console greys out an option that is not allowed:
- Only one hook per rule may send work to the host. Other hooks on the same rule must be Record only.
- Run the remediation with the output needs all three: Run when = Verdict fails, only validations ticked, and a remediation in the rule (Remediations section). The hint under the field says "Running the remediation needs "Verdict fails" for validations only." when this is the reason.
- Let the function pick an action needs at least one action in the rule. Add actions under Remediations →
Actions (Add action). Action names use lowercase letters, digits and
_and cannot beremedy. A rule can have up to 16 actions. - A rule can have up to 8 hooks, and each function only once.
Important: When a hook is set to Run the remediation with the output or Let the function pick an action, the rule's remediation is no longer sent on its own when the rule fails. The function's hook decides what the host gets.
Warning: With Run the remediation with the output, the remediation is sent even when the function failed. Then
lea_artifact.jsonholds the error and the function's files are missing. Write the remediation so that it does nothing harmful when its input file is missing. See Function recipes.
When you save the rule, changes to hooks apply at once to every host. Changes to the remediation or actions are part of the rule definition: the console asks how to roll them out (All hosts now or New hosts only). See Rule library and updates.
The Functions settings page
Open Settings → Functions. Administrators see everything below; other users see the function cards without the buttons.
Buttons and status at the top
| Item | What it does |
|---|---|
| New function | Opens a wizard that builds a starter folder for a new function. You download it or upload it right away |
| Upload | Uploads a function folder, a .tgz or a .zip. You see a validation report before anything is stored |
| Policy | Turns on Require approval by a second administrator and Require a signature from a trusted key, and manages the trusted signing keys |
| APPROVAL REQUIRED / NO APPROVAL | Whether uploads need a second administrator |
| SIGNATURE REQUIRED · N KEYS / SIGNATURE OPTIONAL | Whether uploads must be signed |
| Waiting for approval | A table of uploads that wait for a second administrator. Review opens one |
| Show test runs | Adds test runs to the Recent runs tables |
See Uploads, approvals and signatures for the policy.
Function cards
Each function has a card:
- Name and status. AVAILABLE (can run) or UNAVAILABLE. A signature status: SIGNED with the key fingerprint, UNSIGNED or BAD SIGNATURE. UPLOAD #N PENDING when a newer version waits for approval (click it to review).
- Test run runs the function on a real result without sending anything to the host.
- New version uploads a new version of this function.
- Starter downloads a starter folder with this function's settings, the SDK and a sample event.
- The delete icon deletes the function and its secrets. It is disabled while a rule uses the function.
- A line with the Timeout, Arguments and Environment, and a line with the content Digest (a fingerprint of the code), the upload number, who uploaded it and how, and when.
- Used by rules: every rule with a hook for this function, with a short summary such as "on fail of validation · record only".
- Recent runs: the last runs with Started, Host · rule (click to open the result), Status (OK, ERROR, TIMEOUT, PENDING), Trigger (validation, remedy, or TEST for test runs), Delivered (what was sent to the host), Duration and Error.
- Secrets: every secret the function declares. NOT SET means it has no value yet. Click the pencil to set or replace a value, the bin to delete it. Values are never shown again after saving. RE-ENTER means the value must be set again. NOT DECLARED means the function no longer asks for it, so it is not passed.
Read the Recent runs table
| Column | What it shows |
|---|---|
| Status | How the function run ended: OK means it answered, ERROR means it failed, TIMEOUT means it ran too long, PENDING means it has not finished. |
| Trigger | Which kind of host result started the run: validation is a normal check, remedy is the result after a remediation or action. Test runs show TEST. |
| TEST | A run started by hand with Test run, which sends nothing to the host. TEST #N means it tested upload number N. |
| Delivered | What this run sent to the host: the remediation, a named action, or "pending" until the host's next check-in. A dash means the hook only records. |
| Duration | How long the function ran on the LEA server, in milliseconds. |
Run a test
Test run on a function card runs the function in the sandbox on a real result, with the same event a rule hook would send. Nothing is sent to the host, and test runs do not count towards rate limits or failure notifications. Pick a Rule, click a row under Pick a result, fill in any Arguments, and click Run test.
| Column | What it shows |
|---|---|
| Verdict | Whether this host passed or failed the rule in that stored result: PASS, FAIL or INFO (no PASS/FAIL verdict). |
| Result | The number of the stored host report the test runs on. Click it to open the result of this rule on this host. |
Runtime
At the bottom, Runtime shows what the server offers to functions: the Python version, available Binaries
(such as sh, bash, curl, wget, openssl, python3), Workers (functions that can run at the same time),
limits, the Environment allow-list, and a list of installed Python packages. A red message here means functions are
disabled on this server. See When a function does not work.
When things happen
Functions run in the background. The host does not wait for them.
- The function starts within seconds after the result arrives, if a worker is free.
- Work for the host arrives on the host's next check-in after the function finished. Hosts check in every 30 seconds by default. To speed this up for one host, use Speed up check-ins on the host page.
- If the function already answered for exactly the same output, and the verdict has not changed since, the function does not run again. The earlier answer is reused, and any work for the host goes out in the reply to that same report. So a ticket function runs once per distinct failure, not on every check.
- Work held for a host is kept for 1 hour. If the host does not check in within that hour, it is dropped and the next failing check starts again.
- A function runs at most 12 times per hour for the same host, rule and function. Your operator can change this limit. Test runs do not count.
- If a function fails or times out, it is tried again the next time the host sends the same output, but not sooner than 1 minute later. The wait doubles after each failure, up to 1 hour. Administrators get a Function failed notification.
- Artifacts are kept for 30 days.
If something goes wrong
- The function is not in the list, or an option is greyed out: see When a function does not work.
- The function ran but the host did nothing: check the Delivered column on the function card and the host's last check-in. See When a function does not work.
Related
- Your first function
- Function recipes
- Writing function code
- Uploads, approvals and signatures
- Functions reference (technical)