Ban the netblock of a client that breaks a rate limit, in memory (closes #18)

A request over a rate limit is refused with SWWAF_BAN_RESPONSE and bans
the client's netblock: an hour at first, three times the last ban when
broken again within a day of its end, permanent past seven days. The
ban ledger in internal/bans is checked after the static lists and
before the lookup, and the requests it refuses are not counted. A ban
resets the client's counters and carries notes holding the request
that broke the limit, as SPEC.md now says. At most SWWAF_MAX_BANS are
held. SWWAF_BAN_RESPONSE also answers SWWAF_DENY_NETS and the country
lists.

Judgement call: the six ban settings cannot be off.
Judgement call: a permanent ban's ban_expires is "permanent".

Model: opus-5-5

internal/config/config.go

@@ -9,6 +9,7 @@ import (
 	"log/slog"
 	"math"
 	"net"
+	"net/http"
 	"net/netip"
 	"net/url"
 	"slices"
@@ -67,6 +68,25 @@ type Config struct {
 	// capitals, as GeoJS gives them.
 	DeniedCountries             []string
 	ExclusivelyAllowedCountries []string
+	// BanResponse is the status a refused client is answered with, 403
+	// or 429, or 0 to close the connection without an answer
+	// (SWWAF_BAN_RESPONSE). It answers a banned client, a request that
+	// breaks a rate limit, SWWAF_DENY_NETS and the country lists.
+	BanResponse int
+	// LimitBanDuration is the ban for a first broken rate limit
+	// (SWWAF_LIMIT_BAN_DURATION). A limit broken again within
+	// LimitBanRepeatWindow after the last ban ended bans for three times
+	// as long as that ban (SWWAF_LIMIT_BAN_REPEAT_WINDOW), and a ban that
+	// would be longer than MaxBanDuration is permanent instead
+	// (SWWAF_MAX_BAN_DURATION). None of them can be off.
+	LimitBanDuration     time.Duration
+	LimitBanRepeatWindow time.Duration
+	MaxBanDuration       time.Duration
+	// MaxBans is the most bans held (SWWAF_MAX_BANS).
+	MaxBans int
+	// BanScopeV4Prefix is the length of the netblock around an IPv4
+	// client that a ban covers (SWWAF_BAN_SCOPE_V4_PREFIX).
+	BanScopeV4Prefix int
 
 	// settings are the values read, as given or by default, for the
 	// log line at start.
@@ -82,6 +102,7 @@ const (
 	kibibyte = 1 << 10
 	mebibyte = 1 << 20
 	gibibyte = 1 << 30
+	ipv4Bits = 32
 )
 
 var (
@@ -102,7 +123,14 @@ var (
 			"such as http://127.0.0.1:8081")
 	errNotCountry = errors.New(
 		"is not a two-letter country code such as de or kp")
-	errOnBothLists = errors.New("is in SWWAF_DENIED_COUNTRIES too")
+	errOnBothLists          = errors.New("is in SWWAF_DENIED_COUNTRIES too")
+	errNotDurationAboveZero = errors.New(
+		"is not a duration above zero, such as 1h or 7d")
+	errNotNumberAboveZero = errors.New(
+		"is not a whole number above zero, such as 5000")
+	errNotBanResponse = errors.New("is not 403, 429 or close")
+	errNotV4Prefix    = errors.New(
+		"is not the length of an IPv4 netblock, from 0 to 32, such as 24")
 )
 
 // FromEnvironment reads the settings with lookupEnv, normally
@@ -129,6 +157,12 @@ func FromEnvironment(lookupEnv func(string) (string, bool)) (*Config, error) {
 		DeniedCountries:         env.countries("SWWAF_DENIED_COUNTRIES", ""),
 		ExclusivelyAllowedCountries: env.countries(
 			"SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES", ""),
+		BanResponse:          env.banResponse("SWWAF_BAN_RESPONSE", "403"),
+		LimitBanDuration:     env.durationNotOff("SWWAF_LIMIT_BAN_DURATION", "1h"),
+		LimitBanRepeatWindow: env.durationNotOff("SWWAF_LIMIT_BAN_REPEAT_WINDOW", "24h"),
+		MaxBanDuration:       env.durationNotOff("SWWAF_MAX_BAN_DURATION", "7d"),
+		MaxBans:              env.numberNotOff("SWWAF_MAX_BANS", "5000"),
+		BanScopeV4Prefix:     env.v4Prefix("SWWAF_BAN_SCOPE_V4_PREFIX", "32"),
 	}
 
 	for _, country := range cfg.ExclusivelyAllowedCountries {
@@ -241,6 +275,40 @@ func (e *environment) countries(name, defaultValue string) []string {
 	return countries
 }
 
+// durationNotOff reads a setting that is a duration and, unlike a
+// timeout, cannot be off.
+func (e *environment) durationNotOff(name, defaultValue string) time.Duration {
+	duration, err := parseDurationNotOff(e.value(name, defaultValue))
+	e.check(name, err)
+
+	return duration
+}
+
+// numberNotOff reads a setting that is a whole number above zero, which
+// cannot be off.
+func (e *environment) numberNotOff(name, defaultValue string) int {
+	number, err := parseNumberNotOff(e.value(name, defaultValue))
+	e.check(name, err)
+
+	return number
+}
+
+// banResponse reads a setting that is how a refused client is answered.
+func (e *environment) banResponse(name, defaultValue string) int {
+	status, err := parseBanResponse(e.value(name, defaultValue))
+	e.check(name, err)
+
+	return status
+}
+
+// v4Prefix reads a setting that is the length of an IPv4 netblock.
+func (e *environment) v4Prefix(name, defaultValue string) int {
+	length, err := parseV4Prefix(e.value(name, defaultValue))
+	e.check(name, err)
+
+	return length
+}
+
 // parseDuration reads a duration in Go's syntax, such as 90s or 15m, a
 // whole number of days such as 7d, or off.
 func parseDuration(value string) (time.Duration, error) {
@@ -329,6 +397,52 @@ func parseCount(value string) (int64, error) {
 	return n, nil
 }
 
+// parseDurationNotOff reads a duration above zero, as parseDuration does,
+// but not off.
+func parseDurationNotOff(value string) (time.Duration, error) {
+	duration, err := parseDuration(value)
+	if err != nil || duration == 0 {
+		return 0, fmt.Errorf("%q %w", value, errNotDurationAboveZero)
+	}
+
+	return duration, nil
+}
+
+// parseNumberNotOff reads a whole number above zero.
+func parseNumberNotOff(value string) (int, error) {
+	n, err := strconv.Atoi(value)
+	if err != nil || n <= 0 {
+		return 0, fmt.Errorf("%q %w", value, errNotNumberAboveZero)
+	}
+
+	return n, nil
+}
+
+// parseBanResponse reads how a refused client is answered: 403, 429, or
+// close, which is 0.
+func parseBanResponse(value string) (int, error) {
+	switch value {
+	case "403":
+		return http.StatusForbidden, nil
+	case "429":
+		return http.StatusTooManyRequests, nil
+	case "close":
+		return 0, nil
+	default:
+		return 0, fmt.Errorf("%q %w", value, errNotBanResponse)
+	}
+}
+
+// parseV4Prefix reads the length of an IPv4 netblock, from 0 to 32.
+func parseV4Prefix(value string) (int, error) {
+	n, err := strconv.Atoi(value)
+	if err != nil || n < 0 || n > ipv4Bits {
+		return 0, fmt.Errorf("%q %w", value, errNotV4Prefix)
+	}
+
+	return n, nil
+}
+
 // parseList splits a comma-separated list and trims the spaces around
 // each item. An empty value is an empty list.
 func parseList(value string) ([]string, error) {

internal/config/config_test.go

@@ -33,6 +33,12 @@ const (
 	rateLimitPerDay         = "SWWAF_RATE_LIMIT_PER_DAY"
 	deniedCountries         = "SWWAF_DENIED_COUNTRIES"
 	allowedCountries        = "SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES"
+	banResponse             = "SWWAF_BAN_RESPONSE"
+	limitBanDuration        = "SWWAF_LIMIT_BAN_DURATION"
+	limitBanRepeatWindow    = "SWWAF_LIMIT_BAN_REPEAT_WINDOW"
+	maxBanDuration          = "SWWAF_MAX_BAN_DURATION"
+	maxBans                 = "SWWAF_MAX_BANS"
+	banScopeV4Prefix        = "SWWAF_BAN_SCOPE_V4_PREFIX"
 )
 
 // off switches a timeout, a size limit or a rate limit off.
@@ -76,6 +82,12 @@ func TestDefaults(t *testing.T) {
 		RateLimitPerMinute:      1000,
 		RateLimitPerHour:        10000,
 		RateLimitPerDay:         50000,
+		BanResponse:             403,
+		LimitBanDuration:        time.Hour,
+		LimitBanRepeatWindow:    24 * time.Hour,
+		MaxBanDuration:          7 * 24 * time.Hour,
+		MaxBans:                 5000,
+		BanScopeV4Prefix:        32,
 	})
 
 	if cfg.UpstreamURL.String() != "http://127.0.0.1:8081" {
@@ -112,6 +124,12 @@ func TestValuesAsSet(t *testing.T) {
 		rateLimitPerDay:         "6000",
 		deniedCountries:         "cn, RU,kp,Xk",
 		allowedCountries:        "de",
+		banResponse:             "429",
+		limitBanDuration:        "15m",
+		limitBanRepeatWindow:    "2d",
+		maxBanDuration:          "30d",
+		maxBans:                 "100",
+		banScopeV4Prefix:        "24",
 	})
 
 	wantSettings(t, cfg, config.Config{
@@ -125,6 +143,12 @@ func TestValuesAsSet(t *testing.T) {
 		RateLimitPerMinute:      60,
 		RateLimitPerHour:        600,
 		RateLimitPerDay:         6000,
+		BanResponse:             429,
+		LimitBanDuration:        15 * time.Minute,
+		LimitBanRepeatWindow:    48 * time.Hour,
+		MaxBanDuration:          30 * 24 * time.Hour,
+		MaxBans:                 100,
+		BanScopeV4Prefix:        24,
 	})
 
 	if cfg.UpstreamURL.String() != "https://app.internal:8443/" {
@@ -188,6 +212,15 @@ func TestRateLimitsOff(t *testing.T) {
 	}
 }
 
+func TestBanResponseCloseIsZero(t *testing.T) {
+	t.Parallel()
+
+	cfg := fromEnvironment(t, environment{banResponse: "close"})
+	if cfg.BanResponse != 0 {
+		t.Errorf("close read as %d, want 0", cfg.BanResponse)
+	}
+}
+
 func TestTrustedProxiesSetButEmptyTrustNothing(t *testing.T) {
 	t.Parallel()
 
@@ -250,6 +283,12 @@ func TestInvalidValueStopsTheStart(t *testing.T) {
 		{allowedCountries, "uk"},
 		{allowedCountries, "zz"},
 		{allowedCountries, "de,germany"},
+		{banResponse, "404"}, {banResponse, "drop"}, {banResponse, ""},
+		{limitBanDuration, off}, {limitBanDuration, "0s"}, {limitBanDuration, "1"},
+		{limitBanRepeatWindow, off}, {limitBanRepeatWindow, "-1h"},
+		{maxBanDuration, off}, {maxBanDuration, "1w"},
+		{maxBans, off}, {maxBans, "0"}, {maxBans, "5K"},
+		{banScopeV4Prefix, "33"}, {banScopeV4Prefix, "-1"}, {banScopeV4Prefix, "/24"},
 	} {
 		t.Run(tc.name+"="+tc.value, func(t *testing.T) {
 			t.Parallel()
@@ -302,6 +341,12 @@ func TestLogsEachSettingWithItsValue(t *testing.T) {
 		rateLimitPerDay:         "50000",
 		deniedCountries:         "",
 		allowedCountries:        "",
+		banResponse:             "403",
+		limitBanDuration:        "1h",
+		limitBanRepeatWindow:    "24h",
+		maxBanDuration:          "7d",
+		maxBans:                 "5000",
+		banScopeV4Prefix:        "32",
 	}
 	if !maps.Equal(line.Settings, want) {
 		t.Errorf("logged settings\n%v\nwant\n%v", line.Settings, want)
@@ -324,6 +369,22 @@ func wantSettings(t *testing.T, got *config.Config, want config.Config) {
 		got.RateLimitPerDay != want.RateLimitPerDay {
 		t.Errorf("settings\n%+v\nwant\n%+v", got, want)
 	}
+
+	wantBanSettings(t, got, want)
+}
+
+// wantBanSettings checks the settings for bans.
+func wantBanSettings(t *testing.T, got *config.Config, want config.Config) {
+	t.Helper()
+
+	if got.BanResponse != want.BanResponse ||
+		got.LimitBanDuration != want.LimitBanDuration ||
+		got.LimitBanRepeatWindow != want.LimitBanRepeatWindow ||
+		got.MaxBanDuration != want.MaxBanDuration ||
+		got.MaxBans != want.MaxBans ||
+		got.BanScopeV4Prefix != want.BanScopeV4Prefix {
+		t.Errorf("ban settings\n%+v\nwant\n%+v", got, want)
+	}
 }
 
 // wantNetblocks checks a list of netblocks.