Skip to content

Threat model

This page is honest about what The Gateway can do for you, and where it can’t help. Read it before depending on the daemon for anything serious.

A failing VPN tunnel leaking traffic to the ISP

Section titled “A failing VPN tunnel leaking traffic to the ISP”

The kill-switch is reference-counted, lives at prerouting priority -1, and is re-applied by the reconciler on every tick. A stale handshake doesn’t produce a single packet to the default route. This is the strongest guarantee in the system.

Hard-coded DNS resolvers on client devices

Section titled “Hard-coded DNS resolvers on client devices”

force_dns DNATs every UDP/53 to the gateway resolver, so a phone that ignores DHCP and hits 8.8.8.8 directly still gets answered by the integrated resolver — with filtering, ECS stripping and per-device policy applied.

System-wide DoH-block matches by SNI on TCP/443 against a curated list of known providers. Firefox’s “Trusted Recursive Resolver” and similar mechanisms stop working when it’s on. DoT (TCP/853) is dropped when DNS mode is set to paranoid (see Privacy & kill-switch).

Cross-tunnel linkability of simultaneous flows

Section titled “Cross-tunnel linkability of simultaneous flows”

The splitting engine round-robins per connection across a tunnel pool. Two simultaneous TLS sessions to two different SaaS providers exit through two different tunnels — an observer at any one exit sees only half of your activity.

Packet-length and timing fingerprinting (at higher levels)

Section titled “Packet-length and timing fingerprinting (at higher levels)”

Level 3 adds 512-byte packet padding; levels 4 and 5 raise it to 1400 bytes (near the MSS-clamped frame size). A 40-byte heartbeat and a 1300-byte HTTP request look the same to a passive observer. Levels 3+ also add Poisson-distributed cover traffic so the visible packet rate doesn’t track real activity.

The bridge subsystem terminates TLS on a real, innocuous decoy hostname (your decoy site) and tunnels HTTP CONNECT inside. A censor inspecting SNI sees ordinary traffic to a static website.

The reconciler scans nftables, ip rule and ip route once a minute (configurable). A docker daemon or stray ufw enable that drops a chain wins for at most that interval, then loses.

Each tunnel runs in its own network namespace with a dedicated veth pair into the root namespace. A misbehaving OpenVPN client or redsocks process can’t accidentally add a route or ip rule that affects another tunnel — the namespaces are kernel-isolated.

Cohort-level fingerprinting via periodic-task timing

Section titled “Cohort-level fingerprinting via periodic-task timing”

Every periodic task in the daemon (DNS cache refresh, OCSP refresh, mesh heartbeat, webhook dispatch, reconciler) picks a random phase offset at startup. Two installations configured with the same intervals don’t fire their first tick at the same wall-clock moment, so an upstream observer (DoH provider, CA OCSP responder, mesh control plane) can’t de-anonymise an appliance by its aligned task spikes alone. Phase stays stable across restarts on a single install; it varies across installs.

Harvest-now-decrypt-later TLS interception

Section titled “Harvest-now-decrypt-later TLS interception”

The daemon’s outbound TLS (to upstream DoH resolvers, OCSP, webhook receivers, mesh control plane) uses X25519MLKEM768 as the preferred hybrid key-exchange group in Go 1.24+ defaults. Recorded handshakes can’t be decrypted later by a Shor-capable attacker. Operators with peers that have shipped PQ support can switch pq_crypto_mode to required for MLKEM-only strict mode (see Settings).

Every config-changing API call is logged with operator, source IP, before/after, and timestamp. Audit retention defaults to 90 days; raise it for compliance.

Physical seizure of an unattended box (dead-man’s switch)

Section titled “Physical seizure of an unattended box (dead-man’s switch)”

For deployments where the daemon’s host might be physically lost (travel router stolen, on-prem box seized), the dead-man’s switch auto-wipes sensitive tables if no admin has logged in for a configured window:

Terminal window
curl -X PUT https://gateway.lan:8080/api/v1/system/deadman \
-H "Authorization: Bearer $API_KEY" \
-d '{"enabled":true,"hours":72}'

