Configure a machine
The Configure window is where you choose what a machine watches for and what happens to the events it finds. This page explains how it is laid out, how per-machine settings relate to your account-wide ones, and when a change reaches the machine.
The Configure window
The Configure window holds every detection setting for one machine: which taint sources it tracks, what it attaches to each event, and the rules that decide what happens to its events. Open it with the Configure button on the machine's row on the Machines page.
The window is titled Configure · your-machine-name and has up to five parts, depending on the machine's product:
| Part | What it holds | Shown for |
|---|---|---|
| Taint sources | one control per source the product can use, plus Set all sources | es-python |
| Other | switches that mark no data, such as identity and handoff (Other) | es-python |
| Sent with each event | command line, environment variables, source code (event context) | es-python only |
| Suppressed events | whether to keep or discard events EyalSec proved safe (discard suppressed events) | es-python only |
| Rules | the rule table, Apply template… and Save as template… | es-python and es-chromium |
Every change saves as soon as you make it. There is no Save button: close the window when you are done.
When a product cannot act on part of what the window offers, a short note under the title says so. For example, es-chromium does not fetch machine configuration, so its window has no taint sources and its rules only filter what the dashboard shows.
Machine settings and account settings
Every setting exists at two levels: account-wide (global) and for one machine. You set the global level on the Filters page and the machine level in the Configure window. A machine's own taint setting always wins over the global one.
The two kinds of setting combine differently:
- Taint sources and event context override. For each source the machine uses its own setting if it has one, otherwise the global one, otherwise its local default (see Unset).
- Rules add up. A machine follows the global rules and its own rules together. A per-machine rule cannot switch off a global rule; to exempt one machine, narrow or disable the global rule and add per-machine rules where you need them.
A good pattern is to set a sensible baseline globally, then change individual machines only where they need to differ.
Unset: inherit instead of deciding
Each taint source can be On, Off or Unset (use flag). Unset means "no decision at this level": the machine inherits the global setting, and if that is also unset, it falls back to what the program was started with (a command-line flag or environment variable). Unset is the default for every source.
How the three states resolve, in order:
- The machine's own On or Off, if set.
- Otherwise the global On or Off, if set.
- Otherwise the machine's local setting: for es-python, flags such as
--make-socket-vulnor variables such asES2_MAKE_SOCKET_VULN=1(see the es-python command line). With no flag either, the source is off.
So Off is not the same as Unset: Off switches a source off even if the program was started with a flag that turns it on. Use Unset when you want the next level to decide.
Two sources behave differently. make_vuln and handoff have no flag, so on them Unset means off, and only On switches them on. See make_vuln and handoff.
The Sent with each event settings use the same idea, but their Unset option is labelled Default (on) or Default (off), naming what the machine does when nothing is set. See event context.
Set all sources
Set all sources changes every taint source in the window in one step: pick All On, All Off or All Unset (use flag). The dropdown then returns to Set all…, because it is an action, not a setting.
It covers every entry in the Taint sources section and nothing else. It does not touch the switches under Other, so switching every source on never turns on handoff, and it does not touch the Sent with each event settings, so it can never start sending your environment variables.
Turning every source on is a quick way to see everything a program does, but it can produce a lot of events on a busy application. Most people start with one or two sources, such as socket, and add more as they learn what the program does.
Other
Other holds the switches that sit with the taint sources but are not sources: they mark no data, so no event is ever attributed to them. On es-python these are identity, a check of your database queries, and handoff, which lets the EyalSec browser follow a flow from your service into the page. Each one is On, Off or Unset like a source, and Set all sources leaves them alone. See identity and handoff.
When a change reaches the machine
A change reaches an es-python machine the next time the program starts, and also within about 30 seconds while it runs. What the running program does with it depends on the kind of change:
| Change | Takes effect |
|---|---|
| a rule (Raise, Don't send) | on the next event, without a restart |
| a taint source, Sent with each event, identity or handoff | the next time the program starts |
| a Show or Hide rule | immediately, on the dashboard (nothing is sent to the machine) |
| Discard suppressed events | on the next event, without a restart (EyalSec applies it when events arrive) |
In detail, es-python fetches its configuration when a program starts, before your code runs, and then again every 30 seconds in the background. If EyalSec cannot be reached, the program runs with the last configuration it received. Taint settings are fixed for the life of a process, so after changing a source, restart the program to apply it.
es-chromium does not fetch this configuration; everything in its window filters what the dashboard shows. See es-chromium.
Templates in the Configure window
The Rules part of the window has two template controls. Apply template… copies the rules of a saved template into this machine, and Save as template… saves this machine's rules as a new template of your own. Both are described on Rule templates.