Merge branch 'release-2.26.x'

server/ban_test.go

@@ -0,0 +1,55 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"heckel.io/ntfy/v2/ban"
+)
+
+// TestServer_BanFeed_WritesOffenderToFile is the end-to-end wiring test: a rejected request flows
+// through s.handle -> the error responder -> s.ban.Record, and once the offender's prefix
+// breaches, its ban line lands in the ban file (flushed on Close).
+func TestServer_BanFeed_WritesOffenderToFile(t *testing.T) {
+	banFile := filepath.Join(t.TempDir(), "ban.log")
+	conf := newTestConfig(t, "")
+	conf.BanFile = banFile
+	conf.BanWindow = time.Minute
+	conf.BanThreshold = 1                 // capacity 1: the 2nd rejection breaches
+	conf.BanWeights = ban.Weights{"*": 1} // any 4xx counts one strike
+	s := newTestServer(t, conf)
+	require.NotNil(t, s.ban)
+
+	// A delayed message with caching disabled is a deterministic 400 (errHTTPBadRequestDelayNoCache).
+	// request() sends from RemoteAddr 9.9.9.9.
+	reject := map[string]string{"Cache": "no", "In": "30 min"}
+	for i := 0; i < 3; i++ {
+		response := request(t, s, "PUT", "/mytopic", "", reject)
+		require.Equal(t, 400, response.Code)
+	}
+
+	// Writes are async; Close flushes the buffer. The offender's prefix must be in the feed exactly
+	// once (throttled to one line per window).
+	s.ban.Close()
+	data, err := os.ReadFile(banFile)
+	require.NoError(t, err)
+	lines := strings.Split(strings.TrimRight(string(data), "\n"), "\n")
+	require.Len(t, lines, 1)
+	require.Contains(t, lines[0], " 9.9.9.9 9.9.9.9/32 400 ") // <ip> <prefix> <http-code> <ntfy-code>
+}
+
+// TestServer_BanFeed_DisabledByDefault verifies the feature is off with no ban file: s.ban is
+// nil and the error path skips it (guarded), so a rejected request must not panic.
+func TestServer_BanFeed_DisabledByDefault(t *testing.T) {
+	conf := newTestConfig(t, "") // no BanFile
+	s := newTestServer(t, conf)
+	require.Nil(t, s.ban)
+
+	reject := map[string]string{"Cache": "no", "In": "30 min"}
+	response := request(t, s, "PUT", "/mytopic", "", reject) // guarded callsite, no Record
+	require.Equal(t, 400, response.Code)
+}

server/config.go

@@ -10,6 +10,7 @@ import (
 	"text/template"
 	"time"
 
+	"heckel.io/ntfy/v2/ban"
 	"heckel.io/ntfy/v2/user"
 )
 
@@ -42,6 +43,24 @@ const (
 	DefaultWebPushExpiryDuration        = 60 * 24 * time.Hour
 )
 
+// Defines default abuse ban-feed settings (see BanFile, BanWindow, BanThreshold, BanWeights)
+const (
+	DefaultBanWindow    = 10 * time.Minute
+	DefaultBanThreshold = 100 // Weighted strikes per BanWindow before a prefix is banned
+)
+
+// DefaultBanWeights is the ban-feed's default per-code strike weights: the auth-failure flood bans fast,
+// and everything else defaults to weight 1 (no "*" rule needed; see BanWeights.WeightFor).
+var DefaultBanWeights = []string{
+	banWeight(errHTTPTooManyRequestsLimitAuthFailure, 10), // brute-force auth flood -> ban fast
+}
+
+// banWeight formats a "CODE:WEIGHT" ban-feed default from an ntfy error, so the codes stay in sync with
+// the errHTTP definitions instead of being duplicated as string literals.
+func banWeight(err *errHTTP, weight int) string {
+	return fmt.Sprintf("%d:%d", err.Code, weight)
+}
+
 // Defines all global and per-visitor limits
 // - message size limit: the max number of bytes for a message
 // - total topic limit: max number of topics overall