A background goroutine polls every 5 minutes. If time.Since(last_admin_login) > hours, the daemon executes a soft wipe automatically:

  • Clears audit_log, the DNS query trail, gateway log files and the in-memory log ring.
  • Clears anomalies and resolved alerts, plus finished server-job logs and completed-update leftovers.
  • Keeps configuration, including the manual DNS blocklist. Since v2.18.0 it fires once per absence, rather than repeating every five minutes; a new admin login re-arms it.

The last_admin_login timestamp is updated by a successful admin login, not by a viewer login or an ordinary request using an existing bearer token. Do not rely on a scheduled status request to postpone the timer. Check the reported last login and choose a window appropriate for an unattended deployment.

Fail-safe direction. A corrupted last_admin_login kv row does not trigger a wipe — that would be the wrong direction for a single bad write. Instead the deadman-broken alert fires so the operator can repair the row before the window matters.

The manual POST /api/v1/system/wipe accepts three levels:

Level Effect
soft Clears the logs and activity history listed above; keeps configuration and the encrypted vault.
medium Soft plus vault key-slot erasure and stored-file removal. Preserves the live database and kill-switch state.
hard Also removes the live database, brings down tunnels, reaps managed OpenVPN processes and restarts the daemon.

The dead-man auto-trigger only does soft — the manual wipe is the escalation path for an operator who knows they need it. Failed steps are reported as a partial failure, not a successful wipe. File overwrites are not a guarantee of forensic erasure on flash storage or copy-on-write filesystems; journal and off-box copies are outside this operation.

Forensic recovery from a powered-off seized box

Section titled “Forensic recovery from a powered-off seized box”

From v2.18.0, Settings → Encrypted Storage manages an optional LUKS2 vault at /var/lib/gateway/vault. It holds scheduled and crash backups, the key that seals Secrets values, the federation signing key, the internal CA key and, when configured, the server-management SSH key. It does not encrypt the whole settings database or all of /var/lib/gateway. Tunnel keys and the server certificate stay outside so the VPN and web UI can start after a power cut.

Terminal window
# Read-only status; configure and unlock in Settings → Encrypted Storage.
curl https://gateway.lan:8080/api/v1/storage/encrypted \
-H "Authorization: Bearer $API_KEY"
# State is off, locked, unlocked, open (mapped but not mounted), or missing.
# Additional fields include holds, backups_paused, size_mb and cryptsetup.

The container file is /opt/gateway/vault.img, opened through the gateway-vault mapper. Setup defaults to 512 MB, accepts 128–16,384 MB and requires cryptsetup plus a passphrase of at least ten characters. Setup mounts it and moves existing backups and eligible keys immediately; inspect any migration warning rather than assuming everything moved. An open server-key rotation must be finished first.

The passphrase is not stored. A daemon restart leaves the vault open; a host reboot locks it until an administrator unlocks it. While locked:

  • Scheduled and crash backups are skipped, not written beside the vault in plaintext.
  • Sealed Secrets values cannot be read or saved; certificate issuance waits.
  • Federation manifests go out unsigned and cannot authenticate a certificate change to peers.
  • Server jobs that need the stored SSH key wait for unlocking. Routing and the web UI remain available.

This protects the vault’s contents on a powered-off device, not plaintext files outside it or a live compromised process. Keep an independent backup and passphrase recovery plan.

Removal is state-dependent. Removing an unlocked vault moves backups and readable keys back outside before erasing its LUKS key slots. Removing a locked vault requires explicit discard and loses its backups and keys; a lost passphrase cannot be recovered. Discard can clear sealed Secrets values, replace federation/server-management keys and require CA rotation and renewed peer/server trust. Use the UI’s current-state confirmation. The API exposes setup, unlock, lock and teardown; see System & lifecycle.


Compromise of the device behind The Gateway

Section titled “Compromise of the device behind The Gateway”

If a laptop on your LAN is owned, the attacker has the user’s authenticated sessions, browser state, and any application secrets stored on disk. The Gateway only protects what crosses its boundary. Endpoint security is a separate problem.

If the daemon binary or /etc/gateway/ are compromised, every guarantee here is void. Protect the daemon with the same care you’d give a CA: read-only root filesystem, sealed boot, separate audit aggregator, restricted SSH.

