Rules

A rule decides what happens to a group of events: show only them, hide them, stop the machine sending them, or block the risky operation. This page explains each field of a rule, the four modes, the rules every account starts with, and the warnings the editor shows.

What a rule is

A rule picks out a group of events by their name and, optionally, their source, and says what to do with them. Rules live in the Rules table of the Configure window (one machine) and of the Filters page (every machine). A rule only ever affects the events it matches.

Each row of the table is one rule. To add one, fill in the empty row at the bottom and press +. To change a rule, edit its row: every change saves as soon as you make it. To delete a rule, press × at the end of its row.

A machine follows the global rules and its own rules together. See Machine settings and account settings.

Source

Source limits the rule to events whose untrusted data came from one taint source. The default, any, matches events from every source. Pick a name from the list to target one source, or Custom number… to target a number you gave make_vuln() yourself.

• The list shows the sources the machine's product can report. In a rule, weak_random is spelled weak-random and db_rows is spelled db (see Source names in rules).
• Custom number… reveals a box for the number. It matches values marked with make_vuln(value, number) in your code (see make_vuln).
• es-chromium does not show a Source column, because its events do not carry a source a rule could match.

Event (regex)

Event (regex) is a regular expression matched against the event's name: the sink it reached, as shown in the event's Where label, for example os system or sqlite execute. Leave it empty to match every event (the same as .*). You rarely need to write one by hand: click the box to pick a whole category, such as Code execution or SQL injection, or a single event (see Suggestions).

The pattern matches anywhere in the name, so exec matches exec and also sqlite execute. Use ^ and $ to pin it to the start or end, and | for alternatives:

A pattern that is not a valid regular expression is outlined in red and is not saved until you fix it.

Keep patterns simple (words, ^, $, |, .*, character classes like [0-9]). On the dashboard a pattern ignores letter case; on the machine, where Raise and Don't send rules are applied, it is case-sensitive and shorthand classes such as \d or \w are not supported.

Suggestions

Clicking or typing in an Event (regex) box on the Filters page opens a list of suggestions in two parts:

• Categories group every event of one kind. Code execution covers everything that can run attacker-chosen code: shell commands and started programs (os.system(), subprocess.Popen()), eval() / exec(), and unsafe deserialization such as pickle.loads(). The narrower Command injection, Code injection and Unsafe deserialization categories cover one part each. The others include SQL injection, Template injection, File access and path traversal, Outbound connections (SSRF) and Secrets and weak crypto.
• Events lists every single event name, with the call in your code that reports it.

Point at a category, or move to it with the arrow keys, to see every event it covers before you pick it. On a narrow screen, tap the number beside the category instead. Typing a word (sql, socket, pickle) narrows both lists.

The events in that preview can be picked one at a time: point at Command injection and click os spawn to write a rule for that single event. In Code execution, clicking a part heading such as Command injection picks that narrower category. With the keyboard, press the right arrow on a category to move into its preview, the up and down arrows to choose, Enter to pick, and the left arrow or Escape to go back to the list.

Picking a suggestion writes its regex into the box, and the line under the box names what it is, for example Code execution · 34 events. A category's regex matches exactly the events it lists and nothing else, so a Command injection rule never catches a SQL event that happens to contain the word exec. You can still edit the regex afterwards; once it no longer matches a suggestion exactly, the line under the box disappears.

Suggestions are offered for es-python. On the es-chromium page the box is a plain regex field.

Mode

Mode is what the rule does to the events it matches. There are four modes: Show (UI) and Hide (UI) only change what you see on the dashboard, while Don't send (drop) and Raise (machine) change what the machine does. New rules default to Show (UI).

The numbers are what the API uses. Raise appears only when it is enabled for your account. es-chromium offers Show and Hide only: see Who can use it.

Show (UI)

Show (UI) narrows your events lists to the events the rule matches. Everything else is still recorded and still counts; it is just not listed while the rule is on. When several Show rules are on, an event matching any one of them is shown.

