Throttle failed admin password attempts per client IP

The admin password auth endpoint (POST /admin/auth) had no rate limiting,
so an attacker with network access could brute-force admin.password at
full speed. See GHSA-8w47-3f5r-h9xm.

Add a small, dependency-free AuthThrottle middleware that limits failed
attempts per client IP within a time window (10 per minute), and wrap
the auth route with it. Properties that matter for an auth endpoint:

- Only failures count and the per-IP limit is checked before the
  password is compared, so a caller with valid credentials is not
  throttled - including while another source is attacking - and the
  response does not reveal whether a guess was correct once the limit is
  hit.
- Each source IP is tracked independently, with the map bounded and
  reset per window to keep memory in check.
- Forwarded headers (X-Real-IP/X-Forwarded-For) are only trusted when
  the socket peer is a private/loopback address (a local proxy or load
  balancer), so a direct client cannot spoof them to evade throttling or
  lock out another IP; header values are validated as IPs.

This is best-effort, in-process defense in depth: the primary protection
of the admin endpoint must be done at the infrastructure level (firewall
rules, private network, authenticating reverse proxy), as noted at the
route registration.

The middleware is reusable for other endpoints via NewAuthThrottle and
its Middleware method.

Author: FZambia

internal/admin/handlers.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"strings"
+	"time"
 
 	"github.com/centrifugal/centrifugo/v6/internal/api"
 	"github.com/centrifugal/centrifugo/v6/internal/configtypes"
@@ -35,7 +36,18 @@ func NewHandler(n *centrifuge.Node, apiExecutor *api.Executor, c Config) *Handle
 	mux := http.NewServeMux()
 	prefix := strings.TrimRight(h.config.HandlerPrefix, "/")
 	mux.Handle(prefix+"/admin/init", http.HandlerFunc(h.initHandler))
-	mux.Handle(prefix+"/admin/auth", middleware.Post(http.HandlerFunc(h.authHandler)))
+	// Throttle repeated failed password attempts per client IP to slow brute-force
+	// of admin.password. Only failures count and each IP is tracked independently,
+	// so a valid login is never throttled - including while another source attacks.
+	//
+	// This is best-effort, in-process protection only. The admin auth endpoint is
+	// intended to be reachable by trusted operators, and Centrifugo recommends
+	// restricting access to it at the infrastructure level (firewall rules, a
+	// private network, an authenticating reverse proxy, etc.). The throttle here
+	// raises the bar for brute-force but is not a substitute for that: the primary
+	// protection of the admin endpoint must be done at the infrastructure level.
+	authThrottle := middleware.NewAuthThrottle(10, time.Minute, nil)
+	mux.Handle(prefix+"/admin/auth", middleware.Post(authThrottle.Middleware(http.HandlerFunc(h.authHandler))))
 	mux.Handle(prefix+"/admin/api", middleware.Post(h.adminSecureTokenAuth(api.NewHandler(n, apiExecutor, api.Config{}).OldRoute())))
 
 	webPrefix := prefix + "/"

internal/admin/handlers_test.go

@@ -106,6 +106,38 @@ func TestAuthHandler_InvalidPassword(t *testing.T) {
 	require.Equal(t, http.StatusBadRequest, resp.Code)
 }
 
