Details about security of communication between Eddie UI and the Elevated process

Eddie main application (UI or CLI, called Main here) runs as a normal user. Privileged work — VPN tunnel, Network Lock, routing, DNS, and similar — is done by a separate helper called Elevated, started with administrator or root rights. How that helper is started (UAC, pkexec, sudo, service, and so on) is described in Elevation.

Elevated does not expose a general shell. It accepts only a fixed set of commands with restricted parameters. This page summarizes how Main and Elevated talk, and which checks limit abuse of the helper.

Spot and service modes

Spot: Main starts Elevated for the current run (OS elevation prompt). Elevated serves that session and then exits.
Service: Elevated runs as a persistent OS service (Windows service, Linux systemd unit, or MacOS Launchd daemon). Main connects without a new elevation prompt each time. Service mode is optional and can be toggled in Preferences.

If a service is installed but Main cannot authenticate to it, Eddie falls back to spot mode.

Local communication only

Main and Elevated communicate over a local IPC channel — a Unix domain socket on Linux and MacOS, and a named pipe on Windows. The helper is not meant to be reachable from the network.

In spot mode, Main chooses an ephemeral endpoint and passes it when launching Elevated. In service mode, the endpoint is fixed (default logical port 9350, overridable with elevated.service.port on Main and service_port on Elevated).

Connection checks

After the local channel is accepted, Elevated identifies the peer using kernel-attested process information (credentials on the Unix socket, or the named-pipe client process id on Windows), then resolves that process to an executable path.

Additional rules:

One client at a time. Spot mode is single-connection: after the authorized client connects, further connections are not accepted, and Elevated exits when that session ends.
Spot binding. The client PID is passed at launch (spot_client_pid). Elevated accepts only a peer whose kernel-reported PID matches that value, so a different local process cannot attach to someone else’s spot elevation.
Integrity / co-location (release builds). The connecting executable must live in the same directory as Elevated and must pass Eddie’s integrity checks for that install. On secure (root-owned) layouts, co-location plus directory permissions are the main guarantee; on writable or portable layouts, Elevated also compares a stored hash snapshot of executables and libraries in that directory (taken at spot start or at service install). A mismatch rejects the connection (and typically triggers spot fallback when a service was expected).
Session handshake. After the gates above, Main and Elevated exchange a session key and version information for the rest of the command stream. That handshake is not a substitute for the process and integrity checks.

Official signed packages from eddie.website / airvpn.org are built so these checks apply in normal installs. Self-built unsigned trees behave according to the same rules, but without vendor code-signing of the binaries themselves.

Command surface

Only known Elevated commands are implemented. Arguments are validated on the helper side (paths, interface names, addresses, and similar). External tools (OpenVPN, WireGuard helpers, firewall utilities, and so on) are invoked with discrete arguments — not through a shell — and, where required, from a controlled staging or install location.

Compromising the unprivileged Main process can still drive legitimate Elevated operations (connect, change routes, toggle Network Lock). The design goal is to prevent turning that into arbitrary root or SYSTEM code execution through the helper.