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:
parent
60ecea5419
commit
bc02284e9d
4 changed files with 69 additions and 22 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue