es-python command line
Every EyalSec option you can give es-python on the command line, and the environment variable that does the same thing, in one reference.
How options and the dashboard combine
Most of these options switch something on for one run, without touching the dashboard. When the dashboard has an explicit On or Off for the same setting on this machine (or globally), the dashboard wins; when it is left unset, the option decides. See Unset means inherit.
The normal way to configure a machine is the dashboard's Configure modal. The options here are for a quick local run, a test, or a place where you cannot reach the dashboard.
Command-line flags
EyalSec flags go before the script name or -m, like any other Python option. Anything after the script name is passed to your program untouched.
es-python --make-socket-vuln --report-env app.py --port 8080
# ^ EyalSec options ^ script ^ your program's own arguments
Sources
Each flag switches on one taint source for this run. All of them are off by default.
| Flag | Switches on | Details |
|---|---|---|
--make-socket-vuln |
data received over the network | socket |
--make-file-vuln |
data read from files | file |
--make-stdin-vuln |
data read from standard input | stdin |
--make-env-vuln |
environment variable values and command-line arguments | env |
--make-foreign-vuln |
code loaded from files other users can write | foreign |
--make-weakrandom-vuln |
values from the non-cryptographic random generator | weak_random |
--make-secret-vuln |
credentials written in your source code | hardcoded |
--make-db-rows-vuln |
values read back out of a database | db_rows |
--make-everything-vuln |
all of the above except foreign | everything |
--make-everything-vuln never includes foreign. Add --make-foreign-vuln as well if you want it.
Blocking
The raise flag makes es-python stop a risky operation instead of only reporting it. It is the older, whole-run way to get Report and Raise.
| Flag | Effect |
|---|---|
--raise |
when untrusted data reaches a risky operation, raise a RuntimeError there instead of letting it run |
--raise-on-found |
the same as --raise |
--raise only applies while the machine has no Raise rules of its own. As soon as the machine (or your global settings) has at least one Raise rule, the rules alone decide what is blocked and the flag is ignored. --raise also needs at least one source switched on, because with no source nothing is untrusted. See Report and Raise.
What each event carries
These three choose what extra context is sent with every event. See Sent with each event for what each one contains and how secrets are masked.
| Flag | Effect | Default |
|---|---|---|
--no-report-cmdline |
do not send the command line | the command line is sent |
--report-env |
send the program's environment variables | not sent |
--report-code |
send a short listing of your source around where the data entered and where it was used | not sent |
Maintenance and information
These do not change what is detected. You rarely need them.
| Flag | Effect |
|---|---|
--name |
print the account and machine this es-python reports to, then exit |
-r, --refresh |
fetch this machine's latest settings from EyalSec, waiting for the answer, before running. On its own (no script) it fetches and exits |
-cc N, --check-config N |
like --refresh, but wait at most N milliseconds for the answer (0 means wait) |
-h, --help |
print all options, including these, and where the on-machine manual is |
Fuzzing flags
es-python also accepts --fuzz, --fuzz-socket, --fuzz-files, --fuzz-stdin, --fuzz-foreign, --fuzz-everything and --rf. These are experimental, not needed for normal use, and not covered by this guide. You can safely ignore them.
Environment variables
Every es-python command-line flag has an environment variable that does the same thing, for when you cannot change the command line (a service manager, a container entry point, a test runner). Set it to exactly 1 to switch it on; other values such as true or yes are ignored.
ES2_MAKE_SOCKET_VULN=1 es-python app.py
export ES2_REPORT_ENV=1
| Variable | Same as |
|---|---|
ES2_MAKE_SOCKET_VULN=1 |
--make-socket-vuln |
ES2_MAKE_FILE_VULN=1 |
--make-file-vuln |
ES2_MAKE_STDIN_VULN=1 |
--make-stdin-vuln |
ES2_MAKE_ENV_VULN=1 |
--make-env-vuln |
ES2_MAKE_FOREIGN_VULN=1 |
--make-foreign-vuln |
ES2_MAKE_WEAKRANDOM_VULN=1 |
--make-weakrandom-vuln |
ES2_MAKE_SECRET_VULN=1 |
--make-secret-vuln |
ES2_MAKE_DB_ROWS_VULN=1 |
--make-db-rows-vuln |
ES2_MAKE_EVERYTHING_VULN=1 |
--make-everything-vuln |
ES2_RAISE=1 |
--raise |
ES2_RAISE_ON_FOUND=1 |
--raise-on-found |
ES2_NO_REPORT_CMDLINE=1 |
--no-report-cmdline |
ES2_REPORT_ENV=1 |
--report-env |
ES2_REPORT_CODE=1 |
--report-code |
ES2_REFRESH=1 |
--refresh |
ES2_CHECK_CONFIG=N |
--check-config N |
Environment variables are inherited by child processes, so a program that starts other es-python programs passes them on. A flag applies only to the process you give it to.
Variables with no flag
A few settings exist only as environment variables.
| Variable | Effect | Details |
|---|---|---|
ES2_FOREIGN_CODE_ALLOW=/path:/other/path |
exempt code under these absolute path prefixes from the foreign source | foreign |
ES2_PREFER_APP_LIBS=name:name |
let your own copy of the named libraries win over the bundled ones | Bundled libraries |
ES2_NO_BUNDLED_LIBS=1 |
let your own copy of every bundled library win | Bundled libraries |
ES2_NO_SYSTEM_SITE=1 |
do not share your regular Python's installed packages | Packages |
Examples
A few common combinations.
# Watch network input for one run
es-python --make-socket-vuln server.py
# Watch everything, block on the first finding
es-python --make-everything-vuln --raise app.py
# Run the test suite with file and stdin watched, sending the environment
ES2_MAKE_FILE_VULN=1 ES2_MAKE_STDIN_VULN=1 es-python --report-env -m pytest
# Watch foreign code, trusting a shared tools directory you maintain
ES2_FOREIGN_CODE_ALLOW=/opt/team-tools es-python --make-foreign-vuln app.py