Security model
ngstone is built for a single operator, and its threat model is scoped accordingly — it takes tunneling's inherent exposure seriously without pretending to be a general-purpose ingress platform with tenant isolation.
Assets#
What's actually at stake if something goes wrong:
- The laptop's local app, and by extension its LAN foothold
- The auth token
- The wildcard domain's reputation
- Tunneled request and response data in transit
Anonymous attacker#
An anonymous attacker who has the public URL is exactly an anonymous HTTP client of the exposed local app — nothing more. They cannot reach the inspector (it's a terminal UI attached to your own process, not a network service — there's no port to reach), any other localhost port (only the configured target is ever dialed), or the control plane (token-gated). Whatever residual risk remains here is inherent to tunneling itself: if the local app is a debug server with a remote code execution bug, the tunnel exposes exactly that. Mitigations are a fast, byte-identical 404 for unknown or offline hosts (no enumeration oracle), per-IP rate limiting, and making this risk explicit in the docs rather than implying a false sense of isolation.
Leaked token#
What a leaked token grants — and doesn't
A scoped credential is intentionally presented as a bearer token to the control plane, so protect it like a password. The edge never stores the plaintext token. Revocation is fail-closed if the credential store cannot be read, and active sessions are disconnected on the next heartbeat after revocation or expiry. Durable storage also expires connector leases so another edge can safely reclaim an offline tunnel.
Per-tunnel access control#
--basic-auth and --allow-cidr (see Access control) narrow the public surface of one tunnel — they are not a second layer of defense against someone who already holds the edge token. A holder of the token can bind a fresh, unprotected subdomain, or take over your binding outright, so access control only matters against the anonymous internet, not against a compromised token.
Basic auth credentials are stored on the edge as an unsalted SHA-256 digest of user:pass — the agent hashes locally and the plaintext never crosses the wire. Unsalted means identical credentials always produce the same digest, so treat a leaked digest as equivalent to a leaked password subject to offline dictionary attack, not as a safe-to-expose value.
--allow-cidrtrusts the edge's view of the connection's source IP. That view is only trustworthy behind a front proxy if the edge is also configured with -proxy-protocol-trusted restricting which peers may send a PROXY header — otherwise a direct client can forge one and spoof its way past the allowlist.
Header spoofing#
Inbound Forwarded/X-Forwarded-* headers are stripped and re-stamped at the edge, and X-Real-IPis stripped explicitly since it isn't covered by the standard library's automatic delete. The local app can trust these headers only because the agent-side proxy is written to preserve them on the way through — the same stdlib behavior that strips spoofed headers on the edge would silently delete the legitimate ones on the agent if it used the same code path unmodified.
The inspector's attack surface#
There's no CSRF or DNS-rebinding story to tell here, because there's no HTTP endpoint to attack: the request inspector is a terminal UI (see Using the request inspector) that renders directly to your own process's stdout. It doesn't bind a port, doesn't serve an API, and isn't reachable from a browser tab — a malicious web page has nothing to drive.
Resource exhaustion#
Every buffer in the system has a stated cap, including the yamux receive windows — easy to omit, since concurrency × window is the real ceiling and neither number alone tells the whole story. No code path buffers an entire request or response body in memory. The unauthenticated surface on :4443is separately capped (concurrent handshakes, unauthenticated sessions, and unauthenticated sessions per client address) so a stranger can't hoard control-plane resources for the price of a bare TCP connect. The per-address cap is a quarter of the handshake cap, so four addresses (or /48s) can still fill the handshake cap.
Out of scope#
OIDC team authentication now protects the management dashboard and API. It does not authenticate anonymous visitors to a public tunnel; use tunnel access controls for that surface. Remaining gaps include:
- WebSocket over h2 extended CONNECT — native gRPC and h2c backends use the explicit HTTP/2 bind mode; WebSocket clients should use the existing HTTP/1.1 upgrade path
- Volumetric DDoS beyond the VPS's own capacity
- Compromise of the VPS itself — it terminates TLS and sees plaintext, so it's treated as trusted infrastructure