Running es-python

How to run your Python programs under es-python once a machine is installed, where it lives on disk, how Python versions sit side by side, and what to do when the command is not found.

What es-python is

es-python is the EyalSec Python runtime: a security-instrumented Python that you run your code with instead of your regular python. It behaves like the Python of the same version (same language, same standard library, same packages) and also watches for untrusted data reaching a risky operation, which it reports to your dashboard as an event.

You do not change your code. You only change the command that starts it.

Run your code

Once the installer has finished, swap python for es-python wherever you start a program.

es-python app.py
es-python -m pytest
es-python -m flask run
es-python -c 'print("hello")'

Every option your regular Python accepts works the same way. EyalSec adds a few of its own, listed on es-python command line.

To use es-python inside a virtual environment, create the environment with es-python itself:

es-python -m venv .venv
. .venv/bin/activate
python app.py        # inside the venv, "python" is es-python

Nothing is reported until you switch on at least one source, because every source is off by default. Turn sources on in the Configure modal, or for a single run with a command-line flag.

Settings from the dashboard

Each time es-python starts, it asks EyalSec for this machine's current settings (sources, rules, what to send with each event) and waits up to about two seconds for the answer. While the program runs, it checks again about every 30 seconds.

What that means in practice:

If EyalSec cannot be reached at startup, es-python runs with the settings it received last time. See When changes reach the machine for the full picture.

Where it is installed

The installer puts everything in your home directory, so it needs no administrator rights and does not touch the Python that came with your system.

Your regular python and python3 are left exactly as they were. To go back to normal Python, just run python.

Python versions

Each machine runs the Python version you picked when you added it, from 3.9 to 3.14, depending on what is available for that operating system. es-python matches that version exactly, so a program that runs under your python3.12 runs under an es-python 3.12.

You can install more than one version on the same computer, one machine each. They live side by side:

• es-python3.12, es-python3.13, and so on, always run that version.
• Plain es-python runs the version that was installed most recently.

Run es-python -V to see which version plain es-python is, and eyalsec info to list every build installed for your user.

PATH and "command not found"

The installer adds ~/.local/bin to your PATH in your shell's startup file (~/.bashrc, ~/.zshrc, or a fish conf.d file). A shell that was already open before the install does not read that file again, so it may not find es-python yet.

If you see es-python: command not found:

1. Open a new terminal, or run exec $SHELL in the current one.

2. Check the command exists: ls ~/.local/bin/es-python. If it does not, the install did not finish; see Troubleshooting the install.

3. Check ~/.local/bin is on your PATH: echo $PATH. If it is not (for example, your shell reads a startup file the installer did not know about), add this line to that file:

   export PATH="$HOME/.local/bin:$PATH"
   

4. Programs started by cron, systemd or another service manager do not read your shell's startup files. Call es-python by its full path there, for example /home/you/.local/bin/es-python app.py.

Also make sure you are the same user that ran the installer: es-python is installed for that user only.

Which machine is this?

A computer can hold installs for more than one machine. To see which account and machine plain es-python reports to, run:

es-python --name

It prints the account name and the machine name as they appear on the dashboard, then exits without running anything.

Speed

How much es-python slows a program down depends on the sources you switch on. With few sources on, most programs run close to their regular speed; each extra source adds work, and file on a program that reads many files adds the most. Measure your own workload before turning everything on in production.

Reinstalling and updating

To take a newer build, reinstall the machine from the dashboard; see Reinstall. After a reinstall, restart any program that is still running under the old copy: it holds a credential that no longer works, and the machine row shows old copy running until it stops.