Skip to content

Commit 3b17157

Browse files
VojtechVitekcursoragentclaude
authored
feat: middleware.ClientIP, a replacement for middleware.RealIP (#967)
* ClientIP middleware proposal, intended to replace RealIP * ClientIP middleware: address PR feedback and security advisories Rework the new ClientIP* middlewares per reviewer feedback (c2h5oh, adam-p, rezmoss, Saku0512) and align with the documented attack patterns in GHSA-3fxj-6jh8-hvhx, GHSA-rjr7-jggh-pgcp, GHSA-9g5q-2w5x-hmxf. API: - Rename ClientIPFromXFFHeader -> ClientIPFromXFF. - Add ClientIPFromXFFTrustedProxies(n) for dynamic proxy pools where enumerating CIDRs isn't practical (autoscaling, ephemeral containers). - Add GetClientIPAddr alongside GetClientIP; both back to a single netip.Addr stored in context. r.RemoteAddr is never mutated. - Drop IsLoopback/IsPrivate filtering: the user's explicit trust configuration is authoritative (k8s nginx-ingress and similar legitimately surface those values). - Merge multiple X-Forwarded-For header instances before walking (RFC 2616), defeating duplicate-header attacks. - Deprecate middleware.RealIP with citations to all three advisories and guidance pointing at the new API. Docs: - Per-function godoc explains exactly when each variant applies. - Example_clientIP is a single, consolidated decision guide rendered on pkg.go.dev. Tests: 56 subtests including explicit PoC reproductions of each advisory, /24 boundary cases (Saku0512), IPv6, multi-header merging, spoofing prevention, and middleware chaining (rezmoss). Co-authored-by: Cursor <[email protected]> Co-Authored-By: Claude Sonnet 4.7 <[email protected]> * Drop first-write-wins semantics, we want users to use exactly one middleware * ClientIPFromXFFTrustedProxies: drop fallback-chaining hint from godoc Saku0512 correctly flagged in #967 that the godoc told users to register ClientIPFromRemoteAddr *after* ClientIPFromXFFTrustedProxies for fallback behavior. With last-write-wins semantics (482e855) that recipe is actively wrong: on the happy path RemoteAddr would silently overwrite the legitimate XFF-derived client IP with the immediate proxy's address — reintroducing the spoofing-prone behavior this API was written to prevent. Rather than just reverse the order in the example, drop the chaining hint entirely. The whole point of 482e855 was to push users toward picking exactly one ClientIPFrom* middleware; documenting a chaining recipe in one specific function works against that. The honest statement is "no client IP is set and GetClientIP returns \"\"" — what the caller does about it is on them. Also rename TestClientIPChaining -> TestClientIPLastWriteWins and reword its subtests to describe the property being locked down rather than endorsing a fallback recipe. Same coverage, no implicit recommendation. * ClientIP: add failing regression tests for v4-mapped / zoned IP bypasses Per PR #967 review, demonstrate three concrete gaps that the rightmost-untrusted XFF algorithm and ClientIPFromRemoteAddr don't catch: 1. v4-mapped IPv6 in XFF escapes a v4 trusted prefix (netip.Prefix.Contains is false for ::ffff:a.b.c.d vs a.b.c.0/N). Internal-address spoof and loopback spoof variants. 2. Zoned IPv6 in XFF escapes a v6 trusted prefix (netip.Prefix.Contains is false for any zoned address). 3. v4-mapped IPv6 RemoteAddr is returned in its v6 form, splitting one logical client across two rate-limit buckets / log keys / prefix checks depending on dual-stack listener configuration. These tests are EXPECTED TO FAIL on this commit; the follow-up commit will land the fixes (Unmap() + zone-strip at parse time). The previously discussed "empties don't shift TrustedProxies slot" property is not a bypass — current behavior is already correct — so it will be added as a regression-pin test alongside the fixes rather than committed here as failing. Co-authored-by: Cursor <[email protected]> * ClientIP: normalize v4-mapped IPv6 and strip header zones; README migration Fixes three gaps surfaced by the PR #967 review (failing tests added in the previous commit now pass): 1. v4-mapped IPv6 in XFF escaping a v4 trusted prefix. netip.Prefix.Contains returns false for ::ffff:a.b.c.d checked against a.b.c.0/N, so an attacker able to inject the v4-mapped form of an internal address could escape the trust list. Fix: a single parseHeaderAddr helper Unmap()s before the prefix check and before storage. Applied uniformly in ClientIPFromHeader, the rightmost-untrusted XFF walk, and the ClientIPFromXFFTrustedProxies slot lookup. 2. Zoned IPv6 in XFF escaping a v6 trusted prefix. netip.Prefix.Contains returns false for any zoned IP, and zone identifiers carry no meaning across the network, so an attacker-injected zone suffix bypassed the trust check. Fix: parseHeaderAddr strips zones via WithZone("") at parse time; zones are by definition not valid in header-sourced IPs. 3. ClientIPFromRemoteAddr returning ::ffff:a.b.c.d for v4 clients on dual-stack listeners, splitting one logical client into two rate-limit / log / ACL keys. Fix: Unmap() before storing. Zone is preserved here because RemoteAddr can legitimately be link-local. Also: - Pre-canonicalize the user-supplied header name in ClientIPFromHeader at construction time, matching the realip.go pattern and saving a per-request canonicalization on the hot path. A package-level xForwardedForHeader constant documents the canonical XFF spelling. - Per-function godoc explicitly notes the v4-mapped folding and zone stripping so downstream callers understand the normalization contract. - New regression-pin tests: empties don't shift the ClientIPFromXFFTrustedProxies slot index; positive normalization tests for v4-mapped and zoned inputs in each entry point. - README: deprecate the RealIP row, add ClientIPFrom* entries, and introduce a "Choosing a ClientIP middleware" section with copy-paste recipes for the common deployments (direct internet, Cloudflare, CloudFront, dynamic-IP proxy pools). Co-authored-by: Cursor <[email protected]> * Improve comments and README * Update middleware.Logger to work with ClientIP * ClientIPFromXFF: zero-allocation lazy right-to-left walk middleware.ClientIPFromXFF sits in the request hot path of any chi server running behind a proxy fleet. Per the #967 review, "each allocation counts" — at high RPS the per-request mergeXFF allocations are small individually but show up in GC pressure across many handlers. The previous implementation built a fully materialized merged XFF slice via mergeXFF, then walked it right-to-left and returned at the first non-trusted entry. In the common case — one trusted hop, the rightmost XFF entry IS the client — we paid to allocate and populate the whole chain only to inspect the last cell. Replace it with a lazy walker that iterates headers right-to-left and, within each header, iterates comma-separated entries right-to-left via strings.LastIndexByte. Substrings alias the original header storage, no copies. The walker returns at the first parseable non-trusted entry without ever materializing a slice. Per-request allocation impact (XFF present, typical "1 header, 3 IPs, 1 trusted hop"): Before: ~4 small allocations - initial mergeXFF backing array - strings.Split's []string per header value - 2 regrowths of the result slice as it fills After: 0 allocations - returns on the first iteration; nothing materialized Worst case (entire chain inside trusted prefixes, walker scans all entries): still 0 allocations. Correctness validated three independent ways: - Algorithm conformance: every requirement of the PR's rightmost- untrusted spec maps line-by-line to the new walker — multi-header merge, empty/whitespace drop, parse-failure skip, trust-prefix skip, normalization via parseHeaderAddr (Unmap + zone strip). - Iteration-order equivalence: walking headers in reverse and each header's entries in reverse via LastIndexByte yields exactly the same sequence as mergeXFF's flat list walked right-to-left. - All existing ClientIPFromXFF tests pass: multi-header merge, rightmost-untrusted spoofing scenarios, CIDR boundary membership, v4-mapped folding, IPv6 zone stripping, security regression pins. - Brute-force equivalence fuzz against the original mergeXFF-based walker over 200k random inputs (valid IPs, garbage, v4-mapped, zoned, whitespace, leading/trailing/double commas, empty headers): zero divergences. mergeXFF is unchanged and still used by ClientIPFromXFFTrustedProxies, which genuinely needs the total count for slot indexing. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFF: add failing tests for fail-closed on unparseable XFF PR #967 review issue #6 (adam-p): a netip.ParseAddr failure mid-chain in the rightmost-untrusted walk currently triggers a silent continue. With that behaviour, a hostile or buggy hop emitting garbage between the client and a trusted proxy is indistinguishable from no entry at all, and the walker happily skips past it to return a more-leftward IP — a spoofable result. Pin the desired fail-closed contract with TestXFF_FailClosedOnUnparseable covering three failing cases: 1. garbage_rightmost_no_prefixes XFF "1.1.1.1, garbage" with no trusted prefixes. Today returns 1.1.1.1 (skip-and-continue); must return "" (fail-closed). 2. garbage_between_client_and_trusted_proxy XFF "203.0.113.7, garbage, 10.0.0.1", trusted 10.0.0.0/8. Today skips the trusted hop and the garbage, returns 203.0.113.7. Must return "" — we cannot tell whether the entry to the left of garbage is the client or another forged hop. 3. garbage_past_trusted_chain Same shape with multiple trusted hops. Identical contract. Plus one negative case that MUST keep passing (proves fail-closed does not over-trigger when the walker returns before reaching garbage): 4. garbage_in_unreachable_left_header Headers ["garbage", "203.0.113.7, 10.0.0.1"], trusted 10.0.0.0/8. Walker returns 203.0.113.7 from the right header; garbage in the left header is never inspected. Already passes today, must still pass after the fix. Also remove the now-obsolete "unparseable_rightmost_skipped" case from TestClientIPFromXFF_NoTrustedPrefixes — it asserts the old skip-and- continue behaviour and no longer fits that table's "rightmost-first" theme. The "weird_with_empties_then_valid_rightmost" comment is updated to call out that empty/whitespace entries are trimmed before parsing and so do not trip fail-closed. Cases 1-3 are EXPECTED TO FAIL on this commit; the follow-up flips rightmostUntrustedXFF from silent-skip to fail-closed. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFF: fail closed on unparseable XFF entries PR #967 review issue #6 (adam-p): the rightmost-untrusted walk previously treated a netip.ParseAddr failure the same as a trusted-prefix match — silently skip and keep walking left. That is unsafe. Rightmost-untrusted only works because we trust ourselves to be able to read every hop to the right of the client. An unparseable hop is indistinguishable from a hostile or missing one. Walking past it can let us "find" a client IP that is actually any prepended value an attacker chose to put further left in the chain — exactly the spoofing shape this middleware was written to prevent. Flip the !ok branch in rightmostUntrustedXFF from continue to return (zero, false). Trusted-prefix still continues, empties/whitespace still skip via trim, fail-closed only fires on actual parse failures. ClientIPFromXFFTrustedProxies and ClientIPFromHeader are unaffected: they are single-value reads and already produce no IP on parse failure by construction. Godoc: - ClientIPFromXFF gets one concise line stating the fail-closed contract (visible to library users). - rightmostUntrustedXFF's internal comment is expanded to explain the security rationale (visible to chi maintainers). The four cases pinned in the previous commit's TestXFF_FailClosedOnUnparseable now pass; full middleware test suite stays green. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFFTrustedProxies: zero-allocation lazy nthFromRightXFF walk After 09ddca9 swapped rightmostUntrustedXFF to a lazy right-to-left walk, mergeXFF was kept only because ClientIPFromXFFTrustedProxies needs positional indexing — xff[len-N] — into the merged chain. The slice was allocated and populated every request, even though only one position in it was ever read. The same right-to-left iteration that powers rightmostUntrustedXFF serves this call site with a different stop condition: count down N non-empty entries from the right, return the Nth. nthFromRightXFF is that helper. ClientIPFromXFFTrustedProxies's handler becomes a single call against it; mergeXFF is deleted. Both XFF middlewares now share one iteration shape (right-to-left lazy walk over comma-separated entries across all header values, with substrings aliasing the original header storage) parameterised by stop condition: "first non-trusted" for rightmostUntrustedXFF, "Nth from right" for nthFromRightXFF. One less helper to reason about; both paths become zero-allocation. Allocation impact for ClientIPFromXFFTrustedProxies (per request with XFF present, typical "3 IPs, N=2"): Before: ~4 small allocations - initial mergeXFF backing array - strings.Split's []string per header value - 2 regrowths of the result slice After: 0 allocations - returns at the Nth non-empty entry from the right; nothing materialized Security properties preserved end-to-end — all 12 subtests of TestClientIPFromXFFTrustedProxies pass unchanged, including the trickiest pin (empties_dont_shift_slot) which is exactly the property "do not count empty entries toward N" that nthFromRightXFF's drop-then- decrement loop guarantees by construction. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFF: unify both XFF walkers behind a single walkXFF primitive After the prior two commits, both XFF middlewares had near-identical right-to-left scan loops differing only in stop condition (first non-trusted entry vs Nth non-empty entry from the right). nthFromRightXFF and rightmostUntrustedXFF together carried ~30 lines of duplicated loop boilerplate. Collapse to one primitive: walkXFF(headers []string, visit func(entry string) bool) iterates the merged X-Forwarded-For chain right-to-left and calls visit on each trimmed non-empty entry; visit returns true to stop the walk. Both middleware handlers now share this primitive and supply their own stop condition as a small inline visitor closure (~7 lines each). Net: -21 lines in middleware/client_ip.go, one fewer concept to reason about, single source of truth for the (security-critical) walk order and the empty-entry drop rule. Zero-allocation property is preserved -- benchmarked side-by-side against the previous two-helpers implementation: BenchmarkRightmost_TwoHelpers 36 ns/op 0 B/op 0 allocs/op BenchmarkRightmost_Callback 37 ns/op 0 B/op 0 allocs/op BenchmarkNth_TwoHelpers 11 ns/op 0 B/op 0 allocs/op BenchmarkNth_Callback 13 ns/op 0 B/op 0 allocs/op Go's escape analysis keeps the visitor closures (and their captured &found / &entry / &n locals) on the stack; only cost is one indirect call per visited entry (~1-2 ns). All tests still pass (advisory pins, fail-closed pins, multi-header merge, normalization, boundary CIDR, last-write-wins, panic conditions). Stale comments in client_ip_test.go that referenced the removed helpers by name are updated; test names/comments uniformly use "position" (matching the godoc) for the algorithmic concept and "entry" for an individual chain value. Co-authored-by: Cursor <[email protected]> * client_ip_test: scrub stale "EXPECTED TO FAIL" notes on regression pins Four test godocs still said "this test is EXPECTED TO FAIL until X lands" even though X landed in a follow-up commit on this branch. Misleading to future readers (Copilot PR review flagged 3 of 4). The tests themselves are unchanged and still pass; they are now regression pins for behavior the PR already enforces. Reword the relevant paragraphs from future-tense ("the expected post-fix behavior is...") to present-tense ("pinned post-fix behavior: parseHeaderAddr does X") so the doc matches what the test actually pins. Affected tests: - TestXFF_V4MappedIPv6BypassesTrustedV4Prefix - TestXFF_IPv6ZoneIDBypassesTrustedV6Prefix - TestClientIPFromRemoteAddr_V4MappedIsUnmapped - TestXFF_FailClosedOnUnparseable Co-authored-by: Cursor <[email protected]> * fix(review): minor README fix * ClientIPFromHeader: add failing tests for multi-value header attack PR #967 Copilot review: ClientIPFromHeader uses r.Header.Get(header) to read the trusted single-IP header. Get returns only the FIRST value Go saw on the wire. If the trusted header reaches us with two values (a client-supplied "spoofed" plus a proxy-added "real"), we surface the client's value -- exactly the bypass shape this middleware was written to prevent. The trusted hop is the one CLOSEST to us in the chain, which is the LAST value, not the first. Same rightmost-untrusted spirit as ClientIPFromXFF: values from hops further from us are by definition less trustworthy than what our nearest hop produced. So the post-fix contract is: - Read r.Header.Values(header) (all instances). - Take the last entry. - parseHeaderAddr it; if it doesn't parse (garbage, empty), no IP is set -- do NOT fall back to earlier values (those came from less-trusted hops). TestClientIPFromHeader_MultiValueLastWins pins five cases: 1. single_value_unchanged (regression pin) 2. attacker_then_proxy -- today returns attacker's value 3. three_values_last_wins -- today returns attacker's value 4. last_unparseable_no_fallback -- today falls back to earlier value 5. last_empty_no_fallback -- today falls back to earlier value Cases 2-5 are EXPECTED TO FAIL on this commit; the follow-up flips ClientIPFromHeader from Get to Values()[len-1]. Co-authored-by: Cursor <[email protected]> * ClientIPFromHeader: take last value, not first (defense-in-depth) PR #967 Copilot review: the previous implementation read the trusted single-IP header with r.Header.Get(header), which returns only the first value. If the trusted header reaches us with multiple values -- a client-supplied "spoofed" entry plus the proxy's real entry, or two proxy-set entries because of upstream chain quirks -- we surfaced the attacker-controlled first value. Switch to r.Header.Values(header) and take the LAST entry. The last value is the one added by the hop closest to us in the chain, which is by definition the most trusted (the rightmost-untrusted principle we already apply to X-Forwarded-For). Fail-closed on garbage at the last position: we do NOT fall back to earlier values, as those came from less-trusted hops further from us. Correctly configured proxies (single value, proxy overwrites instead of appends) are unaffected -- len(values)==1, so first == last == that value. The four cases pinned in the previous commit's TestClientIPFromHeader_MultiValueLastWins now pass: - attacker_then_proxy (last value wins) - three_values_last_wins (last value wins) - last_unparseable_no_fallback (fail-closed) - last_empty_no_fallback (fail-closed) Existing ClientIPFromHeader tests stay green. Godoc updated with one short paragraph naming the multi-value contract. Co-authored-by: Cursor <[email protected]> * client_ip: add walkXFF benchmark as O(M) regression pin PR #967 Copilot review claimed walkXFF is O(n^2) in the number of XFF entries because it calls strings.LastIndexByte on progressively shorter substrings, and suggested a DoS-prone CPU cost on attacker-supplied large XFF headers. Benchmark refutes the claim. walkXFF is strictly O(M) in total chain length M -- linear in the entry count n, near-constant for the single-trusted-hop case (visitor returns true on the first entry). BenchmarkWalkXFF (visitor walks every entry, worst case for ClientIPFromXFF when all entries are inside trusted prefixes): n=1 5.6 ns/op n=10 57.6 ns/op (5.8 ns/entry) n=100 541.1 ns/op (5.4 ns/entry) n=1000 5228 ns/op (5.2 ns/entry) n=10000 55148 ns/op (5.5 ns/entry) BenchmarkWalkXFF_RightmostStop (visitor stops at the first entry, the common case for ClientIPFromXFF with no trusted prefixes and ClientIPFromXFFTrustedProxies(1)): n=1 5.2 ns/op n=10 6.0 ns/op n=100 6.1 ns/op n=1000 6.1 ns/op n=10000 6.1 ns/op -- truly constant Why the analysis is O(M): strings.LastIndexByte scans BACKWARD from the end of its input and stops at the first match. After we slice off the rightmost entry, the next call only scans up to the next comma -- O(L) where L is that entry's length. Sum over n iterations is O(n*L) = O(M). On arm64/amd64 it's also SIMD-optimized in the Go runtime, so a hand-rolled byte loop would lose, not win. Benchmark stays in the codebase as a regression pin: any future refactor that accidentally drops back to O(n^2) gets caught here. Zero allocations preserved across both shapes. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFF: doc fix -- no-args case is fail-closed, not skip-and-continue PR #967 Copilot review: the godoc said "Calling with no arguments returns the rightmost parseable XFF IP", implying skip-and-continue past garbage. That phrasing predates the fail-closed change in 5dd2243; the actual behavior is now "try the rightmost; if it doesn't parse, no IP is set". Update the line to match. Co-authored-by: Cursor <[email protected]> * ClientIPFromXFF*: skip Header.Values canonicalization on the hot path PR #967 fresh review: r.Header.Values(key) re-canonicalizes the key through textproto.CanonicalMIMEHeaderKey on every call. xForwardedForHeader is already a const in canonical form, so the canonicalization is redundant work in the request hot path. Replace r.Header.Values(xForwardedForHeader) with the direct map read r.Header[xForwardedForHeader] in both XFF middleware handlers. Safe because: - Headers received by net/http are stored under canonical keys. - Headers set programmatically via r.Header.Set/Add are also stored under canonical keys. - r.Header[non-canonical-key] only misses if user code bypasses the canonicalization via direct map writes; that's a test-only foot-gun and not the regime this middleware runs in. Per-lookup cost measured side by side on an M4 Pro: Header.Values 16.0 ns/op 0 B/op 0 allocs/op DirectMap 4.3 ns/op 0 B/op 0 allocs/op ~12 ns saved per request per XFF middleware on the hot path. Test suite (~70 tests) stays green; walkXFF semantics unchanged. Co-authored-by: Cursor <[email protected]> * Example_clientIP: mention fail-closed in the XFF comment PR #967 fresh review: the inline comment summarizing the XFF middleware said it "walks right-to-left, skipping trusted entries" but stopped short of mentioning the fail-closed-on-garbage contract that landed in 5dd2243. Add three words to match the godoc. Co-authored-by: Cursor <[email protected]> * TestClientIPFromHeader_MultiValueLastWins: regression-pin wording PR #967 Copilot review: the godoc on this test still described the pre-fix behavior in present tense ("Today we surface values[0]"), even though a8e3dbf already switched the implementation to read r.Header.Values() and use the last entry. Reword the godoc to frame the test as a regression pin for the gap fixed in a8e3dbf -- past-tense bug description, present-tense post-fix contract. Same body, same test cases, same assertions. Co-authored-by: Cursor <[email protected]> * BenchmarkWalkXFF: rename stale rightmostUntrustedXFF reference PR #967 Copilot review: the BenchmarkWalkXFF godoc referenced rightmostUntrustedXFF, an internal helper that was consolidated into the single walkXFF primitive back in 1863339 and no longer exists in the package. Rename the reference to ClientIPFromXFF (the public caller whose worst case this benchmark actually exercises). No code change. Co-authored-by: Cursor <[email protected]> --------- Co-authored-by: Cursor <[email protected]> Co-authored-by: Claude Sonnet 4.7 <[email protected]>
1 parent 818fdcf commit 3b17157

7 files changed

Lines changed: 1218 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ func main() {
8787

8888
// A good base middleware stack
8989
r.Use(middleware.RequestID)
90-
r.Use(middleware.RealIP)
90+
r.Use(middleware.ClientIPFromRemoteAddr) // pick one ClientIPFrom* based on your infra, see below
9191
r.Use(middleware.Logger)
9292
r.Use(middleware.Recoverer)
9393

@@ -349,7 +349,11 @@ with `net/http` can be used with chi's mux.
349349
| [Logger] | Logs the start and end of each request with the elapsed processing time |
350350
| [NoCache] | Sets response headers to prevent clients from caching |
351351
| [Profiler] | Easily attach net/http/pprof to your routers |
352-
| [RealIP] | Sets a http.Request's RemoteAddr to either X-Real-IP or X-Forwarded-For |
352+
| [ClientIPFromHeader] | Capture client IP from a trusted single-IP header (X-Real-IP, CF-Connecting-IP, ...) |
353+
| [ClientIPFromXFF] | Capture client IP from X-Forwarded-For, skipping listed trusted CIDR prefixes |
354+
| [ClientIPFromXFFTrustedProxies] | Capture client IP from X-Forwarded-For given a fixed number of trusted proxies |
355+
| [ClientIPFromRemoteAddr] | Capture client IP from the TCP RemoteAddr (server directly on the public internet) |
356+
| [RealIP] | Deprecated — vulnerable to IP spoofing; use [ClientIPFromXFF] or another ClientIPFrom\* middleware |
353357
| [Recoverer] | Gracefully absorb panics and prints the stack trace |
354358
| [RequestID] | Injects a request ID into the context of each request |
355359
| [RedirectSlashes] | Redirect slashes on routing paths |
@@ -375,6 +379,12 @@ with `net/http` can be used with chi's mux.
375379
[Logger]: https://pkg.go.dev/github.com/go-chi/chi/middleware#Logger
376380
[NoCache]: https://pkg.go.dev/github.com/go-chi/chi/middleware#NoCache
377381
[Profiler]: https://pkg.go.dev/github.com/go-chi/chi/middleware#Profiler
382+
[ClientIPFromHeader]: https://pkg.go.dev/github.com/go-chi/chi/middleware#ClientIPFromHeader
383+
[ClientIPFromXFF]: https://pkg.go.dev/github.com/go-chi/chi/middleware#ClientIPFromXFF
384+
[ClientIPFromXFFTrustedProxies]: https://pkg.go.dev/github.com/go-chi/chi/middleware#ClientIPFromXFFTrustedProxies
385+
[ClientIPFromRemoteAddr]: https://pkg.go.dev/github.com/go-chi/chi/middleware#ClientIPFromRemoteAddr
386+
[GetClientIP]: https://pkg.go.dev/github.com/go-chi/chi/middleware#GetClientIP
387+
[GetClientIPAddr]: https://pkg.go.dev/github.com/go-chi/chi/middleware#GetClientIPAddr
378388
[RealIP]: https://pkg.go.dev/github.com/go-chi/chi/middleware#RealIP
379389
[Recoverer]: https://pkg.go.dev/github.com/go-chi/chi/middleware#Recoverer
380390
[RedirectSlashes]: https://pkg.go.dev/github.com/go-chi/chi/middleware#RedirectSlashes
@@ -402,6 +412,62 @@ with `net/http` can be used with chi's mux.
402412
[ThrottleOpts]: https://pkg.go.dev/github.com/go-chi/chi/middleware#ThrottleOpts
403413
[WrapResponseWriter]: https://pkg.go.dev/github.com/go-chi/chi/middleware#WrapResponseWriter
404414

415+
### Choosing a ClientIP middleware
416+
417+
The legacy [RealIP] middleware is deprecated — it is vulnerable to IP spoofing
418+
(GHSA-3fxj-6jh8-hvhx, GHSA-rjr7-jggh-pgcp, GHSA-9g5q-2w5x-hmxf) and mutates
419+
`r.RemoteAddr`. Use one of the four `ClientIPFrom*` middlewares instead — pick
420+
exactly one based on your network setup — and read the resulting IP with
421+
[GetClientIP] (string) or [GetClientIPAddr] (`netip.Addr`):
422+
423+
| Your setup | Use |
424+
|---|---|
425+
| Directly on the public internet, no proxy | `middleware.ClientIPFromRemoteAddr` |
426+
| Behind nginx (`X-Real-IP`), Cloudflare (`CF-Connecting-IP`), Apache (`X-Client-IP`) | `middleware.ClientIPFromHeader("<your-trusted-header>")` |
427+
| Behind one or more proxies whose IP ranges you can list | `middleware.ClientIPFromXFF("10.0.0.0/8", ...)` |
428+
| Behind a known, fixed number of proxies with dynamic IPs | `middleware.ClientIPFromXFFTrustedProxies(2)` |
429+
430+
```go
431+
r := chi.NewRouter()
432+
r.Use(middleware.RequestID)
433+
434+
// Pick exactly one. Examples for common deployments:
435+
436+
// Direct internet exposure (no proxy):
437+
// r.Use(middleware.ClientIPFromRemoteAddr)
438+
439+
// Behind Cloudflare:
440+
// r.Use(middleware.ClientIPFromHeader("CF-Connecting-IP"))
441+
442+
// Behind AWS CloudFront (or any proxy fleet with known CIDRs):
443+
r.Use(middleware.ClientIPFromXFF(
444+
"13.32.0.0/15", // CloudFront IPv4
445+
"52.46.0.0/18", // CloudFront IPv4
446+
"2600:9000::/28", // CloudFront IPv6
447+
))
448+
449+
// Behind a known number of proxies with dynamic IPs:
450+
// r.Use(middleware.ClientIPFromXFFTrustedProxies(2))
451+
452+
r.Use(middleware.Logger)
453+
r.Use(middleware.Recoverer)
454+
455+
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
456+
clientIP := middleware.GetClientIP(r.Context()) // for logs, rate-limit keys, etc.
457+
_ = clientIP
458+
})
459+
```
460+
461+
These middlewares never mutate `r.RemoteAddr`. They store a normalized
462+
`netip.Addr` in the request context — IPv4-mapped IPv6 (`::ffff:a.b.c.d`)
463+
is folded to plain IPv4, and IPv6 zone identifiers carried in headers are
464+
stripped, so one logical client maps to a single canonical key for logs,
465+
rate limits, and ACLs.
466+
467+
See the per-function godoc for the full semantics of each middleware, and
468+
[adam-p's "The perils of the 'real' client IP"](https://adam-p.ca/blog/2022/03/x-forwarded-for/)
469+
for the underlying threat model.
470+
405471
### Extra middlewares & packages
406472

407473
Please see https://github.com/go-chi for additional packages.

‎middleware/client_ip.go‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
package middleware
2+
3+
import (
4+
"context"
5+
"net"
6+
"net/http"
7+
"net/netip"
8+
"strings"
9+
)
10+
11+
// clientIPCtxKey stores the client IP set by any of the ClientIPFrom* middlewares.
12+
var clientIPCtxKey = &contextKey{"clientIP"}
13+
14+
// xForwardedForHeader is the canonical form of the X-Forwarded-For header
15+
// name, used by the XFF-based middlewares.
16+
const xForwardedForHeader = "X-Forwarded-For"
17+
18+
// ClientIPFromHeader stores the client IP from a single-IP header set by
19+
// your reverse proxy. Read it with [GetClientIP].
20+
//
21+
// Only safe with headers your proxy unconditionally OVERWRITES on every
22+
// request, e.g.:
23+
//
24+
// - X-Real-IP — Nginx with ngx_http_realip_module
25+
// - X-Client-IP — Apache with mod_remoteip
26+
// - CF-Connecting-IP — Cloudflare
27+
//
28+
// True-Client-IP, X-Azure-ClientIP, and Fastly-Client-IP look similar but
29+
// pass through from the client by default in those products; don't use them
30+
// unless your edge strips the inbound value.
31+
//
32+
// If the header reaches us with multiple values (misconfigured proxy that
33+
// appends, or a downstream proxy not stripping a client-supplied value),
34+
// the LAST value wins — that's the one set by the hop closest to us, and
35+
// therefore the most trusted. Fail-closed if the last value doesn't parse:
36+
// no client IP is set rather than falling back to earlier (less-trusted)
37+
// values.
38+
//
39+
// v4-mapped IPv6 (::ffff:a.b.c.d) folds to plain v4 and IPv6 zones are
40+
// stripped before storage.
41+
func ClientIPFromHeader(trustedHeader string) func(http.Handler) http.Handler {
42+
header := http.CanonicalHeaderKey(trustedHeader)
43+
return func(h http.Handler) http.Handler {
44+
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
45+
values := r.Header.Values(header)
46+
if len(values) > 0 {
47+
if ip, ok := parseHeaderAddr(values[len(values)-1]); ok {
48+
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, ip))
49+
}
50+
}
51+
h.ServeHTTP(w, r)
52+
})
53+
}
54+
}
55+
56+
// ClientIPFromXFF stores the client IP read from the X-Forwarded-For header,
57+
// walking the chain right-to-left and skipping any IP that falls within one
58+
// of the given trusted CIDR prefixes. The first IP that is not trusted is
59+
// the client. Read it with [GetClientIP].
60+
//
61+
// An unparseable entry mid-chain aborts the walk and leaves no client IP
62+
// set (fail-closed) — we can't safely trust anything left of garbage.
63+
//
64+
// Use this when you sit behind one or more reverse proxies whose IP ranges
65+
// you can enumerate as CIDRs:
66+
//
67+
// r.Use(middleware.ClientIPFromXFF(
68+
// "13.32.0.0/15", // CloudFront IPv4
69+
// "52.46.0.0/18", // CloudFront IPv4
70+
// "2600:9000::/28", // CloudFront IPv6
71+
// ))
72+
//
73+
// Calling with no arguments returns the rightmost XFF entry, or no IP if
74+
// that entry doesn't parse (fail-closed) — safe only if you have exactly
75+
// one trusted hop directly in front of this server (e.g., nginx on localhost).
76+
//
77+
// v4-mapped IPv6 (::ffff:a.b.c.d) folds to plain v4 and IPv6 zones are
78+
// stripped before the prefix check and storage; otherwise an attacker
79+
// could use either notation to alias a trusted IP past the check.
80+
//
81+
// If you know the number of trusted proxies but not their IPs, use
82+
// [ClientIPFromXFFTrustedProxies] instead.
83+
//
84+
// Panics at startup if any prefix is invalid.
85+
func ClientIPFromXFF(trustedIPPrefixes ...string) func(http.Handler) http.Handler {
86+
prefixes := make([]netip.Prefix, len(trustedIPPrefixes))
87+
for i, p := range trustedIPPrefixes {
88+
prefixes[i] = netip.MustParsePrefix(p)
89+
}
90+
return func(h http.Handler) http.Handler {
91+
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
92+
var found netip.Addr
93+
walkXFF(r.Header[xForwardedForHeader], func(v string) bool {
94+
ip, ok := parseHeaderAddr(v)
95+
if !ok {
96+
return true // fail-closed; leave found unset
97+
}
98+
if inAnyPrefix(ip, prefixes) {
99+
return false // trusted hop; keep walking left
100+
}
101+
found = ip
102+
return true
103+
})
104+
if found.IsValid() {
105+
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, found))
106+
}
107+
h.ServeHTTP(w, r)
108+
})
109+
}
110+
}
111+
112+
// ClientIPFromXFFTrustedProxies stores the client IP read from the
113+
// X-Forwarded-For header, given the exact number of trusted reverse proxies
114+
// between this server and the public internet. It returns the IP at position
115+
// len(xff) - numTrustedProxies in the merged X-Forwarded-For list — the IP
116+
// added by the outermost of your trusted proxies, the only IP in the chain
117+
// that none of your proxies have allowed an attacker to forge. Read it with
118+
// [GetClientIP].
119+
//
120+
// Use this when:
121+
// - You know exactly how many proxies you sit behind, AND
122+
// - Their IP addresses are dynamic (autoscaling proxy pools, ephemeral
123+
// containers, dynamic CDN edges) so listing CIDRs with [ClientIPFromXFF]
124+
// is impractical.
125+
//
126+
// WARNING: This variant is brittle to network architecture changes. If you
127+
// add or remove a proxy level, numTrustedProxies silently becomes wrong and
128+
// you may start trusting an attacker-supplied IP. Prefer [ClientIPFromXFF]
129+
// with explicit trusted CIDRs whenever you can.
130+
//
131+
// If the XFF chain has fewer than numTrustedProxies entries (header missing
132+
// or architecture changed), no client IP is set and [GetClientIP] returns "".
133+
//
134+
// Like [ClientIPFromXFF], v4-mapped IPv6 folds to plain v4 and IPv6 zones
135+
// are stripped before storage.
136+
//
137+
// Panics at startup if numTrustedProxies < 1.
138+
func ClientIPFromXFFTrustedProxies(numTrustedProxies int) func(http.Handler) http.Handler {
139+
if numTrustedProxies < 1 {
140+
panic("middleware.ClientIPFromXFFTrustedProxies: numTrustedProxies must be >= 1")
141+
}
142+
return func(h http.Handler) http.Handler {
143+
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
144+
n := numTrustedProxies
145+
var entry string
146+
walkXFF(r.Header[xForwardedForHeader], func(v string) bool {
147+
n--
148+
if n == 0 {
149+
entry = v
150+
return true
151+
}
152+
return false
153+
})
154+
if entry != "" {
155+
if ip, ok := parseHeaderAddr(entry); ok {
156+
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, ip))
157+
}
158+
}
159+
h.ServeHTTP(w, r)
160+
})
161+
}
162+
}
163+
164+
// ClientIPFromRemoteAddr stores the client IP read from the TCP RemoteAddr
165+
// of the incoming request — the IP address of whoever opened the connection
166+
// to this server. Read it with [GetClientIP].
167+
//
168+
// Use this when this server is directly connected to the public internet
169+
// with NO reverse proxy in front of it. Behind a reverse proxy, RemoteAddr
170+
// is the proxy's IP, not the client's — use [ClientIPFromHeader] or
171+
// [ClientIPFromXFF] instead.
172+
//
173+
// IPv4 clients on a dual-stack listener surface as ::ffff:a.b.c.d; they
174+
// fold to plain v4 before storage so one logical client maps to one key.
175+
// IPv6 zones are preserved (link-local connections may legitimately have one).
176+
func ClientIPFromRemoteAddr(h http.Handler) http.Handler {
177+
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
178+
host, _, err := net.SplitHostPort(r.RemoteAddr)
179+
if err != nil {
180+
host = r.RemoteAddr // RemoteAddr may already be a bare IP (e.g. in tests).
181+
}
182+
if ip, err := netip.ParseAddr(host); err == nil {
183+
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, ip.Unmap()))
184+
}
185+
h.ServeHTTP(w, r)
186+
})
187+
}
188+
189+
// GetClientIP returns the client IP as a string, as set by one of the
190+
// ClientIPFrom* middlewares. Returns "" if no valid IP was set.
191+
// Convenient for logging, rate-limit keys, etc.
192+
func GetClientIP(ctx context.Context) string {
193+
ip := GetClientIPAddr(ctx)
194+
if !ip.IsValid() {
195+
return ""
196+
}
197+
return ip.String()
198+
}
199+
200+
// GetClientIPAddr returns the client IP as a [netip.Addr], as set by one of
201+
// the ClientIPFrom* middlewares. The returned Addr is the zero value if not
202+
// set; use [netip.Addr.IsValid] to check. Useful when you need typed work —
203+
// prefix containment, Is4/Is6, etc. — without re-parsing the string.
204+
func GetClientIPAddr(ctx context.Context) netip.Addr {
205+
ip, _ := ctx.Value(clientIPCtxKey).(netip.Addr)
206+
return ip
207+
}
208+
209+
// walkXFF walks the entries of the merged X-Forwarded-For chain
210+
// RIGHT-TO-LEFT, invoking visit on each trimmed non-empty entry. visit
211+
// returns true to stop the walk. Lazy walk, zero allocations (entries
212+
// are substrings of the input headers).
213+
//
214+
// Multiple XFF headers are merged per RFC 2616 — each header's
215+
// comma-separated entries in order received — so an attacker cannot pick
216+
// which value security logic sees by sending a duplicate header.
217+
func walkXFF(headers []string, visit func(entry string) bool) {
218+
for hi := len(headers) - 1; hi >= 0; hi-- {
219+
h := headers[hi]
220+
for h != "" {
221+
var v string
222+
if i := strings.LastIndexByte(h, ','); i >= 0 {
223+
v, h = h[i+1:], h[:i]
224+
} else {
225+
v, h = h, ""
226+
}
227+
v = strings.TrimSpace(v)
228+
if v == "" {
229+
continue
230+
}
231+
if visit(v) {
232+
return
233+
}
234+
}
235+
}
236+
}
237+
238+
// inAnyPrefix reports whether ip falls within any of the given prefixes.
239+
func inAnyPrefix(ip netip.Addr, prefixes []netip.Prefix) bool {
240+
for _, p := range prefixes {
241+
if p.Contains(ip) {
242+
return true
243+
}
244+
}
245+
return false
246+
}
247+
248+
// parseHeaderAddr parses s and normalizes for storage: v4-mapped IPv6
249+
// (::ffff:a.b.c.d) folds to plain v4, IPv6 zone is stripped. Both defend the
250+
// trust-prefix check against attacker-injected aliases — [netip.Prefix.Contains]
251+
// returns false for v4-mapped addresses vs v4 prefixes and for any zoned
252+
// address, so without folding/stripping an attacker could escape an
253+
// otherwise valid trust list.
254+
//
255+
// Header-sourced IPs only. [ClientIPFromRemoteAddr] normalizes inline
256+
// (Unmap, but zone preserved for legitimate link-local connections).
257+
func parseHeaderAddr(s string) (netip.Addr, bool) {
258+
ip, err := netip.ParseAddr(s)
259+
if err != nil {
260+
return netip.Addr{}, false
261+
}
262+
return ip.Unmap().WithZone(""), true
263+
}

0 commit comments

Comments
 (0)