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 <cursoragent@cursor.com>
This commit is contained in:
Vojtech Vitek 2026-05-21 01:42:13 +02:00
parent 717827a760
commit 5dd2243e01
No known key found for this signature in database

View file

@ -48,6 +48,9 @@ func ClientIPFromHeader(trustedHeader string) func(http.Handler) http.Handler {
// of the given trusted CIDR prefixes. The first IP that is not trusted is
// the client. Read it with [GetClientIP].
//
// An unparseable entry mid-chain aborts the walk and leaves no client IP
// 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:
//
@ -193,8 +196,11 @@ func mergeXFF(headers []string) []string {
}
// rightmostUntrustedXFF walks all X-Forwarded-For header values right-to-left
// across the merged chain, skipping IPs that match trustedPrefixes (and
// unparseable / empty entries), and returns the first remaining valid IP.
// across the merged chain, skipping trusted-prefix and empty entries, and
// returns the first remaining valid IP. An unparseable entry encountered
// mid-walk fails closed: the walk is abandoned and no IP is returned, since
// an unparseable hop is indistinguishable from a hostile or missing one and
// we cannot safely keep walking past it.
//
// Walks the headers lazily rather than calling [mergeXFF] so the common case
// — one trusted hop, the rightmost entry is the client — returns on the very
@ -215,7 +221,10 @@ func rightmostUntrustedXFF(headers []string, trustedPrefixes []netip.Prefix) (ne
continue
}
ip, ok := parseHeaderAddr(v)
if !ok || inAnyPrefix(ip, trustedPrefixes) {
if !ok {
return netip.Addr{}, false
}
if inAnyPrefix(ip, trustedPrefixes) {
continue
}
return ip, true