@@ -196,9 +215,13 @@ type Config struct {
 	WebPushStartupQueries                string
 	WebPushExpiryDuration                time.Duration
 	WebPushExpiryWarningDuration         time.Duration
-	BuildVersion                         string // Injected by App
-	BuildDate                            string // Injected by App
-	BuildCommit                          string // Injected by App
+	BanFile                              string        // Abuse ban-feed: file that fail2ban tails; empty string disables the feature
+	BanWindow                            time.Duration // Abuse ban-feed: rolling window over which weighted strikes are counted
+	BanThreshold                         int           // Abuse ban-feed: weighted strikes per window before a prefix is banned
+	BanWeights                           ban.Weights   // Abuse ban-feed: code matcher -> strike weight (see ban.ParseWeights, ban.Weights.WeightFor)
+	BuildVersion                         string        // Injected by App
+	BuildDate                            string        // Injected by App
+	BuildCommit                          string        // Injected by App
 }
 
 // NewConfig instantiates a default new server config
@@ -299,6 +322,10 @@ func NewConfig() *Config {
 		WebPushEmailAddress:                  "",
 		WebPushExpiryDuration:                DefaultWebPushExpiryDuration,
 		WebPushExpiryWarningDuration:         DefaultWebPushExpiryWarningDuration,
+		BanFile:                              "",
+		BanWindow:                            DefaultBanWindow,
+		BanThreshold:                         DefaultBanThreshold,
+		BanWeights:                           nil,
 		BuildVersion:                         "",
 		BuildDate:                            "",
 		BuildCommit:                          "",

server/server.go

@@ -31,6 +31,7 @@ import (
 	"golang.org/x/sync/errgroup"
 	"heckel.io/ntfy/v2/action"
 	"heckel.io/ntfy/v2/attachment"
+	"heckel.io/ntfy/v2/ban"
 	"heckel.io/ntfy/v2/db"
 	"heckel.io/ntfy/v2/db/pg"
 	"heckel.io/ntfy/v2/log"
@@ -59,6 +60,7 @@ type Server struct {
 	mailer            mail.Sender
 	topics            map[string]*topic
 	visitors          map[string]*visitor // ip:<ip> or user:<user>
+	ban               *ban.Service        // Abuse ban-feed; nil when the feature is disabled (no ban file)
 	firebaseClient    *firebaseClient
 	twilio            *twilio.Client
 	messages          int64                               // Total number of messages (persisted if messageCache enabled)
@@ -303,6 +305,17 @@ func New(conf *Config) (*Server, error) {
 		}
 		firebaseClient = newFirebaseClient(sender, auther)
 	}
+	var banner *ban.Service
+	if conf.BanFile != "" {
+		banner = ban.NewService(&ban.Config{
+			File:           conf.BanFile,
+			Window:         conf.BanWindow,
+			Threshold:      conf.BanThreshold,
+			Weights:        conf.BanWeights,
+			PrefixBitsIPv4: conf.VisitorPrefixBitsIPv4,
+			PrefixBitsIPv6: conf.VisitorPrefixBitsIPv6,
+		})
+	}
 	s := &Server{
 		config:          conf,
 		db:              pool,
@@ -312,6 +325,7 @@ func New(conf *Config) (*Server, error) {
 		firebaseClient:  firebaseClient,
 		twilio:          twilioClient,
 		mailer:          sender,
+		ban:             banner,
 		topics:          topics,
 		userManager:     userManager,
 		messages:        messages,
@@ -465,6 +479,9 @@ func (s *Server) Stop() {
 		s.attachment.Close()
 	}
 	s.closeDatabases()
+	if s.ban != nil {
+		s.ban.Close()
+	}
 	if s.closeChan != nil {
 		close(s.closeChan)
 	}
@@ -487,7 +504,7 @@ func (s *Server) closeDatabases() {
 
 // handle is the main entry point for all HTTP requests
 func (s *Server) handle(w http.ResponseWriter, r *http.Request) {
-	v, err := s.maybeAuthenticate(r) // Note: Always returns v, even when error is returned
+	r, v, err := s.maybeAuthenticate(r) // Note: Always returns v (and r, with the client IP in its context), even on error
 	if err != nil {
 		s.handleError(w, r, v, err)
 		return
@@ -549,6 +566,11 @@ func (s *Server) handleError(w http.ResponseWriter, r *http.Request, v *visitor,
 	w.Header().Set("Access-Control-Allow-Origin", s.config.AccessControlAllowOrigin) // CORS, allow cross-origin requests
 	w.WriteHeader(httpErr.HTTPCode)
 	io.WriteString(w, httpErr.JSON()+"\n")
+	if s.ban != nil {
+		if ip, err := fromContext[netip.Addr](r, contextVisitorIP); err == nil {
+			s.ban.Record(ip, httpErr.HTTPCode, httpErr.Code)
+		}
+	}
 }
 
 func (s *Server) handleInternal(w http.ResponseWriter, r *http.Request, v *visitor) error {

server/server.yml

@@ -370,6 +370,39 @@
 # visitor-topic-creation-limit-burst: 100
 # visitor-topic-creation-limit-replenish: "1m"
 
+# Abuse ban-feed: Count HTTP response statuses per visitor and append abusive IPs to a file that
+# fail2ban (or similar) can tail and ban on sight. This captures ntfy-layer rejections (e.g. ACL
+# 403s and ntfy's own 429s), so fail2ban does not have to regex-parse the full access log.
+# - ban-file is the file abusive IPs are appended to; leave empty to disable the feature. Its
+#   directory must exist and be writable by ntfy. Rotate it (e.g. logrotate, copytruncate) so it
+#   cannot grow unbounded.
+# - ban-window is the rolling window over which weighted strikes are counted, per visitor.
+# - ban-threshold is the number of weighted strikes per window before a visitor is banned. Each
+#   visitor has ONE strike budget; rejections draw it down, so there is no way to game it by mixing
+#   codes.
+# - ban-weights assigns a strike weight to a matcher KEY (KEY:WEIGHT). A KEY is an exact ntfy code
+#   ("42909"), a prefix family ("429*"), a bare HTTP status ("403", shorthand for "403*"), or "*".
+#   Longest match wins. A weight of 0 exempts a code (never contributes to a ban), so the legit quota
+#   429s can be carved out from a "*" catch-all. Heavier weights ban faster (auth-failure floods).
+#
+# Each appended line has the exact format
+#   "<RFC3339-UTC-timestamp> <ip> <prefix> <http-code> <ntfy-code>", for example:
+#   2026-07-17T20:56:32Z 1.2.3.4 1.2.3.4/32 429 42901
+#   2026-07-17T20:56:32Z 2001:db8::abcd 2001:db8::/64 429 42909
+# <prefix> is <ip> masked to the rate-limiting prefix (visitor-prefix-bits-ipv4/ipv6); that is the
+# unit a fail2ban jail should ban, so a whole IPv6 subnet is banned as one.
+#
+# ban-file: "/var/log/ntfy-ban.log"
+# ban-window: "1m"
+# ban-threshold: 100
+# ban-weights:
+#   - "42909:10"   # auth-failure flood: bans in ~10
+#   - "42908:0"    # daily message quota reached -> legit, never counts
+#   - "42903:0"    # subscription limit -> legit
+#   - "42905:0"    # daily bandwidth reached -> legit
+#   - "42910:0"    # daily phone call quota reached -> legit
+#   - "*:1"        # everything else 4xx/5xx
+
 # Rate limiting: IPv4/IPv6 address prefix bits used for rate limiting
 # - visitor-prefix-bits-ipv4: number of bits of the IPv4 address to use for rate limiting (default: 32, full address)
 # - visitor-prefix-bits-ipv6: number of bits of the IPv6 address to use for rate limiting (default: 64, /64 subnet)

server/server_auth.go

@@ -21,31 +21,35 @@ import (
 //
 // This function will ALWAYS return a visitor, even if an error occurs (e.g. unauthorized), so
 // that subsequent logging calls still have a visitor context.
-func (s *Server) maybeAuthenticate(r *http.Request) (*visitor, error) {
+func (s *Server) maybeAuthenticate(r *http.Request) (*http.Request, *visitor, error) {
 	// Read the "Authorization" header value and exit out early if it's not set
 	ip := extractIPAddress(r, s.config.BehindProxy, s.config.ProxyForwardedHeader, s.config.ProxyTrustedPrefixes)
+	// Stash the extracted client IP in the request context so downstream code (the abuse ban-feed in
+	// handleError) can reuse it without re-parsing headers, and so an account-keyed (tier'd) visitor --
+	// whose shared visitor object has a stale v.ip -- is still attributed to the actual request IP.
+	r = withContext(r, map[contextKey]any{contextVisitorIP: ip})
 	vip := s.visitor(ip, nil)
 	if s.userManager == nil {
-		return vip, nil
+		return r, vip, nil
 	}
 	header, err := readAuthHeader(r)
 	if err != nil {
-		return vip, err
+		return r, vip, err
 	} else if !supportedAuthHeader(header) {
-		return vip, nil
+		return r, vip, nil
 	}
 	// If we're trying to auth, check the rate limiter first
 	if !vip.AuthAllowed() {
-		return vip, errHTTPTooManyRequestsLimitAuthFailure // Always return visitor, even when error occurs!
+		return r, vip, errHTTPTooManyRequestsLimitAuthFailure // Always return visitor, even when error occurs!
 	}
 	u, err := s.authenticate(r, header)
 	if err != nil {
 		vip.AuthFailed()
 		logr(r).Err(err).Debug("Authentication failed")
-		return vip, errHTTPUnauthorized // Always return visitor, even when error occurs!
+		return r, vip, errHTTPUnauthorized // Always return visitor, even when error occurs!
 	}
 	// Authentication with user was successful
-	return s.visitor(ip, u), nil
+	return r, s.visitor(ip, u), nil
 }
 
 // authenticate a user based on basic auth username/password (Authorization: Basic ...), or token auth (Authorization: Bearer ...).

server/server_middleware.go

@@ -13,6 +13,7 @@ const (
 	contextRateVisitor contextKey = iota + 2586
 	contextTopic
 	contextMatrixPushKey
+	contextVisitorIP // Client IP extracted in maybeAuthenticate; reused by the abuse ban-feed (see ban.Service.Record)
 )
 
 func (s *Server) limitRequests(next handleFunc) handleFunc {

server/server_test.go

@@ -2889,7 +2889,7 @@ func TestServer_Visitor_XForwardedFor_None(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "  ") // Spaces, not empty!
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "8.9.10.11", v.ip.String())
 	})
@@ -2903,7 +2903,7 @@ func TestServer_Visitor_XForwardedFor_Single(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "1.1.1.1")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "1.1.1.1", v.ip.String())
 	})
@@ -2917,7 +2917,7 @@ func TestServer_Visitor_XForwardedFor_Multiple(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Forwarded-For", "1.2.3.4 , 2.4.4.2,234.5.2.1 ")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "234.5.2.1", v.ip.String())
 	})
@@ -2932,7 +2932,7 @@ func TestServer_Visitor_Custom_ClientIP_Header(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("X-Client-IP", "1.2.3.4")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "1.2.3.4", v.ip.String())
 	})
@@ -2947,7 +2947,7 @@ func TestServer_Visitor_Custom_ClientIP_Header_IPv6(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "[2001:db8:9999::1]:1234"
 		r.Header.Set("X-Client-IP", "2001:db8:7777::1")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "2001:db8:7777::1", v.ip.String())
 	})
