bvandeusen/minstrel
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 46 Wiki Activity

feat(net): trusted-proxy depth so real client IPs survive a proxy — #2453
test-go / test (push) Failing after 50s
Details
test-web / test (push) Failing after 50s
Details
test-go / integration (push) Failing after 2m19s
Details

Browse Source 
Fixes the defect the operator spotted in #370 immediately after it shipped:
auth.ClientIP ignored X-Forwarded-For whenever RemoteAddr was public, so a
proxy on a public address — a separate host, or a CDN, i.e. anyone running
this publicly, since public means TLS means a proxy — recorded the PROXY for
every session. created_ip and last_ip were then always equal and the
"Address changed" signal could never fire. The feature looked like it worked
and reported nothing.

Replaced with the standard trusted-hop model (Rails, Caddy, Traefik, nginx).
XFF grows left-to-right as each proxy appends the peer it received from, so
for client -> CDN -> own-proxy -> app the app sees [client, CDN] with
RemoteAddr = own-proxy, and the client sits at XFF[len - hops]:

  0  RemoteAddr, XFF ignored — no proxy
  1  the address your own proxy observed
  2  through a CDN in front of your proxy

Default 1, per the operator: publicly reachable means a TLS terminator in
front.

The cost is real and stated rather than hidden. hops >= 1 DECLARES that a
proxy exists; set it with no proxy, or deeper than the actual chain, and the
index reaches attacker-supplied entries, letting a visitor choose which
address their own session shows — defeating exactly the detection #370 is
for. That's inherent to the model, which is why 0 is a first-class value and
the admin card says "count your proxies, don't guess high" instead of just
exposing a number. Both mis-set shapes are pinned by tests so they stay known
consequences rather than surprises.

