mancube/eggrd repository overview

⁠EdgeGuard (mancube/eggrd)

A drop-in Rust edge proxy: authentication, rate limiting, hardened response headers, and TLS and mutual TLS on every hop — with zero code changes to your app.

EdgeGuard is the missing front door for any HTTP app (including the ones generated/vibe-coded without one). It owns the request path (auth, rate-limit, validation, WAF-lite) and the response path (CSP/HSTS/cookie hardening, leaky-header stripping) in a single static binary, and since 0.7 it can balance and fail over across a pool of upstreams and report API usage by route, consumer and upstream.

• Image: mancube/eggrd — static musl binary on distroless/static, runs as nonroot, no shell, CA roots included.
• Size: ~7.6 MB compressed (amd64), ~7.3 MB (arm64), measured on 0.7.0 · Arch: linux/amd64, linux/arm64 (both built natively)
• Binary inside: /usr/local/bin/edgeguard (entrypoint) · Exposes: 8080
• Default config (baked in): /etc/edgeguard/edgeguard.toml
• Source / full docs: github.com/lucheeseng827/eggrd⁠ · Apache-2.0

⁠Where it fits

EdgeGuard is the secure front door: one hop that sits between your clients and the app, so traffic reaches the app only after it clears auth, rate limiting, and validation. Your app stops listening on the public port — EdgeGuard does — and is forwarded to unchanged. One hop, to one upstream or a pool of them (balanced, health-checked, failing over), over plain HTTP, TLS or mutual TLS; it is not a CDN, an API gateway, or an identity provider.

   CLIENTS                 EDGEGUARD                UPSTREAMS
   (public internet)       (this image)             (what it fronts)

 ┌───────────────┐
 │ Browsers      │  ─┐
 │ API callers   │   │          ┌────────────┐ plain HTTP  ┌───────────────┐
 │ LLM / SSE apps│   ├ TLS·auth▶│  edgeguard │ ─────────▶  │ your app      │
 │ bots·scanners │   │ rate-lim │  req path  │ (localhost) │ (unchanged)   │
 └───────────────┘   │ WAF·DLP  │ ────────── │             ├───────────────┤
 ┌───────────────┐   │          │  resp path │ ─────────▶  │ LLM provider  │
 │ CDN / LB / DNS│  ─┘ :443/8080│ CSP · HSTS │  hardened   │ static site   │
 │ (optional)    │              │  cookies   │  response   └───────────────┘
 └───────────────┘              └─────┬──────┘
                                      │
            ┌─────────────────────────┘
            ├──▶ Redis — one global rate-limit shared across replicas
            ├──▶ control plane — policy pull · usage · quota (managed mode)
            └──▶ Prometheus — scrapes /__edgeguard/metrics

• Upstream — every client hits EdgeGuard, never the app directly: browsers, API callers, streaming LLM/SSE apps, bots and scanners. It may sit behind a CDN / platform LB that forwards to it (the client's address comes from a PROXY protocol header or the balancer's X-Forwarded-For entry); EdgeGuard terminates TLS, verifies client certificates if asked, authenticates, rate-limits, and screens (WAF / edge DLP) before anything is forwarded.
• EdgeGuard — the request path (auth, limit, validation) in, the response path (CSP/HSTS, cookie hardening, leaky-header stripping) out — one static binary, no required external services.
• Downstream — a wrapped child on APP_PORT, an external UPSTREAM URL, or a pool of targets per path: your own app, a streaming LLM backend, or a static frontend + /api backend split via [[upstreams]]. https:// upstreams are verified, with mutual TLS if needed. The app is forwarded to unchanged — zero code changes.
• Side channels (optional) — Redis for one global rate-limit across replicas, a control plane (managed mode) for policy pull + usage/quota, and Prometheus scraping /__edgeguard/metrics.

⁠Tags

There is no 0.6.0 image (its hardening shipped in 0.7.0) and no 0.7.0-rc.2 image.

Pin a version in production: mancube/eggrd:0.7.2.

⁠Quick start

Front-proxy mode — put EdgeGuard in front of an existing upstream (the natural mode for this image):

docker run -p 8080:8080 \
  -e UPSTREAM=http://app.internal:3000 \
  mancube/eggrd:0.7.2 --config /etc/edgeguard/edgeguard.toml

Bring your own config (overrides the baked-in default):

docker run -p 8080:8080 \
  -e UPSTREAM=http://app.internal:3000 \
  -v "$PWD/edgeguard.toml:/etc/edgeguard/edgeguard.toml:ro" \
  mancube/eggrd:0.7.2 --config /etc/edgeguard/edgeguard.toml

Co-process mode (EdgeGuard supervises your app as PID 1) needs your app in the same image. Copy the binary into your app's image instead of running this one directly:

COPY --from=mancube/eggrd:0.7.2 /usr/local/bin/edgeguard /usr/local/bin/edgeguard
ENTRYPOINT ["/usr/local/bin/edgeguard", "--config", "/etc/edgeguard/edgeguard.toml", "--wrap", "node server.js"]

EdgeGuard binds the platform's $PORT and runs your app on APP_PORT. (Full process-group signaling on Unix; Windows is best-effort — prefer front-proxy mode there.)

⁠Configuration (env)

All config is optional — secure defaults ship in the baked-in edgeguard.toml. Common env overrides:

Auth, rate limits, TLS/ACME, CSP, WAF-lite, and size/method limits are set in the TOML file. Editing it while running hot-reloads the policy in place (port/TLS changes still need a restart).

⁠What it does

• Reverse proxy to an upstream (wrapped child process or external URL), over plain HTTP, verified TLS, or mutual TLS ([upstream_tls]).
• Per-path upstreams and pools ([[upstreams]], single upstream by default): route /api to a backend and everything else to a static frontend (longest-prefix wins), and give a path a pool of targets — priority, weighted round robin, least connections, consistent hashing or sticky cookies, a backup tier, active HTTP/TCP health checks, and failover when a target cannot be reached.
• Client certificates (mTLS) ([tls.client_auth], auth.mode = "mtls"): verify clients against your CA with CRLs, or read the certificate a TLS-terminating load balancer forwards.
• Behind a load balancer: PROXY protocol v1/v2 from trusted addresses, or X-Forwarded-For with forwarded_hops; [outbound] sets one egress proxy and private CA for every call the edge makes (control plane, log/OTLP shipping, JWKS, ACME).
• Connection hardening: a header-read timeout against slowloris clients, a connection cap, and a graceful drain on SIGTERM.
• Streaming / passthrough: SSE (text/event-stream) forwarded unbuffered, frame-by-frame (fronts streaming LLM backends without collapsing time-to-first-byte); optional WebSocket / Upgrade tunneling.
• Request IDs (X-Request-Id): reuse a well-formed inbound id or mint a UUID v4, forward it upstream, echo it on every response, tag the access log — one id correlates client, proxy, and app.
• IP access control ([access], allow-all by default): coarse CIDR allow/deny lists evaluated by client IP before auth and rate limiting.
• Response compression (validation.compress_responses, off by default): gzip for clients that ask, skipping already-compressed types and SSE.
• Auth (auth.mode): HTTP Basic ($argon2 PHC hashes), static API key / bearer (constant-time), or JWT (HS/RS/ES/PS/EdDSA, static key or cached JWKS; configured alg pinned).
• Rate limiting (GCRA → 429): per-IP, optional per-route overrides, optional per-key; in-process governor or shared Redis store for multi-replica global limits.
• WAF-lite (off by default): SQLi / XSS / path-traversal heuristics + custom deny patterns, with a report-only rollout mode.
• Response hardening: CSP (+ report-only + report sink), HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy; adds Secure; HttpOnly; SameSite to cookies — with a per-cookie httponly_cookie_exempt opt-out so a JS-readable double-submit CSRF cookie stays readable; strips Server / X-Powered-By.
• TLS via rustls, optional ACME / Let's Encrypt (HTTP-01), with automatic certificate rotation: ACME and self-signed certificates renew at two-thirds of their lifetime, and a certificate replaced on disk is hot-swapped without a restart ([tls] watch).
• Limits: body-size (413), header-size (431), method allowlist (405).
• Config hot-reload, structured JSON access logs (who called, which route and upstream, how long, how many bytes), Prometheus metrics per route, consumer and upstream, with a Grafana dashboard and alert rules in the monitoring bundle.

⁠Ops endpoints

The reserved /__edgeguard/* namespace is never forwarded upstream:

Use ADMIN_PORT to move these onto a private listener and keep them off the public port.

⁠Auth / secrets

Hash a password with the built-in helper (distroless has no shell — pass --hash as an arg, feed the password on stdin):

echo -n 'your-password' | docker run -i --rm mancube/eggrd:0.7.2 --hash
# paste the $argon2id$... string as the user's value in edgeguard.toml

A plaintext users value is dev-only (compared in constant time, never stored hashed). Always use an $argon2 hash for anything reachable.

⁠License

Apache-2.0. Codename "EdgeGuard" is a working title.