Skip to content

Documentation

Your first function

This guide walks you through a complete first function, from nothing to a result on a real host, using only the console. The function records why a rule fails on a host. It uses Record only, so it cannot change anything on your hosts. At the end you see the same steps with the lea command line.

Before you start

You need:

  • The admin role, and your password (or your single sign-on login). Uploading code asks you to confirm who you are.
  • A rule that currently fails on at least one host. Open Execution or Compliance and note one failing rule and one host it fails on. Any rule works; this guide uses "SSH Root Login Disabled" as the example.
  • About 15 minutes.

You do not need to write code for this first function. The starter already does the job.

If you have not read it yet, What functions are explains the words used below (hook, artifact, verdict).

Create the function from a starter

  1. Open Settings → Functions.
  2. Click New function (top left of the page).
  3. In Name, type failure_note. Names use lowercase letters, digits and _ only (at most 64 characters).
  4. In Starter, keep python. The text under it reads "Records why a rule fails on a host".
  5. Leave Description, Entrypoint (python3 main.py) and Timeout (seconds) (30) as they are.
  6. Leave Arguments, Secrets and Environment passthrough empty. Leave Pass the AI provider settings unticked.

You should see: no red message at the bottom of the dialog. The console checks the settings while you type.

The starter's code does this: when the verdict is FAIL, it records the rule name, the host name and the reason the rule failed. For any other verdict it records a short note and sends nothing to the host.

Tip: Download starter (.zip) saves the same folder to your computer, so you can keep it in your code repository and change it later. You can upload that .zip later with Upload. Code is never edited in the console.

Upload it

  1. Click Upload now.

    You should see: the Upload function dialog, already on the Review step, with the report of your function.

  2. Read the report (next section), then click Upload and activate.

    If the button says Upload for approval, your site requires a second administrator. See Uploads, approvals and signatures.

  3. The console now asks you to confirm who you are. A dialog titled Confirm it is you opens:

    • If you sign in with a password, type it in Password and click Confirm. The confirmation stays valid for 10 minutes in this browser session, so you are not asked again for the next steps.
    • If you sign in with single sign-on, click Re-authenticate. You sign in again at your identity provider and come back to this page. Then repeat the action: click New function again and do the steps once more. This time the upload goes through without asking.
    • If you added a passkey, click Use passkey and confirm on your device. The upload continues. With Google sign-in this is the only way; see Passkeys.

You should see: the message "failure_note is active (upload #1). Attach it to a rule in the rule editor and set its secrets below." Click Done. A card for failure_note appears with the status AVAILABLE.

Review the upload report

The report shows what you are about to install. Nothing is stored until you click the upload button.

Part of the reportWhat to check
Status pillsUNSIGNED is normal unless your site requires signatures. NEW FUNCTION means no function with this name exists yet
EntrypointThe command that starts the function: python3 main.py
Timeout30s: the function is stopped after 30 seconds
Secrets—: this function needs none
Environment passed—
Content digestA fingerprint of the code. The same code always gives the same digest
Filesfunction.json, main.py, lib/lea_function.py, README.md, sample_event.json

A red box at the top lists errors. The upload button stays disabled until they are fixed. For a new version of an existing function, the report also shows exactly which lines changed.

Set secrets

This first function needs no secrets, so its card says "This function declares no secrets." Most real functions need one (an API token, for example). You set secrets the same way for any function:

  1. On the function's card, under Secrets, find the secret's name. It shows NOT SET.
  2. Click the pencil icon (Set value).
  3. Paste the value into Value and click Save. Confirm who you are if asked.

The value is encrypted when you save it and is never shown again. You can replace or delete it later.

Try it with a test run

A test run runs the function on a real result, exactly as a rule would, but sends nothing to the host.

  1. On the failure_note card, click Test run.
  2. In Rule, type part of your failing rule's name and pick it from the list.
  3. Under Pick a result, click FAIL to show only failing hosts, then click the row of your host.
  4. Click Run test.

You should see, after a few seconds, Test run #N with the status OK and an Artifact like this:

{
  "summary": "SSH Root Login Disabled fails on web-01",
  "reason": "expected result not found",
  "rule_id": 12,
  "host": "web-01"
}

Below it, Event sent shows the exact data the function received. Keep this in mind for when you write your own code.

If the status is ERROR, read the Error and stderr boxes. See When a function does not work.

Attach it to a rule

  1. Open Rules and click your failing rule.
  2. Click Edit (top right).
  3. In the list of sections on the left, click Functions.
  4. Click Add function. A card appears.
  5. In Function, pick failure_note.
  6. Set Run when to Verdict fails.
  7. Next to for results of, keep only validations ticked.
  8. Leave Only when the output matches empty (no conditions).
  9. Set Then on the host to Record only.

You should see the hint "The output is stored as an artifact next to the result; nothing is sent to the host."

Save the rule

  1. Click Save rule (top right).

If you only changed the Functions section, the rule is saved at once and you return to the rule list. The hook applies to every host that runs the rule.

If you also changed the rule's commands, remediation, actions or parameters, a dialog asks how to roll out that change:

  • All hosts now: every host that runs the rule gets the change.
  • New hosts only: hosts that already run the rule keep their current version until you promote them.

Pick one and click Apply. The function hook is saved together with it. If you click Cancel, the definition and the hook are not saved (other changes, such as the name, are). See Rule library and updates for details on rollout.

Check that it ran

The function runs the next time the host checks the rule (on the rule's schedule) and the result is FAIL.

  1. Open Settings → Functions. On the failure_note card, under Used by rules, you should see your rule with "on fail of validation · record only".
  2. Wait for the rule's next check on the host. Under Recent runs a row appears with your host and rule, Status OK, Trigger validation and Delivered — (nothing was sent to the host, as intended).
  3. Click the Host · rule link in that row, or open Execution and click the row of your host and rule. Under Last check, below the output, a box titled Artifact: failure_note shows OK and the summary in bold.

The function does not run again while the host keeps sending exactly the same output. The same artifact stays attached to every new result. It runs again when the output changes, or after the rule passed and fails again.

You have built, tested and attached your first function.

Do the same with the lea command line

Use this when you keep functions in a code repository and want to upload them from a terminal or a CI pipeline.

Before you start (command line)

  • Install the lea command line from My account → Command line and sign in with lea login --server https://lea.example.com (replace with your LEA Platform address).
  • Uploads and secrets need a personal access token with the functions scope. The normal lea login sign-in cannot upload. Create the token as described in Uploads, approvals and signatures and save it in a file only you can read, for example ~/lea-functions.token.

Steps

  1. Create the starter folder. The folder name becomes the function name:

    lea functions init ./failure_note --template python
    cd failure_note
    
  2. Run it on your computer with the sample event (needs Python 3.9 or later):

    python3 lib/lea_function.py run . --event sample_event.json
    

    You should see "status": "ok" and the artifact.

  3. Check it against the server without storing anything:

    lea functions validate .
    
  4. Upload it with the token:

    LEA_TOKEN="$(cat ~/lea-functions.token)" lea functions push .
    

    You should see that the function is activated (or staged for approval when your site requires it).

  5. Test it on the latest result of a host and rule. Replace web-01 and the rule name with yours:

    lea functions test failure_note --host web-01 --rule "SSH Root Login Disabled" -f
    
  6. Attach it to the rule in the console, as in Attach it to a rule.

  7. Watch its runs:

    lea functions runs failure_note -f
    

To set a secret from the command line, the value is read from the keyboard (hidden) or from standard input, never from the command itself:

LEA_TOKEN="$(cat ~/lea-functions.token)" lea functions secrets set failure_note TICKET_API_TOKEN

All lea functions commands are listed in the CLI reference.

Next steps

If something goes wrong

  • Upload now or Upload and activate asks you to confirm who you are again and again: see When a function does not work.
  • failure_note is not in the Function list of the rule editor: reload the rule editor page. Functions uploaded after you opened the editor do not appear until you reload.
  • No row appears under Recent runs: the rule has not run on a failing host yet, or the hook does not match. See When a function does not work.