web: add XFF debug endpoint and useful defaults for Server.TrustedProxies (#112)

Author: astrophena

web/debug.go

@@ -12,12 +12,15 @@ import (
 	_ "embed"
 	"html"
 	"html/template"
+	"net"
 	"net/http"
 	"net/http/pprof"
+	"net/netip"
 	"net/url"
 	"os"
 	"runtime"
 	"slices"
+	"strings"
 	"sync"
 	"time"
 
@@ -119,6 +122,88 @@ var timeStart = time.Now()
 
 func uptime() time.Duration { return time.Since(timeStart).Round(time.Second) }
 
+type xffDebugPart struct {
+	Raw    string `json:"raw"`
+	Parsed string `json:"parsed,omitempty"`
+	Valid  bool   `json:"valid"`
+}
+
+type xffDebugResponse struct {
+	RemoteAddr       string `json:"remote_addr"`
+	RemoteHost       string `json:"remote_host"`
+	RemoteAddrParsed bool   `json:"remote_addr_parsed"`
+	RemoteAddrIP     string `json:"remote_addr_ip,omitempty"`
+
+	ConnNetwork     string `json:"conn_network,omitempty"`
+	ListenerNetwork string `json:"listener_network,omitempty"`
+
+	UsingDefaultTrustedProxies bool     `json:"using_default_trusted_proxies"`
+	TrustedForwardedSource     bool     `json:"trusted_forwarded_source"`
+	TrustedProxies             []string `json:"trusted_proxies"`
+
+	XForwardedForRaw   string         `json:"x_forwarded_for_raw"`
+	XForwardedForParts []xffDebugPart `json:"x_forwarded_for_parts"`
+	XRealIP            string         `json:"x_real_ip,omitempty"`
+	Forwarded          string         `json:"forwarded,omitempty"`
+
+	RealIPResult string `json:"real_ip_result"`
+}
+
+func (s *Server) xffDebugHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		host, _, err := net.SplitHostPort(r.RemoteAddr)
+		if err != nil {
+			host = r.RemoteAddr
+		}
+		host = strings.TrimSpace(host)
+
+		addr, parseErr := netip.ParseAddr(host)
+		hasAddr := parseErr == nil
+
+		var trustedProxies []string
+		for _, prefix := range s.trustedProxies() {
+			trustedProxies = append(trustedProxies, prefix.String())
+		}
+
+		var parts []xffDebugPart
+		for part := range strings.SplitSeq(r.Header.Get("X-Forwarded-For"), ",") {
+			raw := strings.TrimSpace(part)
+			if raw == "" {
+				continue
+			}
+
+			item := xffDebugPart{Raw: raw}
+			if parsed, err := netip.ParseAddr(raw); err == nil {
+				item.Valid = true
+				item.Parsed = parsed.String()
+			}
+			parts = append(parts, item)
+		}
+
+		connNetwork, _ := r.Context().Value(connNetworkContextKey).(string)
+		resp := xffDebugResponse{
+			RemoteAddr:                 r.RemoteAddr,
+			RemoteHost:                 host,
+			RemoteAddrParsed:           hasAddr,
+			ConnNetwork:                connNetwork,
+			ListenerNetwork:            s.listenerNetwork,
+			UsingDefaultTrustedProxies: s.TrustedProxies == nil,
+			TrustedForwardedSource:     s.isTrustedForwardedSource(r, hasAddr, addr),
+			TrustedProxies:             trustedProxies,
+			XForwardedForRaw:           r.Header.Get("X-Forwarded-For"),
+			XForwardedForParts:         parts,
+			XRealIP:                    r.Header.Get("X-Real-IP"),
+			Forwarded:                  r.Header.Get("Forwarded"),
+			RealIPResult:               s.realIP(r),
+		}
+		if hasAddr {
+			resp.RemoteAddrIP = addr.String()
+		}
+
+		RespondJSON(w, resp)
+	})
+}
+
 // ServeHTTP implements the [http.Handler] interface.
 func (d *DebugHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.URL.Path != "/debug/" {

web/debug_test.go

@@ -9,6 +9,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"net/http/httptest"
+	"net/netip"
 	"os"
 	"strings"
 	"testing"
@@ -158,6 +160,47 @@ func TestDebuggerDiscovery(t *testing.T) {
 	}
 }
 
+func TestXFFDebugHandler(t *testing.T) {
+	t.Parallel()
+
+	s := &Server{}
+	req := httptest.NewRequest(http.MethodGet, "/debug/xff", nil)
+	req.RemoteAddr = "127.0.0.1:1234"
+	req.Header.Set("X-Forwarded-For", " 203.0.113.9 , invalid")
+	req.Header.Set("X-Real-IP", "198.51.100.10")
+	req.Header.Set("Forwarded", "for=203.0.113.9")
+
+	w := httptest.NewRecorder()
+	s.xffDebugHandler().ServeHTTP(w, req)
+
+	var got xffDebugResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("failed to unmarshal xff debug response: %v\nbody: %s", err, w.Body.String())
+	}
+
+	testutil.AssertEqual(t, true, got.UsingDefaultTrustedProxies)
+	testutil.AssertEqual(t, true, got.TrustedForwardedSource)
+	testutil.AssertEqual(t, []string{"127.0.0.0/8"}, got.TrustedProxies)
+	testutil.AssertEqual(t, "203.0.113.9", got.RealIPResult)
+	testutil.AssertEqual(t, "198.51.100.10", got.XRealIP)
+	testutil.AssertEqual(t, "for=203.0.113.9", got.Forwarded)
+	if len(got.XForwardedForParts) != 2 {
+		t.Fatalf("got %d XFF parts, want 2: %+v", len(got.XForwardedForParts), got.XForwardedForParts)
+	}
+	testutil.AssertEqual(t, true, got.XForwardedForParts[0].Valid)
+	testutil.AssertEqual(t, false, got.XForwardedForParts[1].Valid)
+
+	s.TrustedProxies = []netip.Prefix{}
+	w = httptest.NewRecorder()
+	s.xffDebugHandler().ServeHTTP(w, req)
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("failed to unmarshal xff debug response: %v\nbody: %s", err, w.Body.String())
+	}
+	testutil.AssertEqual(t, false, got.UsingDefaultTrustedProxies)
+	testutil.AssertEqual(t, false, got.TrustedForwardedSource)
+	testutil.AssertEqual(t, "127.0.0.1", got.RealIPResult)
+}
+
 func getDebug(t *testing.T, mux *http.ServeMux) string {
 	return send(t, mux, http.MethodGet, "/debug/", http.StatusOK)
 }

