es-chromium
es-chromium is the EyalSec browser: you browse the site you are testing with it, and it reports when data an attacker can influence reaches a part of the page where it could run script. This page covers what it watches, how to install and open it, what its events look like and what its configuration can and cannot do.
What es-chromium does
es-chromium is a desktop browser for security testing. While you browse, it follows page input (the URL, messages from other windows, cookies, storage, responses the page fetched) through the page's JavaScript and reports every flow that reaches a DOM sink, such as a markup write or a call that runs code. Each finding is a DOM-XSS flow that really happened in the page, from the input to the sink that used it, and it appears on the es-chromium list of your events page.
Treat it as a testing browser, not your everyday one: it reports the page URLs you visit and the values that reached a sink.
What it watches
es-chromium watches the places a web page takes input from, and the operations in the page that can turn that input into markup, code or navigation. The inputs are the sources; the operations are the sinks.
| Kind of input | Examples |
|---|---|
| The address of the page | location.hash, location.search, location.href, location.pathname, document.URL, URLSearchParams |
| Other windows | postMessage messages, window.name, document.referrer, history.state |
| Data the page fetched or stored | XMLHttpRequest and fetch responses, web storage, document.cookie |
| Page content | form input.value, document.title, data from a worker |
The sinks it reports include markup writes (such as Element.innerHTML and document.write), code sinks (such as eval), script URLs and script bodies, attribute writes, navigations, and writes to storage and cookies. Besides flows, it reports weaknesses it notices in the page itself, such as a missing Content-Security-Policy, a cookie without Secure or HttpOnly, a permissive CORS policy, a postMessage sent to '*', or an API key in a shipped script.
Install it
You add an es-chromium PC on the Machines page and run one command on that PC. The browser runs on Linux x86_64; each command installs it on one PC and is valid for 10 minutes.
- On the Machines page, choose es-chromium under Product, type a Name for the PC and click Add machine. If es-chromium is not in the list, it is not enabled for your account (see Products).
- Click Install on the new row. The panel shows a privacy notice, an authorization statement (ticked by default; a command is only shown while it is ticked) and the install command.
- Click Copy and run the command in a terminal on that PC.
There is no distro, architecture or version to choose. The full steps, and what each field means, are on Install es-chromium and Add a machine.
Open the browser
After the install, start es-chromium from a terminal with the address you want to test, for example es-chromium http://your-target.example/. It is also in your applications menu as es-chromium. If the command is not found, open a new terminal so the updated PATH is picked up.
The machine's row moves to installed the first time the browser is opened, not when the installer finishes. A browser that is installed but not opened yet stays at pending install, and that is normal. The name you gave the row is shown inside the browser, so you can tell which machine a running browser reports as.
Its events
es-chromium events have their own list. Each row reads as a flow, the source then the sink, for example location.hash -> Element.innerHTML, followed by the page it happened on. A page weakness has no flow, so its row shows only what was found, such as "cookie without Secure".
The toolbar on this list has a Browser picker in place of Machine, and a Can cause XSS button that keeps only events whose sink can run script: markup and code sinks, script URLs and bodies, attribute writes and navigations. Storage and cookie writes, style, outbound requests, messages and plain-text writes are hidden while it is on. In Advanced search the scope is the page Host.
Severity
Severity weighs where the data came from as well as where it went. Input an attacker can choose by sending you a crafted link or posting a message into the page (the URL, window.name, postMessage, the referrer) counts as high. The page's own data (fetched responses, storage, cookies, form input) is how stored XSS arrives, so it stays visible, but on its own it does not lift an event to high. A flow into a sink that provably cannot run script is graded lower. See Severity.
What its configuration can and cannot do
es-chromium does not fetch machine configuration, so everything you set for it filters what the dashboard shows. It cannot arm a taint source, raise inside the browser, or stop the browser sending.
What that means in practice:
- There are no source toggles to turn on. The browser watches all of its sources all the time.
- Rules with the Show and Hide modes work, and are the way to cut noise. Raise and Don't send are not offered.
- A rule scoped to one source matches nothing on this list, because es-chromium events do not carry a source number. Write the rule against the event text instead.
The Filters page shows the same note on its es-chromium tab.
Limits
A few things are worth knowing before you rely on es-chromium.
- It reports what happened on the pages you actually visited and the paths you actually clicked through. A page you did not open, or a code path you did not trigger, produces nothing.
- It runs on Linux x86_64 only.
- There is no Uninstall command in the row menu. To remove a browser, delete the machine on the dashboard and remove the application from the PC the way you would any other.
- es-chromium can also follow data that a monitored server put into its response, if that server runs es-python with the handoff setting turned on. This is off by default.