Event context
An es-python machine can attach extra context to every event it reports: the command line, the environment variables and short listings of your source code. This page explains each setting, its default, and how secrets are masked.
What event context is
Event context is information about the run that an es-python machine sends along with each event, so you can tell which run produced a finding and read it without opening your code. It never marks data and never creates an event on its own. You set it in the Sent with each event part of the Configure window or the Filters page.
This section is shown for es-python machines only. It sits apart from the taint sources, so Set all sources never changes it.
Each setting has three choices:
| Choice | Meaning |
|---|---|
| Default (on) or Default (off) | no decision here: use the global setting, or if that is also unset, what the machine does on its own (named in the label) |
| On | always send it, whatever the machine was started with |
| Off | never send it, whatever the machine was started with |
As with taint sources, a machine's own setting wins over the global one (see Machine settings and account settings). A change takes effect the next time the program starts.
Command line
Command line attaches the command the program was started with, for example es-python app.py --port 8080, to every event. It is on by default, because it is the quickest way to see which run produced a finding. Values that look like passwords, tokens or keys are masked before they leave the machine.
The command line appears in the event detail, and you can search for it with the Command line field in Advanced search.
To switch it off on the machine itself, start the program with --no-report-cmdline or ES2_NO_REPORT_CMDLINE=1. A dashboard On or Off overrides that.
Environment variables
Environment variables attaches the program's environment at startup to every event. It is off by default, because environments often hold credentials. Variables whose names look like secrets are masked, but a secret stored under an ordinary name is sent as it is.
When on, the variables appear in the event detail and can be searched with the Environment field in Advanced search.
To switch it on on the machine itself, start the program with --report-env or ES2_REPORT_ENV=1. A dashboard On or Off overrides that.
Source code
Source code attaches two short listings of your program's own source to every event: the line that first received the untrusted data and the line that used it, with five lines either side of each. It is off by default, because it sends lines of your code to EyalSec. Only those two windows are read, never the whole file.
When on, the listings appear in the event detail.
To switch it on on the machine itself, start the program with --report-code or ES2_REPORT_CODE=1. A dashboard On or Off overrides that.
How secrets are masked
Values that look like secrets are replaced with [masked] on the machine before anything is sent, and masked again when the event arrives at EyalSec. Masking decides by the name of a variable or option, not by its value.
A value is masked when:
- the name of the environment variable or command-line option contains
PASS,PWD,SECRET,TOKEN,KEY,CRED,AUTH,COOKIE,SESSION,SIGNATURE,PRIVATEorDSN, in any letter case.PWDandOLDPWDare exempt, because they hold directories; - it is the password part of a URL.
Examples:
| Sent by the program | Stored by EyalSec |
|---|---|
--password=hunter2 |
--password=[masked] |
--api-key abc123 |
--api-key [masked] |
DB_PASSWORD=hunter2 |
DB_PASSWORD=[masked] |
postgres://app:hunter2@db/prod |
postgres://app:[masked]@db/prod |
MY_VALUE=hunter2 |
MY_VALUE=hunter2 (not masked: ordinary name) |
Because masking goes by name, keep Environment variables off unless you know what your environment holds. Source listings are not masked, so a credential written in the lines around a finding is sent as it is.