A malicious VPN provider at the tunnel exit

Section titled “A malicious VPN provider at the tunnel exit”

VPN providers see your unencrypted egress (post-tunnel). The Gateway encrypts to them; it doesn’t audit them. Pick exits you trust. Splitting across multiple providers reduces single-provider correlation but doesn’t eliminate it.

Global passive adversaries with traffic-correlation capability

Section titled “Global passive adversaries with traffic-correlation capability”

If an adversary can observe both your tunnel ingress AND every exit of the providers you use, they can correlate flow timing and volume. Privacy levels 4–5 raise the cost but don’t make it impossible. This is the same threat model Tor users live with.

A browser’s TLS handshake, supported ciphers, JA3/JA4 fingerprints, and HTTP/2 settings are visible to the exit. They’re outside the daemon’s reach. Use Tor / Tor Browser when this matters.

A determined active adversary with kernel-level access

Section titled “A determined active adversary with kernel-level access”

If someone roots the daemon’s host, they can edit nftables and the reconciler will fight them — but they win every tick until they’re evicted. The kill-switch is not magical; it’s a regular kernel-mode rule.

Real-time identity correlation by your VPN provider

Section titled “Real-time identity correlation by your VPN provider”

If your VPN provider logs source IP + destination per connection, no amount of splitting or cover traffic helps. Choose providers with a verified no-logs policy and / or pay anonymously.

A shared-tenancy VPS, a misconfigured cloud-init script that exposes the daemon to the internet, an unrelated service on the same box that allows arbitrary code execution — these are all outside the daemon’s scope.

Federation syncs config between peers (operator-triggered or via the per-peer prober). If your primary is malicious, your secondaries will obediently apply a hostile policy on the next sync. Treat the primary as a privileged role: separate ops accounts, separate audit, restricted access.

Backups are encrypted with AES-256-GCM, key derived from a passphrase via PBKDF2-HMAC-SHA256 (100 000 iterations, per-export salt). If you lose the passphrase, the backup is unrecoverable. The daemon never logs and never escrows it — that’s deliberate.


The Gateway makes these specific promises:

  1. Outbound IP never leaks to the default route for traffic matched by a fail_policy: fail-closed policy whose tunnel is down.
  2. Outbound DNS for any device with force_dns: true and / or system-wide force_dns is answered by the integrated resolver, with filtering applied, even if the device hard-codes a public resolver.
  3. DoH bypass by browsers is blocked when block_doh: true is on system-wide, for every known DoH provider in the bundled list.
  4. WebRTC IP exposure via STUN is blocked for devices in privacy classes with block_webrtc: true.
  5. IPv6 leakage is blocked for devices in privacy classes with ipv6_policy: block.
  6. Per-policy state isolation: traffic for policy A cannot bleed into policy B’s routing table or kill-switch state. Even if one policy’s reconciliation fails, others continue to be enforced.
  7. Crash safety: a daemon crash mid-write does not leak — SQLite is WAL-mode, and the daemon does not SIGKILL on shutdown.
  8. Per-tunnel namespace isolation: each tunnel runs in its own netns connected by a veth pair. A per-tunnel sidecar (redsocks, openvpn client) can’t touch another tunnel’s interface, routes, or rules — the kernel boundary is hard.

Outside of these, you are operating without a guarantee.


  • Run the daemon on a dedicated box. Don’t multi-tenant with Docker, ufw, firewalld, or anything else that mutates nftables — the reconciler will fight whatever else touches the kernel.
  • Restrict the API to auth.local_net (loopback / management VLAN) or put a reverse proxy in front that requires mutual TLS. Never expose the API directly to the public internet.
  • Pick at least two unrelated VPN providers for your pool. Provider diversity is part of the threat model.
  • Bind sensitive policies (work email, banking, source-of-truth federation primary) to fail_policy: fail-closed. Accept the brief outage trade-off.
  • Keep the daemon updated. The reconciler protects against drift, not against bugs in the daemon’s own logic.
  • Take regular encrypted backups. Verify the restore once a quarter on a spare box.