+// TestAuthHandler_Throttled ensures the /admin/auth route throttles repeated
+// failed password attempts per client IP, without blocking a valid login from
+// another IP while an attacker is brute-forcing.
+func TestAuthHandler_Throttled(t *testing.T) {
+	node := &centrifuge.Node{}
+	cfg := Config{Password: "test-password", Secret: "test-secret"}
+	handler := NewHandler(node, nil, cfg)
+
+	post := func(ip, password string) int {
+		form := url.Values{}
+		form.Add("password", password)
+		req := httptest.NewRequest("POST", "/admin/auth", strings.NewReader(form.Encode()))
+		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+		req.RemoteAddr = "10.0.0.1:12345" // trusted local proxy peer, so X-Real-IP is honored.
+		req.Header.Set("X-Real-IP", ip)
+		resp := httptest.NewRecorder()
+		handler.ServeHTTP(resp, req)
+		return resp.Code
+	}
+
+	// The default limit is 10 failures per IP per window.
+	for i := 0; i < 10; i++ {
+		require.Equal(t, http.StatusBadRequest, post("6.6.6.6", "wrong"), "attempt %d", i)
+	}
+	require.Equal(t, http.StatusTooManyRequests, post("6.6.6.6", "wrong"))
+	// The attacker cannot tell a correct guess from a throttled one.
+	require.Equal(t, http.StatusTooManyRequests, post("6.6.6.6", "test-password"))
+
+	// A valid login from a different IP still succeeds during the attack.
+	require.Equal(t, http.StatusOK, post("7.7.7.7", "test-password"))
+}
+
 // TestAdminSecureTokenAuth_InsecureMode tests adminSecureTokenAuth allows request in insecure mode.
 func TestAdminSecureTokenAuth_InsecureMode(t *testing.T) {
 	config := Config{Insecure: true}

internal/middleware/auththrottle.go

@@ -0,0 +1,144 @@
+package middleware
+
+import (
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// AuthThrottle limits repeated failing requests per client IP within a time
+// window. It is meant for authentication-style endpoints (admin password auth,
+// and any other endpoint where a caller repeatedly retries credentials) to slow
+// brute-force without ever throttling a caller that succeeds.
+//
+// Only failures are counted, and the per-IP limit is checked before the wrapped
+// handler runs, which gives two properties that matter for auth endpoints:
+//
+//   - A caller presenting valid credentials is never throttled, even while a
+//     different source is actively brute-forcing: success does not accrue against
+//     the limit, and each source IP is counted independently.
+//   - Once an IP is over the limit its requests are rejected before the handler
+//     runs, so the response cannot reveal whether the submitted credentials were
+//     valid.
+//
+// It is safe for concurrent use. Wrap a handler with Middleware:
+//
+//	throttle := middleware.NewAuthThrottle(10, time.Minute, nil)
+//	mux.Handle(path, throttle.Middleware(handler))
+type AuthThrottle struct {
+	max       int
+	window    time.Duration
+	isFailure func(status int) bool
+
+	mu        sync.Mutex
+	failures  map[string]int
+	windowEnd time.Time
+}
+
+// authThrottleMapCap bounds the number of tracked IPs so a flood of requests with
+// varying source addresses cannot grow the map without limit.
+const authThrottleMapCap = 10000
+
+// NewAuthThrottle creates an AuthThrottle allowing at most max failing requests
+// per client IP within window, after which further requests from that IP are
+// rejected with 429 until the window rolls over. isFailure decides, from the
+// status the wrapped handler wrote, whether a request counts as a failure; if
+// nil, any status >= 400 counts.
+func NewAuthThrottle(max int, window time.Duration, isFailure func(status int) bool) *AuthThrottle {
+	if isFailure == nil {
+		isFailure = func(status int) bool { return status >= 400 }
+	}
+	return &AuthThrottle{
+		max:       max,
+		window:    window,
+		isFailure: isFailure,
+		failures:  make(map[string]int),
+	}
+}
+
+// Middleware wraps h with per-IP failure throttling.
+func (t *AuthThrottle) Middleware(h http.Handler) http.Handler {
+	retryAfter := strconv.Itoa(int(t.window.Seconds()))
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ip := clientIP(r)
+		if !t.allow(ip) {
+			w.Header().Set("Retry-After", retryAfter)
+			http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
+			return
+		}
+		sw := &statusResponseWriter{ResponseWriter: w, status: http.StatusOK}
+		h.ServeHTTP(sw, r)
+		if t.isFailure(sw.Status()) {
+			t.recordFailure(ip)
+		}
+	})
+}
+
+// allow reports whether another request from ip may reach the handler. It rolls
+// the window over, discarding accumulated counts once the window elapses.
+func (t *AuthThrottle) allow(ip string) bool {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if now := time.Now(); now.After(t.windowEnd) {
+		t.failures = make(map[string]int)
+		t.windowEnd = now.Add(t.window)
+	}
+	return t.failures[ip] < t.max
+}
+
+// recordFailure counts one failed request from ip. New IPs are not tracked once
+// the map is at capacity, keeping memory bounded under an address-varying flood.
+func (t *AuthThrottle) recordFailure(ip string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if _, tracked := t.failures[ip]; !tracked && len(t.failures) >= authThrottleMapCap {
+		return
+	}
+	t.failures[ip]++
+}
+
+// clientIP derives the client address used as the throttle key.
+//
+// Forwarded headers are only trusted when the immediate socket peer is a private
+// or loopback address, i.e. a local reverse proxy or load balancer (Centrifugo is
+// commonly deployed behind one). For a direct public client the headers are
+// client-controlled and ignored, so a peer cannot spoof them to evade throttling
+// or lock out another IP. Header values are validated and canonicalized as IPs
+// before use, so junk cannot inflate map keys or fragment the keyspace.
+func clientIP(r *http.Request) string {
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		host = r.RemoteAddr
+	}
+	peer := net.ParseIP(host)
+	if peer == nil || (!peer.IsLoopback() && !peer.IsPrivate()) {
+		return host
+	}
+	// Peer is a trusted local proxy: use the forwarded client address.
+	if ip := parseIP(r.Header.Get("X-Real-IP")); ip != "" {
+		return ip
+	}
+	if fwd := r.Header.Get("X-Forwarded-For"); fwd != "" {
+		if i := strings.IndexByte(fwd, ','); i >= 0 {
+			fwd = fwd[:i]
+		}
+		if ip := parseIP(strings.TrimSpace(fwd)); ip != "" {
+			return ip
+		}
+	}
+	return host
+}
+
+// parseIP returns the canonical string form of s if it is a valid IP, else "".
+func parseIP(s string) string {
+	if s == "" {
+		return ""
+	}
+	if ip := net.ParseIP(s); ip != nil {
+		return ip.String()
+	}
+	return ""
+}

