40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
# Checkpoint 22 — IP-bypass / trusted-proxy hardening
|
|
|
|
Date: 2026-09-08
|
|
|
|
## Security issue addressed
|
|
|
|
Before checkpoint 22, `Authenticator.Authenticate` evaluated `auth.ip_bypass` against the fully resolved client IP. If the immediate peer was in `auth.trusted_proxies`, that address could originate from `X-Forwarded-For`. A deployment that trusted a broad reachable subnet could therefore allow a direct client in that subnet to present a bypass address such as `127.0.0.1`.
|
|
|
|
## New default
|
|
|
|
- `ClientIP()` still resolves trusted forwarding chains for observability.
|
|
- `auth.ip_bypass` is evaluated against the direct TCP peer by default.
|
|
- `Identity.ClientIP` remains the resolved client address for usage/logging.
|
|
- Legacy forwarded-IP bypass is available only with explicit `auth.ip_bypass_use_forwarded_ip=true`.
|
|
- Config preflight warns when forwarded bypass is enabled and when `auth.trusted_proxies` contains broad non-loopback CIDRs.
|
|
|
|
API-key and OIDC authentication semantics are unchanged. No persistent-state schema change is introduced.
|
|
|
|
## Regression coverage
|
|
|
|
Tests prove that:
|
|
|
|
1. a trusted peer with `X-Forwarded-For: 127.0.0.1` cannot satisfy loopback IP bypass by default,
|
|
2. forwarded client-IP resolution still reports `127.0.0.1` for observability in that test,
|
|
3. explicit compatibility mode restores forwarded-IP bypass,
|
|
4. a direct loopback peer still satisfies the normal loopback bypass,
|
|
5. preflight warns on compatibility mode and a broad `10.0.0.0/8` trusted-proxy range while not flagging loopback-only proxy ranges.
|
|
|
|
## Built-binary spoof E2E
|
|
|
|
A release Linux-amd64 gateway was started with a trusted loopback proxy peer and an IP-bypass rule for `192.0.2.123/32`.
|
|
|
|
With the new default (`ip_bypass_use_forwarded_ip=false`), a request from the trusted TCP peer carrying `X-Forwarded-For: 192.0.2.123` returned **401 Unauthorized**.
|
|
|
|
The same test with the explicit compatibility flag set to `true` returned **200 OK** with an `ip-bypass` admin identity and resolved `client_ip=192.0.2.123`. This proves both the secure default and the intentional compatibility escape hatch in the release binary.
|
|
|
|
## Production-config preflight
|
|
|
|
The user's two-worker configuration validates successfully with the checkpoint-22 candidate. Preflight reports broad trusted-proxy warnings for `10.0.0.0/8`, `172.16.0.0/12` and `192.168.0.0/16`; these no longer permit forwarded headers to satisfy IP bypass under the default, but should still be narrowed to improve client-IP attribution integrity.
|