Agent endpoints

These are the endpoints the EyalSec agents on your machines call by themselves: to report events, to fetch their configuration, and to install. You never need to call them, and they do not accept your API key; they are listed so you know what traffic to expect from a monitored machine.

How agents authenticate

An agent signs its requests with its machine's own credential, which the installer puts on the machine, not with your API key or your session. It is sent in a Secret header; the es-chromium browser sends it as a secret form field instead.

A request with a missing or unknown credential is refused with 403. A machine that is deleted, or whose product is taken off your account, stops being accepted within a few minutes. For firewalls: every call below goes to your EyalSec address (for the hosted service, https://eyalsec.com) over HTTPS.

Report an event

POST /api/create_event/ is how an agent reports an event. POST /events is the same endpoint under a shorter name.

POST /api/create_event/
POST /events

The agent sends the event's fields (the sink label, the value, the stack trace, where the data came in, and so on) as a form with each text field base64-encoded. The server answers 202 Accepted at once and stores the event in the background, which is why identical events are merged and counted rather than shown once per occurrence (see count).

A machine that sends faster than its allowance gets 429, and 503 means the service as a whole is shedding load for a moment; agents retry later. Events for a product your account does not have are refused.

Fetch machine configuration

GET /api/machine_config is how an agent picks up the settings you make in the dashboard: its taint sources, rules and what to send with each event. The answer is encrypted for that machine.

GET /api/machine_config

The answer carries an X-Config-Version header. The agent sends the last version it saw in the same header, and gets 304 Not Modified with no body when nothing has changed. es-python fetches it when a program starts and then about every 30 seconds; see when changes apply. es-chromium does not fetch it at all.

Look up the machine's name

GET /api/machine_name returns the owner's username and the machine's display name as plain text, such as alice / web-01. An agent uses it to show which account and machine it reports to.

GET /api/machine_name

Install and uninstall

The install command you copy from the Machines page downloads its installer from these endpoints. They need no API key: the one-time secret in the command is what authorizes them. See Install.

POST /install.sh
POST /install/payload
POST /uninstall.sh

/install.sh checks the one-time secret and returns an installer for that machine; the installer then fetches /install/payload. The payload supports HTTP range requests, so an interrupted download can resume (for example with curl -C -). /uninstall.sh returns the removal script for the uninstall command. es-chromium has its own installer address, and the command the Machines page gives you already names it (see Install es-chromium).

The public lists GET /api/supported_os_types/ and GET /api/supported_python_versions/ are also used during setup to offer the available targets.

The installer also reports whether it succeeded. A failed install moves the machine to failed on the Machines page; see troubleshooting.