docs: deployment recipe + verify checklist for ClientIPFromXFFTrustedProxies (#1111)

Replace the counting prose and ASCII diagram with a recipe table mapping
common deployments to numTrustedProxies values, plus a "verify with a
known IP" step. Steer users toward ClientIPFromXFF with explicit CIDRs
(added pointers to CDN-published IP lists from Cloudflare, AWS, Fastly,
GCP) since CIDR-based trust cannot off-by-one. Add one fail-closed test
case.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Vojtech Vitek (golang.cz) 2026-08-20 10:53:43 +02:00 committed by GitHub
parent 60ecea5419
commit bc02284e9d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 69 additions and 22 deletions

View file

@ -465,6 +465,11 @@ is folded to plain IPv4, and IPv6 zone identifiers carried in headers are
stripped, so one logical client maps to a single canonical key for logs,
rate limits, and ACLs.
For `ClientIPFromXFFTrustedProxies`, `numTrustedProxies` is the total proxy
hops between client and server. Prefer `ClientIPFromXFF` with explicit CIDRs
when you can — CIDR-based trust cannot off-by-one. See the godoc for a
deployment recipe and a verify checklist.
See the per-function godoc for the full semantics of each middleware, and
[adam-p's "The perils of the 'real' client IP"](https://adam-p.ca/blog/2022/03/x-forwarded-for/)
for the underlying threat model.

View file

@ -62,7 +62,14 @@ func ClientIPFromHeader(trustedHeader string) func(http.Handler) http.Handler {
// set (fail-closed) — we can't safely trust anything left of garbage.
//
// Use this when you sit behind one or more reverse proxies whose IP ranges
// you can enumerate as CIDRs:
// you can enumerate as CIDRs. Most CDNs publish their IPs:
//
// Cloudflare: https://www.cloudflare.com/ips/
// AWS: https://ip-ranges.amazonaws.com/ip-ranges.json
// Fastly: https://api.fastly.com/public-ip-list
// Google Cloud: https://www.gstatic.com/ipranges/cloud.json
//
// Example (CloudFront):
//
// r.Use(middleware.ClientIPFromXFF(
// "13.32.0.0/15", // CloudFront IPv4
@ -109,30 +116,34 @@ func ClientIPFromXFF(trustedIPPrefixes ...string) func(http.Handler) http.Handle
}
}
// ClientIPFromXFFTrustedProxies stores the client IP read from the
// X-Forwarded-For header, given the exact number of trusted reverse proxies
// between this server and the public internet. It returns the IP at position
// len(xff) - numTrustedProxies in the merged X-Forwarded-For list — the IP
// added by the outermost of your trusted proxies, the only IP in the chain
// that none of your proxies have allowed an attacker to forge. Read it with
// [GetClientIP].
// ClientIPFromXFFTrustedProxies stores the client IP read from
// X-Forwarded-For, given the exact number of trusted reverse proxies
// between this server and the public internet. Read it with [GetClientIP].
//
// Use this when:
// - You know exactly how many proxies you sit behind, AND
// - Their IP addresses are dynamic (autoscaling proxy pools, ephemeral
// containers, dynamic CDN edges) so listing CIDRs with [ClientIPFromXFF]
// is impractical.
// PREFER [ClientIPFromXFF] with explicit CIDRs whenever you can — it
// cannot off-by-one and is robust to architecture changes. Most CDNs
// publish their IP ranges (Cloudflare, AWS, Fastly, Google Cloud). Use
// this counting variant only when proxy IPs are dynamic and unpublishable.
//
// WARNING: This variant is brittle to network architecture changes. If you
// add or remove a proxy level, numTrustedProxies silently becomes wrong and
// you may start trusting an attacker-supplied IP. Prefer [ClientIPFromXFF]
// with explicit trusted CIDRs whenever you can.
// numTrustedProxies = total proxy hops between the client and this server.
// Count every hop in the request path:
//
// If the XFF chain has fewer than numTrustedProxies entries (header missing
// or architecture changed), no client IP is set and [GetClientIP] returns "".
// Single proxy (one LB / nginx / Heroku / Fly.io / Render) ....... 1
// Two proxies (Cloudflare → ALB, CloudFront → ALB) .............. 2
// Three proxies (CDN → API gateway → LB) ......................... 3
//
// Like [ClientIPFromXFF], v4-mapped IPv6 folds to plain v4 and IPv6 zones
// are stripped before storage.
// VERIFY BEFORE GOING LIVE: send a request from a known IP and confirm
// [GetClientIP] returns that IP. If it returns a proxy IP, your count is
// too LOW — a client can spoof their IP, fix immediately. If it returns
// "", your count is too HIGH — no leak, but no client IP either.
//
// This middleware reads ONLY X-Forwarded-For; it does not inspect
// r.RemoteAddr. Guarantee at the network layer (security group / firewall)
// that only your proxies can reach this server.
//
// If the XFF chain has fewer than numTrustedProxies entries, no client IP
// is set (fail-closed). Like [ClientIPFromXFF], v4-mapped IPv6 folds to v4
// and IPv6 zones are stripped before storage.
//
// Panics at startup if numTrustedProxies < 1.
func ClientIPFromXFFTrustedProxies(numTrustedProxies int) func(http.Handler) http.Handler {

View file

@ -77,3 +77,32 @@ func Example_clientIP() {
fmt.Print(w.Body.String())
// Output: 198.51.100.42
}
// Example_clientIPFromXFFTrustedProxies shows that with two proxies the
// client sits at XFF[len-2] and any client-prepended entries to the left of
// that position are ignored.
func Example_clientIPFromXFFTrustedProxies() {
r := chi.NewRouter()
r.Use(middleware.ClientIPFromXFFTrustedProxies(2)) // P1 (inner) + P2 (outer).
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, middleware.GetClientIP(r.Context()))
})
// Each chain ends in "<client>, <P1>"; P2's address is in RemoteAddr,
// not in X-Forwarded-For. Leading entries are client-controlled.
for _, xff := range []string{
"109.81.118.93, 3.172.119.73",
"8.8.8.8, 109.81.118.93, 3.172.119.73",
"8.8.8.8, 8.8.8.8, 8.8.8.8, 109.81.118.93, 3.172.119.73",
} {
req := httptest.NewRequest("GET", "/", nil)
req.Header.Set("X-Forwarded-For", xff)
w := httptest.NewRecorder()
r.ServeHTTP(w, req)
fmt.Print(w.Body.String())
}
// Output:
// 109.81.118.93
// 109.81.118.93
// 109.81.118.93
}

View file

@ -196,8 +196,10 @@ func TestClientIPFromXFFTrustedProxies(t *testing.T) {
// XFF shorter than N: no IP set. This is intentionally fail-closed so a
// proxy-count mismatch doesn't silently fall through to attacker-controlled
// values.
// values. The index len(xff)-N is negative/out-of-range here; the walk
// must never panic or wrap around to an entry the client controls.
{"shorter_than_n", 3, []string{"1.1.1.1, 2.2.2.2"}, ""},
{"single_entry_n_two", 2, []string{"2.2.2.2"}, ""},
{"missing_header", 1, nil, ""},
// Spoofing: prepended attacker values are to the LEFT of the chosen