web/server.go

@@ -72,7 +72,8 @@ type Server struct {
 	// Also, the server will start the systemd watchdog timer if enabled.
 	NotifySystemd bool
 	// TrustedProxies is a list of proxy CIDR ranges trusted to provide X-Forwarded-For.
-	// If empty, X-Forwarded-For is ignored.
+	// If nil, 127.0.0.0/8 is trusted by default. If empty but non-nil,
+	// X-Forwarded-For is ignored.
 	TrustedProxies []netip.Prefix
 
 	handler syncx.Lazy[*handler]
@@ -198,14 +199,25 @@ func (s *Server) realIP(r *http.Request) string {
 }
 
 func (s *Server) isTrustedProxy(addr netip.Addr) bool {
-	for _, prefix := range s.TrustedProxies {
+	for _, prefix := range s.trustedProxies() {
 		if prefix.Contains(addr) {
 			return true
 		}
 	}
 	return false
 }
 
+var defaultTrustedProxies = []netip.Prefix{
+	netip.MustParsePrefix("127.0.0.0/8"),
+}
+
+func (s *Server) trustedProxies() []netip.Prefix {
+	if s.TrustedProxies == nil {
+		return defaultTrustedProxies
+	}
+	return s.TrustedProxies
+}
+
 func (s *Server) isTrustedForwardedSource(r *http.Request, hasAddr bool, addr netip.Addr) bool {
 	if network, _ := r.Context().Value(connNetworkContextKey).(string); network == "unix" {
 		return true
@@ -271,7 +283,7 @@ func (s *Server) initHandler() *handler {
 
 	s.Mux.Handle("GET /static/", hashfs.FileServer(h.static))
 	if s.Debuggable {
-		Debugger(s.Mux)
+		Debugger(s.Mux).Handle("xff", "X-Forwarded-For", s.xffDebugHandler())
 	}
 
 	if s.CrossOriginProtection != nil {

web/server_test.go

@@ -224,6 +224,12 @@ func TestServerRealIP(t *testing.T) {
 	req.Header.Set("X-Forwarded-For", "203.0.113.9")
 	testutil.AssertEqual(t, "198.51.100.10", s.realIP(req))
 
+	req.RemoteAddr = "127.0.0.1:1234"
+	testutil.AssertEqual(t, "203.0.113.9", s.realIP(req))
+
+	s.TrustedProxies = []netip.Prefix{}
+	testutil.AssertEqual(t, "127.0.0.1", s.realIP(req))
+
 	prefix := netip.MustParsePrefix("192.0.2.0/24")
 	s.TrustedProxies = []netip.Prefix{prefix}
 	req.RemoteAddr = "192.0.2.10:9999"