A global Show rule applies to every product's events list unless its source ties it to one product, so a Show rule written for es-python can hide es-chromium events too. A Show or Hide rule on a single machine applies when the Events page is filtered to that machine.

Hide (UI)

Hide (UI) removes the events the rule matches from your events lists. They are still recorded and still count against your event quota; switch the rule off or delete it and they reappear.

For one kind of event you have already seen, the Events page's row menu is often quicker: on es-python its Rule group writes a rule like this one for you (see Rule), and on es-chromium its Block actions hide events like it. Blocks are listed on the Filters page.

Don't send (drop)

Don't send (drop) tells the machine not to send the events the rule matches. They are never sent, never stored and never counted, so they cannot be recovered later. Use it to cut noise you are sure you never want, such as a busy but harmless operation.

The dashboard guards against the two ways a drop rule can remove more than you meant:

• An empty pattern drops everything. Adding or switching to a Don't send rule with no pattern asks you to confirm: "Empty drop rule: with no pattern, ALL events from this machine are dropped (never recorded or billed)." While such a rule is on, a warning stays above the table: "A "Don't send" rule has no pattern: every event from this machine is dropped and never recorded."
• A drop narrowed by Sanitize cannot be undone. If you pick any Sanitize option other than Any on a Don't send rule, the row warns: "Don't send" with a Sanitize choice is applied by EyalSec when each event arrives: matching events are discarded and never stored, and cannot be recovered even if a later update would judge them differently.

Don't send works on every account. It is acted on by es-python; es-chromium does not offer it, so for es-chromium only Show and Hide change anything. See When a change reaches the machine.

Raise (machine)

Raise (machine) tells the machine to block the operation the rule matches: es-python stops it with a RuntimeError instead of letting it run. es-chromium cannot block; see Who can use it. The event is still recorded, so you see what was blocked. This is how you turn on Report and Raise.

Raise must be enabled for your account (see the Raise gate). If it is not, the mode is not offered, and a Raise rule sent through the API or a template is refused with "Raise rules are not enabled for your account. Ask an administrator to enable them."

Sanitize

Sanitize narrows a rule by whether EyalSec found that the untrusted data was made safe before it reached the operation. Any, the default, ignores this. The other choices limit the rule to one verdict:

For example, a Don't send (drop) rule with Sanitized only discards, from es-python machines, the events EyalSec proved safe that match its pattern.

Only EyalSec knows the verdict, not the machine, so a narrowed rule works differently from an ordinary one:

• A Don't send rule narrowed by Sanitize is not sent to the machine. The machine sends the events as usual, and EyalSec discards the matching ones when they arrive, so they are still never stored or counted. This applies to es-python machines. To discard every suppressed event from a machine, use Discard suppressed events instead of a rule.
• A Raise (machine) rule cannot be narrowed: the machine blocks the operation before EyalSec has judged the data. Sanitize is fixed at Any for Raise rules, and a narrowed Raise rule sent through the API or a template is refused.

On

On switches a rule on or off without deleting it. A rule that is off does nothing, on the dashboard or on the machine, until you tick it again. New rules are added switched on.

The rules every account starts with

Your global rule list starts with two rules rather than an empty table: two Don't send (drop) rules on source any, one with the pattern re and one with write. They tell every machine to drop events whose name contains re or write, a conservative start that keeps early noise down.

Because a pattern matches anywhere in the name, re drops more than regular-expression operations: any event name containing those two letters, such as a name containing request or remove, is dropped too. Review both rules before relying on your events list.

They are ordinary rules and yours to change: edit their patterns, switch them off, or delete them to have machines send everything. They are added once, the first time your global rules are loaded, and never come back after you delete them.

Rule templates

A rule template is a saved set of rules you can apply to your global rules or to one machine in one step. Use Apply template… and Save as template… above the rules table, or the Templates page. EyalSec provides ready-made es-python templates for common kinds of organization, such as a web application or a data pipeline. See Rule templates.