internal/middleware/auththrottle_test.go

@@ -0,0 +1,148 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// goodPassword is accepted by the test handler; anything else returns 400.
+const goodPassword = "correct"
+
+func throttleTestHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Query().Get("pw") == goodPassword {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		http.Error(w, "bad", http.StatusBadRequest)
+	})
+}
+
+func doReq(h http.Handler, ip, pw string) *httptest.ResponseRecorder {
+	r := httptest.NewRequest(http.MethodPost, "/auth?pw="+pw, nil)
+	r.RemoteAddr = "10.0.0.1:12345" // trusted local proxy peer, so X-Real-IP is honored.
+	r.Header.Set("X-Real-IP", ip)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, r)
+	return w
+}
+
+func TestAuthThrottle_LimitsFailuresPerIP(t *testing.T) {
+	h := NewAuthThrottle(3, time.Minute, nil).Middleware(throttleTestHandler())
+
+	// First 3 wrong attempts from an IP reach the handler and return its status.
+	for i := 0; i < 3; i++ {
+		require.Equal(t, http.StatusBadRequest, doReq(h, "1.1.1.1", "wrong").Code, "attempt %d", i)
+	}
+	// The 4th is rejected before the handler runs, with a Retry-After hint.
+	resp := doReq(h, "1.1.1.1", "wrong")
+	require.Equal(t, http.StatusTooManyRequests, resp.Code)
+	require.Equal(t, strconv.Itoa(60), resp.Header().Get("Retry-After"))
+
+	// Even a correct password from the throttled IP is rejected with 429, so the
+	// response does not reveal that the credentials were valid.
+	require.Equal(t, http.StatusTooManyRequests, doReq(h, "1.1.1.1", goodPassword).Code)
+}
+
+func TestAuthThrottle_DoesNotBlockOtherIPsOrSuccess(t *testing.T) {
+	h := NewAuthThrottle(3, time.Minute, nil).Middleware(throttleTestHandler())
+
+	// Exhaust the limit for the attacker's IP.
+	for i := 0; i < 5; i++ {
+		_ = doReq(h, "9.9.9.9", "wrong")
+	}
+	require.Equal(t, http.StatusTooManyRequests, doReq(h, "9.9.9.9", "wrong").Code)
+
+	// A legitimate admin on a different IP still logs in while the attack runs.
+	require.Equal(t, http.StatusOK, doReq(h, "2.2.2.2", goodPassword).Code)
+
+	// Success never accrues against the limit: many valid logins stay allowed.
+	for i := 0; i < 20; i++ {
+		require.Equal(t, http.StatusOK, doReq(h, "3.3.3.3", goodPassword).Code, "login %d", i)
+	}
+}
+
+func TestAuthThrottle_PublicPeerCannotSpoofHeader(t *testing.T) {
+	h := NewAuthThrottle(3, time.Minute, nil).Middleware(throttleTestHandler())
+	// A direct public client rotating X-Real-IP cannot evade the limit: the header
+	// is untrusted (peer is not a local proxy), so every attempt keys on the real
+	// socket peer and the IP is throttled after the limit regardless of the header.
+	req := func(spoofedIP string) int {
+		r := httptest.NewRequest(http.MethodPost, "/auth?pw=wrong", nil)
+		r.RemoteAddr = "203.0.113.5:9999" // public peer.
+		r.Header.Set("X-Real-IP", spoofedIP)
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, r)
+		return w.Code
+	}
+	require.Equal(t, http.StatusBadRequest, req("1.1.1.1"))
+	require.Equal(t, http.StatusBadRequest, req("2.2.2.2"))
+	require.Equal(t, http.StatusBadRequest, req("3.3.3.3"))
+	require.Equal(t, http.StatusTooManyRequests, req("4.4.4.4"))
+}
+
+func TestAuthThrottle_WindowReset(t *testing.T) {
+	h := NewAuthThrottle(2, 50*time.Millisecond, nil).Middleware(throttleTestHandler())
+
+	require.Equal(t, http.StatusBadRequest, doReq(h, "1.2.3.4", "wrong").Code)
+	require.Equal(t, http.StatusBadRequest, doReq(h, "1.2.3.4", "wrong").Code)
+	require.Equal(t, http.StatusTooManyRequests, doReq(h, "1.2.3.4", "wrong").Code)
+
+	// After the window elapses the count resets and the IP may try again.
+	time.Sleep(70 * time.Millisecond)
+	require.Equal(t, http.StatusBadRequest, doReq(h, "1.2.3.4", "wrong").Code)
+}
+
+func TestAuthThrottle_MapBounded(t *testing.T) {
+	tr := NewAuthThrottle(1, time.Minute, nil)
+	// Track an IP, then flood the map with unique addresses past its capacity.
+	tr.recordFailure("10.0.0.1")
+	for i := 0; i < authThrottleMapCap+100; i++ {
+		tr.recordFailure("10.9." + strconv.Itoa(i/256) + "." + strconv.Itoa(i%256))
+	}
+	// The already-tracked IP keeps counting even though the map is now full.
+	tr.recordFailure("10.0.0.1")
+
+	tr.mu.Lock()
+	size := len(tr.failures)
+	pretrackedCount := tr.failures["10.0.0.1"]
+	tr.mu.Unlock()
+	require.LessOrEqual(t, size, authThrottleMapCap, "map must stay bounded")
+	require.Equal(t, 2, pretrackedCount, "already-tracked IP keeps counting")
+}
+
+func TestClientIP(t *testing.T) {
+	newReq := func(realIP, xff, remote string) *http.Request {
+		r := httptest.NewRequest(http.MethodPost, "/", nil)
+		r.RemoteAddr = remote
+		if realIP != "" {
+			r.Header.Set("X-Real-IP", realIP)
+		}
+		if xff != "" {
+			r.Header.Set("X-Forwarded-For", xff)
+		}
+		return r
+	}
+	// Trusted local proxy peer (private / loopback): forwarded headers are used.
+	require.Equal(t, "5.5.5.5", clientIP(newReq("5.5.5.5", "1.1.1.1", "10.0.0.9:1")))
+	require.Equal(t, "1.1.1.1", clientIP(newReq("", "1.1.1.1, 2.2.2.2", "10.0.0.9:1")))
+	require.Equal(t, "8.8.8.8", clientIP(newReq("8.8.8.8", "", "127.0.0.1:1")))
+
+	// Direct public peer: forwarded headers are client-controlled, so ignored -
+	// the socket peer is used and a spoofed header cannot change the key.
+	require.Equal(t, "9.9.9.9", clientIP(newReq("", "", "9.9.9.9:12345")))
+	require.Equal(t, "9.9.9.9", clientIP(newReq("1.2.3.4", "1.2.3.4", "9.9.9.9:12345")))
+
+	// Behind a trusted proxy, a non-IP header value falls back to the peer, so an
+	// attacker cannot inflate map keys or fragment the keyspace with junk.
+	require.Equal(t, "10.0.0.9", clientIP(newReq(strings.Repeat("x", 5000), "", "10.0.0.9:1")))
+	require.Equal(t, "10.0.0.9", clientIP(newReq("", "not-an-ip", "10.0.0.9:1")))
+
+	require.Equal(t, "raw-addr", clientIP(newReq("", "", "raw-addr")))
+}