Migration 0053 + internal/netsettings, cached under an RWMutex. That's not an
optimisation: ClientIP runs in RequireUser for every authenticated request, so
a per-request query would put the database on the critical path of the whole
API. New() always returns a usable service so a boot-time DB hiccup degrades
to the default instead of breaking that path (rule #131), and Hops() is
nil-safe because test routers construct middleware without it.

RequireUser now takes a func() int rather than an int — the value is
operator-editable at runtime while the middleware is built once at boot, and
reading it per request is what makes a save take effect with no restart
(rule #25).

The admin card is verifiable, not just configurable: it reports the address
the CURRENT setting resolves THIS request to, the raw forwarded chain, and the
socket peer — so you set the number, save, and confirm the address matches the
machine you're on. It also counts the arriving chain and says how many proxies
that implies. GET/PUT both return that payload, PUT recomputed under the new
value, so the effect is visible without a reload.

Also fixes styling in the #370 card that CI could not catch: text-destructive
and bg-destructive don't exist in this Tailwind config — the palette is
colors.action.destructive — so the "Address changed" warning and the
sign-out-others button were rendering unstyled. Both now use
text-action-destructive / bg-action-destructive / text-action-fg.

Not done here: requestlog.go still logs raw RemoteAddr and will disagree with
the sessions UI about who connected. Left for its own change.
This commit is contained in:
bvandeusen
2026-08-05 10:07:43 -04:00
parent bf649f3beb
commit 381e9cedb7
19 changed files with 788 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/auth/clientip.go
+82 -63
View File
@@ -6,51 +6,101 @@ import (
"strings"
)
// ClientIP returns the caller's address for the active-sessions surface (#370).
// ClientIP returns the caller's address, reading through trustedProxyHops
// reverse proxies (#2453).
//
// Both obvious implementations are wrong, and they're wrong in ways that
// matter specifically because this feeds a compromise-detection UI:
// X-Forwarded-For grows left-to-right: every proxy APPENDS the peer it
// received the request from. For client -> CDN -> own-proxy -> Minstrel the
// app sees XFF = [client, CDN] and RemoteAddr = own-proxy. Each trusted proxy
// therefore accounts for one entry counting from the right, and the first
// address we were NOT told to trust is the client:
//
// - r.RemoteAddr alone. Minstrel is normally behind a reverse proxy, so
// every session would show the proxy's address — noise shaped like data,
// hiding the exact thing the operator is looking for.
// - Trusting X-Forwarded-For. Any client can set that header, so an
// attacker could choose what appears in their victim's session list.
// A security surface an attacker can write to is worse than none.
// hops 0 -> RemoteAddr; XFF ignored entirely
// hops 1 -> XFF[1] = CDN — trusting only our own proxy, the most we can
// honestly claim is the address it told us about
// hops 2 -> XFF[0] = client
//
// So the header is trusted only when the request actually arrived from a
// proxy. If RemoteAddr is public, the caller reached us directly and its XFF
// is attacker-controlled, so it's ignored outright. If RemoteAddr is
// private/loopback, XFF is walked from the RIGHT — entries are appended as a
// request passes through infrastructure, so the rightmost end is the one our
// own proxies wrote — and the first address that isn't itself a proxy range
// wins. A client forging XFF can only prepend to the untrusted left end,
// which that walk never reaches.
// This replaces an earlier heuristic that ignored XFF whenever RemoteAddr was
// public. That was safe but useless in the deployment that matters: a proxy
// on a public address (separate host, or a CDN) meant every session recorded
// the proxy, so the active-sessions surface could never show an address
// change (#370).
//
// Known limitation, failing closed on purpose: if the proxy sits on a PUBLIC
// address (a separate host, or a CDN in front), RemoteAddr isn't in a proxy
// range, so we report the proxy rather than the end user. That's a true fact
// about where the request came from, which beats trusting a forgeable header.
// # What the operator is asserting
//
// Returns "" when nothing usable can be determined. Callers store that as-is
// and the UI renders "unknown" rather than inventing a value.
func ClientIP(r *http.Request) string {
// hops >= 1 is a DECLARATION that a proxy sits in front. Two ways to get it
// wrong, both worth understanding rather than papering over:
//
// - Set to 1+ with NO proxy: any client can forge X-Forwarded-For and pick
// what its own session row shows, defeating the compromise detection.
// - Set HIGHER than the real chain: the index runs past the proxy-written
// entries into attacker-supplied ones, same result.
//
// Both are inherent to the trusted-hop model — Rails, Caddy, Traefik and
// nginx all behave this way — which is why 0 is a first-class value and the
// admin card tells the operator to count their proxies.
func ClientIP(r *http.Request, trustedProxyHops int) string {
remote := hostOf(r.RemoteAddr)
ip := net.ParseIP(remote)
if ip == nil || !isProxyRange(ip) {
if trustedProxyHops <= 0 {
return remote
}
if forwarded := forwardedClient(r.Header.Get("X-Forwarded-For")); forwarded != "" {
return forwarded
chain := forwardedChain(r)
if len(chain) == 0 {
// No forwarding header: either there's genuinely no proxy, or one is
// misconfigured. The socket peer is the only thing we actually know.
return remote
}
// Some proxies set only X-Real-IP. The trust condition is already
// satisfied — we know this request came from a proxy range.
if real := net.ParseIP(strings.TrimSpace(r.Header.Get("X-Real-IP"))); real != nil {
return real.String()
// Clamp rather than reject: a chain shorter than the configured depth
// means the operator over-counted, and the leftmost entry is the closest
// thing to a client on offer. The caveat above covers the risk.
idx := len(chain) - trustedProxyHops
if idx < 0 {
idx = 0
}
if ip := net.ParseIP(chain[idx]); ip != nil {
return ip.String()
}
// A proxy wrote something that isn't an address. Positional meaning is
// lost, so fall back to what we can verify ourselves.
return remote
}
// forwardedChain returns the X-Forwarded-For entries in wire order, or the
// single X-Real-IP value when XFF is absent.
//
// Entries are kept verbatim, including unparseable ones: their POSITION is
// what carries meaning here, so silently dropping a malformed hop would
// shift every index and could hand back an attacker-supplied entry.
func forwardedChain(r *http.Request) []string {
raw := r.Header.Get("X-Forwarded-For")
if strings.TrimSpace(raw) == "" {
// Some proxies set only X-Real-IP, which by construction is a single
// hop — the address that proxy saw.
if real := strings.TrimSpace(r.Header.Get("X-Real-IP")); real != "" {
return []string{real}
}
return nil
}
parts := strings.Split(raw, ",")
out := make([]string, 0, len(parts))
for _, p := range parts {
if p = strings.TrimSpace(p); p != "" {
out = append(out, p)
}
}
return out
}
// hopsOf reads a trusted-depth accessor, treating a nil one as "trust
// nothing". Test contexts and any future caller that hasn't wired the
// settings service get the safe reading rather than a panic.
func hopsOf(fn func() int) int {
if fn == nil {
return 0
}
return fn()
}
// hostOf strips the port from a RemoteAddr, tolerating values that have none.
func hostOf(remoteAddr string) string {
host, _, err := net.SplitHostPort(remoteAddr)
@@ -59,34 +109,3 @@ func hostOf(remoteAddr string) string {
}
return host
}
// forwardedClient walks an X-Forwarded-For value right-to-left and returns
// the first address outside our proxy ranges — see ClientIP for why the
// direction matters. Returns "" if the header is absent, malformed, or
// contains nothing but proxy addresses.
func forwardedClient(header string) string {
parts := strings.Split(header, ",")
for i := len(parts) - 1; i >= 0; i-- {
ip := net.ParseIP(strings.TrimSpace(parts[i]))
if ip == nil || isProxyRange(ip) {
continue
}
return ip.String()
}
return ""
}
// isProxyRange reports whether ip is an address a reverse proxy would
// plausibly occupy in a self-hosted deployment: loopback, RFC1918 / ULA
// (both covered by IsPrivate), link-local, or unspecified.
//
// Deliberately not configurable. These ranges cover proxy-on-same-host and
// proxy-on-the-same-docker-network, which is essentially every self-hosted
// install, and it works with no setup at all (rule #26). An exotic topology
// can motivate a setting when one actually turns up.
func isProxyRange(ip net.IP) bool {
return ip.IsLoopback() ||
ip.IsPrivate() ||
ip.IsLinkLocalUnicast() ||
ip.IsUnspecified()
}
internal/auth/clientip_test.go
+106 -57
View File
@@ -5,99 +5,148 @@ import (
"testing"
)
// The spoofing cases below are the reason this function exists rather than a
// one-line r.RemoteAddr read, so they're asserted explicitly rather than
// folded into the happy-path table.
// The hop arithmetic is the whole feature, so the table is written as
// deployment topologies rather than abstract inputs.
func TestClientIP(t *testing.T) {
tests := []struct {
name string
hops int
remoteAddr string
forwarded string
realIP string
want string
}{
{
name: "direct connection, no proxy headers",
name: "no proxy configured, socket peer wins",
hops: 0,
remoteAddr: "203.0.113.5:51234",
want: "203.0.113.5",
},
{
// The attack this guards against: a client connecting straight to
// us claims to be someone else. RemoteAddr is public, so it did
// NOT come through our proxy, so its XFF is worthless.
name: "direct connection ignores forged X-Forwarded-For",
// hops 0 is the setting for a directly-exposed instance, and it
// must make forged headers inert.
name: "hops 0 ignores a forged forwarded header",
hops: 0,
remoteAddr: "203.0.113.5:51234",
forwarded: "198.51.100.99",
want: "203.0.113.5",
},
{
name: "direct connection ignores forged X-Real-IP",
// The common case: one TLS-terminating proxy. Note RemoteAddr is
// PUBLIC here — a proxy on its own host — which the previous
// private-range heuristic got wrong.
name: "one proxy on a public address yields the client",
hops: 1,
remoteAddr: "203.0.113.200:40000",
forwarded: "198.51.100.7",
want: "198.51.100.7",
},
{
name: "one proxy on a private address yields the client",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "198.51.100.7",
want: "198.51.100.7",
},
{
// client -> Cloudflare -> own proxy -> app.
// Trusting only our own proxy, the honest answer is Cloudflare:
// that's the address our proxy actually observed.
name: "cdn chain with hops 1 stops at the cdn",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "198.51.100.7, 203.0.113.50",
want: "203.0.113.50",
},
{
// Same chain, both hops trusted — now we reach the real client.
name: "cdn chain with hops 2 reaches the client",
hops: 2,
remoteAddr: "172.18.0.1:40000",
forwarded: "198.51.100.7, 203.0.113.50",
want: "198.51.100.7",
},
{
// A client prepending a lie is only reachable if the operator
// over-counts their proxies; at the correct depth it's skipped.
name: "forged prefix is not reached at the correct depth",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "1.2.3.4, 198.51.100.7",
want: "198.51.100.7",
},
{
// The documented mis-set failure, pinned so it stays a KNOWN
// consequence rather than a surprise: depth deeper than the real
// chain reads attacker-supplied input.
name: "hops set deeper than the chain clamps to the leftmost entry",
hops: 5,
remoteAddr: "172.18.0.1:40000",
forwarded: "1.2.3.4, 198.51.100.7",
want: "1.2.3.4",
},
{
name: "no forwarding header falls back to the socket peer",
hops: 1,
remoteAddr: "203.0.113.5:51234",
realIP: "198.51.100.99",
want: "203.0.113.5",
},
{
name: "behind proxy, single forwarded client",
name: "x-real-ip used when forwarded-for is absent",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "203.0.113.5",
want: "203.0.113.5",
realIP: "198.51.100.7",
want: "198.51.100.7",
},
{
// A client that prepends a lie to XFF only pollutes the LEFT end;
// the proxy appends the address it actually saw on the right. The
// right-to-left walk reaches the truth first.
name: "behind proxy, forged prefix is skipped for the appended truth",
remoteAddr: "10.0.0.2:40000",
forwarded: "198.51.100.99, 203.0.113.5",
want: "203.0.113.5",
},
{
name: "behind proxy chain, internal hops skipped",
remoteAddr: "10.0.0.2:40000",
forwarded: "203.0.113.5, 10.0.0.7, 172.18.0.3",
want: "203.0.113.5",
},
{
name: "behind proxy, X-Real-IP used when no forwarded header",
remoteAddr: "127.0.0.1:40000",
realIP: "203.0.113.5",
want: "203.0.113.5",
},
{
// LAN client through a LAN proxy: everything is private, so there
// is no public address to find. Reporting the peer is honest.
name: "behind proxy, all-private chain falls back to remote",
name: "forwarded-for wins over x-real-ip when both present",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "192.168.1.50, 172.18.0.3",
forwarded: "198.51.100.7",
realIP: "1.2.3.4",
want: "198.51.100.7",
},
{
// Positions are preserved, so a garbage hop can be selected —
// in which case we fall back rather than return nonsense.
name: "unparseable selected entry falls back to the socket peer",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: "198.51.100.7, not-an-ip",
want: "172.18.0.1",
},
{
name: "behind proxy, malformed forwarded entries ignored",
remoteAddr: "172.18.0.1:40000",
forwarded: "not-an-ip, 203.0.113.5, also-garbage",
want: "203.0.113.5",
},
{
name: "remote addr without a port is tolerated",
remoteAddr: "203.0.113.5",
want: "203.0.113.5",
},
{
name: "ipv6 remote addr",
remoteAddr: "[2001:db8::1]:51234",
want: "2001:db8::1",
},
{
name: "ipv6 forwarded client behind proxy",
name: "ipv6 client through one proxy",
hops: 1,
remoteAddr: "[fd00::1]:40000",
forwarded: "2001:db8::5",
want: "2001:db8::5",
},
{
name: "ipv6 socket peer without proxy",
hops: 0,
remoteAddr: "[2001:db8::1]:51234",
want: "2001:db8::1",
},
{
name: "remote addr without a port is tolerated",
hops: 0,
remoteAddr: "203.0.113.5",
want: "203.0.113.5",
},
{
name: "empty remote addr yields empty",
hops: 1,
remoteAddr: "",
want: "",
},
{
name: "whitespace-only forwarded header is treated as absent",
hops: 1,
remoteAddr: "172.18.0.1:40000",
forwarded: " ",
want: "172.18.0.1",
},
}
for _, tc := range tests {
@@ -113,8 +162,8 @@ func TestClientIP(t *testing.T) {
if tc.realIP != "" {
r.Header.Set("X-Real-IP", tc.realIP)
}
if got := ClientIP(r); got != tc.want {
t.Errorf("ClientIP() = %q, want %q", got, tc.want)
if got := ClientIP(r, tc.hops); got != tc.want {
t.Errorf("ClientIP(hops=%d) = %q, want %q", tc.hops, got, tc.want)
}
})
}
internal/auth/session.go
+8 -2
View File
@@ -56,7 +56,13 @@ const SessionCookieName = "minstrel_session"
// bearer header and puts the dbq.User in request context via userCtxKey.
// Requests without a valid session return 401 with no body so callers don't
// leak whether the username existed (matches the /rest/* auth posture).
func RequireUser(pool *pgxpool.Pool) func(http.Handler) http.Handler {
//
// trustedHops supplies the reverse-proxy depth used to record the session's
// current address (#2453). It's a func rather than an int because the value
// is operator-editable at runtime and this middleware is constructed once at
// boot — reading it per request is what makes an admin change take effect
// without a restart. Passing nil means "trust nothing", i.e. the socket peer.
func RequireUser(pool *pgxpool.Pool, trustedHops func() int) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := sessionTokenFromRequest(r)
@@ -103,7 +109,7 @@ func RequireUser(pool *pgxpool.Pool) func(http.Handler) http.Handler {
// surface exists to show, and it costs nothing extra here.
if err := q.TouchSessionLastSeen(r.Context(), dbq.TouchSessionLastSeenParams{
ID: sess.ID,
LastIp: ClientIP(r),
LastIp: ClientIP(r, hopsOf(trustedHops)),
}); err != nil {
slog.Warn("api: touch session last_seen failed", "err", err)
}
internal/auth/session_test.go
+1 -1
View File
@@ -57,7 +57,7 @@ func TestRequireUser_RejectsWhenNoCookieOrBearer(t *testing.T) {
next := http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
t.Fatal("handler must not be called")
})
h := RequireUser(nil)(next)
h := RequireUser(nil, nil)(next)
req := httptest.NewRequest(http.MethodGet, "/api/me", nil)
w := httptest.NewRecorder()