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 <cursoragent@cursor.com>
This commit is contained in:
Vojtech Vitek 2026-05-21 10:10:22 +02:00
parent 22f567f627
commit a8e3dbfe90
No known key found for this signature in database

View file

@ -29,14 +29,24 @@ const xForwardedForHeader = "X-Forwarded-For"
// pass through from the client by default in those products; don't use them
// unless your edge strips the inbound value.
//
// If the header reaches us with multiple values (misconfigured proxy that
// appends, or a downstream proxy not stripping a client-supplied value),
// the LAST value wins — that's the one set by the hop closest to us, and
// therefore the most trusted. Fail-closed if the last value doesn't parse:
// no client IP is set rather than falling back to earlier (less-trusted)
// values.
//
// v4-mapped IPv6 (::ffff:a.b.c.d) folds to plain v4 and IPv6 zones are
// stripped before storage.
func ClientIPFromHeader(trustedHeader string) func(http.Handler) http.Handler {
header := http.CanonicalHeaderKey(trustedHeader)
return func(h http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if ip, ok := parseHeaderAddr(r.Header.Get(header)); ok {
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, ip))
values := r.Header.Values(header)
if len(values) > 0 {
if ip, ok := parseHeaderAddr(values[len(values)-1]); ok {
r = r.WithContext(context.WithValue(r.Context(), clientIPCtxKey, ip))
}
}
h.ServeHTTP(w, r)
})