@@ -2963,7 +2963,7 @@ func TestServer_Visitor_Custom_Forwarded_Header(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "8.9.10.11:1234"
 		r.Header.Set("Forwarded", " for=5.6.7.8, by=example.com;for=1.2.3.4")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "5.6.7.8", v.ip.String())
 	})
@@ -2979,7 +2979,7 @@ func TestServer_Visitor_Custom_Forwarded_Header_IPv6(t *testing.T) {
 		r, _ := http.NewRequest("GET", "/bla", nil)
 		r.RemoteAddr = "[2001:db8:2222::1]:1234"
 		r.Header.Set("Forwarded", " for=[2001:db8:1111::1], by=example.com;for=[2001:db8:3333::1]")
-		v, err := s.maybeAuthenticate(r)
+		_, v, err := s.maybeAuthenticate(r)
 		require.Nil(t, err)
 		require.Equal(t, "2001:db8:3333::1", v.ip.String())
 	})
@@ -5218,3 +5218,46 @@ func TestServer_Publish_InvalidUTF8WithFirebase(t *testing.T) {
 	require.Equal(t, "\uFFFDclipse", sender.Messages()[0].Data["title"])
 	require.Equal(t, "probl\uFFFDme", sender.Messages()[0].Data["tags"])
 }
+
+func TestServer_BanFeed_RateLimitedIPBanned(t *testing.T) {
+	// Real requests: exhaust the visitor request limit so ntfy returns 429s, and confirm the
+	// client IP is written to the ban file after it breaches the per-status ban limit.
+	banFile := filepath.Join(t.TempDir(), "ntfy-ban.log")
+	c := newTestConfig(t, "")
+	c.BanFile = banFile
+	c.BanWindow = time.Minute
+	c.BanThreshold = 2                    // Ban after the weighted budget of 2 is exhausted
+	c.BanWeights = map[string]int{"*": 1} // Every rejection costs 1 strike
+	c.VisitorRequestLimitBurst = 2        // 429 quickly
+	s := newTestServer(t, c)
+	got429 := 0
+	for i := 0; i < 10; i++ {
+		rr := request(t, s, "PUT", "/mytopic", "x", nil)
+		if rr.Code == 429 {
+			got429++
+		}
+	}
+	require.Greater(t, got429, 2)
+	s.ban.Close() // Writes are async (runWriteLoop); Close flushes the buffer before we read
+	data, err := os.ReadFile(banFile)
+	require.NoError(t, err)
+	require.Contains(t, string(data), "9.9.9.9 9.9.9.9/32 429 42901") // <ip> <prefix> <http> <ntfy-code>
+}
+
+func TestServer_BanFeed_SuccessfulRequestsNotBanned(t *testing.T) {
+	// Real requests that all succeed (200) must never trigger a ban, even with a low "*" fallback.
+	banFile := filepath.Join(t.TempDir(), "ntfy-ban.log")
+	c := newTestConfig(t, "")
+	c.BanFile = banFile
+	c.BanWindow = time.Minute
+	c.BanThreshold = 3                    // Low threshold that would catch 200s if 2xx were not skipped
+	c.BanWeights = map[string]int{"*": 1} // Every rejection costs 1 strike
+	c.VisitorRequestLimitBurst = 100      // Stay under the request limit so every request is 200
+	s := newTestServer(t, c)
+	for i := 0; i < 10; i++ {
+		rr := request(t, s, "PUT", "/mytopic", fmt.Sprintf("m%d", i), nil)
+		require.Equal(t, 200, rr.Code)
+	}
+	s.ban.Close() // Flush any buffered bans (there should be none) before asserting no file
+	require.NoFileExists(t, banFile)
+}