EyalSec User Guide

What is EyalSec?

EyalSec is a safer version of Python. You install it next to your normal Python and run your programs through it exactly as you do today — nothing in your code has to change.

While your program runs, EyalSec quietly watches for one specific danger: when data that came from the outside world (the internet, a file, something a user typed) is about to be used in a risky way — like running a system command or a database query. That combination is how most real-world hacks happen.

When EyalSec sees it, it can do one of two things, and you choose which:

• Report — let the program keep running, but record what happened on your dashboard so you can see it.
• Raise — stop the risky action before it runs, so an attack is blocked instead of just recorded.

You manage everything from one website: your dashboard. It shows which of your machines have EyalSec installed, what they've detected, and lets you change your settings.

Quick Start: your first 10 minutes

Follow these steps once and you'll have EyalSec running and reporting.

1. Create your account

Go to the EyalSec website and click Register. Pick a username and password.

Creating an account

2. Log in

Click Login and sign in with the account you just made. You'll land on your Dashboard.

3. Add a machine

A "machine" is any computer or server where you want to run your code through EyalSec. Open the Machines page and click Install EyalSec. EyalSec shows you a single command to copy.

Adding a machine

4. Install EyalSec on that machine

Paste the command into the machine's terminal and press Enter. It installs a new command called es-python right next to your existing python — your normal Python is untouched.

5. Run your code through EyalSec

Instead of python your_script.py, run:

es-python your_script.py

Your program behaves exactly as before. The only difference is that EyalSec is now watching it.

6. Watch events appear

Go back to the website and open the Events page. Anytime EyalSec spots untrusted data heading somewhere risky, a new event shows up here.

Events appearing on the dashboard

7. (Optional) Turn on blocking

Once you're comfortable, switch the machine to Raise mode (see "Report mode vs Raise mode" below) so EyalSec actively blocks attacks instead of only reporting them.

Report mode vs Raise mode

EyalSec has two modes. You pick the mode per machine, and you can change it anytime.

Report mode

Your program runs completely normally. Whenever untrusted data reaches a risky action, EyalSec writes an event to your dashboard so you can see what happened. Nothing is blocked. This is the safe way to start — you get full visibility without changing how anything behaves.

Raise mode

When untrusted data reaches a risky action, EyalSec stops it. It raises an error and refuses to run that action, so the risky operation never actually happens. This means a real attack is blocked in the moment, mitigating the vulnerability instead of merely recording it.

For example, if an attacker tries to sneak a system command in through a network connection, your program stops with a message like this instead of running the command:

RuntimeError: EyalSec: untrusted data from socket:1.2.3.4:443 reached sink os.system

The program is interrupted, the attack fails, and the event is still recorded on your dashboard.

Getting around your dashboard

The menu on the left of the website takes you to every page.

Dashboard

Your home page after logging in. It gives you an at-a-glance summary of recent activity across all your machines.

The dashboard

Events

The full list of everything EyalSec has detected. Each event tells you, in plain terms:

• where — the place in your code where it happened.
• repr — the actual piece of data that was involved.
• origin — where that untrusted data originally came from (for example, a network connection or a file).
• trace — the path the data travelled through your program to get there.

The events page

Machines

Lists every machine you've connected. From here you can:

• Add a new machine (get a fresh install command).
• Rename a machine so it's easy to recognise.
• Delete a machine you no longer use.
• Reinstall EyalSec on a machine, or switch it between Report and Raise mode.

The machines page

Filters

If some events are just noise you don't care about, create a filter to hide them. This keeps your Events page focused on what matters.

The filters page

Settings

Manage your account:

• Change your password.
• Change your email address (used for account recovery).
• Enable two-factor authentication (2FA) for extra login security, and save your backup codes somewhere safe.
• Create or revoke an API key if you want to read your data from the EyalSec API instead of the website.

The settings page

Plain-English glossary

• Untrusted data (also called "taint") — any data that came from outside your program and that an attacker might control: things arriving over the network, read from a file, or typed in.
• Source — the place untrusted data enters your program (a network connection, a file, or keyboard input).
• Sink — a risky action that's dangerous if fed untrusted data, such as running a system command, evaluating code, or querying a database.
• CVE — a publicly listed security vulnerability. EyalSec's engine has found real ones, including two critical issues in Django, the popular web framework.

FAQ & troubleshooting

Do I have to change my code? No. You run the same programs the same way — just with es-python instead of python.

Will Raise mode break my app? Only if untrusted data actually reaches a risky action. For normal traffic nothing changes; it only steps in at the exact moment something dangerous is about to happen. Many people start in Report mode and switch to Raise once they're confident.

I don't see any events. What's wrong? Check three things: (1) you ran your program with es-python, not plain python; (2) the machine shows as installed on the Machines page; (3) you don't have a filter hiding the events.

How do I go back to normal Python? Just use python as you always have. EyalSec is added alongside it, so your original Python is always still there.

Getting help

Still stuck? Reach the EyalSec team at support@eyalsec.com and we'll help you out.