Skip to main content

EntryGuard Agent (eg-agent)

The EntryGuard Agent is a lightweight daemon that runs on Linux and Windows machines. It has two capabilities:

  • Script mode — Applies IP whitelisting rules by executing your own scripts. Each resource has a script directory with numbered apply/revoke scripts. Covers use cases where there's no cloud API — on-prem servers, VPS instances, self-hosted services.
  • Tunnel mode — Creates secure TCP tunnels to services in private networks (databases, APIs, internal tools). No VPN, no public IPs needed.

How It Works​

┌──────────────┐         ┌──────────────────┐         ┌───────────────────────────┐
│  EntryGuard  │◄───────►│    eg-agent       │────────►│  Script Directory          │
│  Server      │  polls  │    (daemon)       │  runs   │  apply/01-ufw.sh          │
│              │         │                   │         │  apply/02-traefik.sh      │
│              │         │                   │         │  revoke/01-ufw.sh         │
└──────────────┘         └──────────────────┘         └───────────────────────────┘
  1. A user starts a session in EntryGuard (web or CLI)
  2. EntryGuard creates a command: "apply 203.0.113.50/32" with the resource's script directory
  3. The agent polls for commands every few seconds
  4. The agent discovers scripts in the apply/ subdirectory, sorted by prefix, and executes them in order
  5. When the session expires, the agent runs the scripts in the revoke/ subdirectory
You control the scripts

The agent never generates or runs arbitrary commands. It only calls the scripts you've written and placed in the script directory. EntryGuard passes the CIDR — your scripts decide what to do with it: add an iptables rule, update UFW, modify an nginx allowlist, add a Windows Firewall rule, call a Traefik API, or anything else.

Why Use the Agent?​

  • No inbound access needed — The agent polls outbound. No firewall holes, no public endpoints, no port forwarding.
  • Any service — iptables, ufw, nginx, Windows Firewall, Traefik, HAProxy, WireGuard, custom applications — anything you can script.
  • You own the logic — Scripts are plain shell or PowerShell scripts on your machine. You write them, you control them, you audit them.
  • Multiple scripts per resource — One resource can run several scripts in sequence (e.g., UFW + Traefik + audit log). All run regardless of individual failures.
  • Automatic cleanup — When sessions expire, revoke scripts run automatically.
  • FIFO execution — When multiple users start sessions, commands are queued and executed in order. No race conditions.
  • Lightweight — Single static binary, ~12MB, no runtime dependencies.

Security Model​

The agent follows a strict contract:

What the agent doesWhat the agent does NOT do
Polls EntryGuard for pending commandsGenerate or interpret firewall rules
Passes CIDR and description to your scriptsExecute anything not in your script directories
Reports per-script exit codes and output backModify system configuration directly
Sends heartbeats to report its statusAccept inbound connections

Your scripts are the single source of truth for what happens on the machine. The agent is a delivery mechanism — it brings the CIDR to your scripts and reports the results.

Prerequisites​

  • A Linux or Windows machine (amd64 or arm64), or any container runtime (Docker, Kubernetes)
  • An EntryGuard account on any plan (Free or Paid)
  • An API key with the agent:connect scope
  • A script directory with apply/revoke scripts (see Script Directories and Example Scripts)

Next Steps​