Rule files, and bans for a clear sign of attack (closes #24)

Every *.rules file in SWWAF_RULES_DIR is read at start and again when
one changes, and each request is checked against the rules after the
rate limits: log notes a match, block refuses with 403, ban refuses and
bans the netblock for SWWAF_ATTACK_BAN_DURATION, made permanent by its
next request or its next clear sign of attack. bans.json gains each
ban's cause, the request log rule_ids and rule_blocked, the metrics
rule matches and rules loaded. The image ships 00-default.rules.

Judgement call: a header sent twice is matched with its values joined
by ", ".
Judgement call: SWWAF_MAX_BAN_DURATION does not cap a ban for an attack.
Not in this unit: offences for rule matches, with the error burst.

Model: opus-5-5

internal/bans/bans.go

@@ -1,7 +1,8 @@
 // Package bans is the ban ledger: the bans smallwebwaf makes on the
-// netblocks of clients that break a rate limit, with their notes, as the
-// "Bans" section of SPEC.md describes. The bans are kept in memory, and
-// written to bans.json and read from it by the state package.
+// netblocks of clients that break a rate limit or show a clear sign of
+// attack, with their notes, as the "Bans" section of SPEC.md describes.
+// The bans are kept in memory, and written to bans.json and read from it
+// by the state package.
 package bans
 
 import (
@@ -14,6 +15,15 @@ import (
 	"github.com/hashicorp/golang-lru/v2/simplelru"
 )
 
+// The causes of the bans smallwebwaf makes. A ban an admin adds to
+// bans.json may have no cause.
+const (
+	// CauseLimit is a ban for a broken limit.
+	CauseLimit = "limit"
+	// CauseAttack is a ban for a clear sign of attack.
+	CauseAttack = "attack"
+)
+
 // repeatFactor is how many times as long as the netblock's last ban a ban
 // for a limit broken again within the repeat window lasts.
 const repeatFactor = 3
@@ -21,32 +31,37 @@ const repeatFactor = 3
 // maxTextBytes is how much of each text in a ban's notes is kept.
 const maxTextBytes = 256
 
-// Rules are how long a ban for a broken limit lasts, and how many bans
-// are held.
+// Rules are how long a ban lasts, and how many bans are held.
 type Rules struct {
-	// LimitBanDuration is how long a first ban lasts.
+	// LimitBanDuration is how long a first ban for a broken limit lasts.
 	LimitBanDuration time.Duration
 	// LimitBanRepeatWindow is how soon after the end of the netblock's
-	// ban that ended last a broken limit counts as a repeat, which bans
-	// for repeatFactor times as long as that ban.
+	// ban that ended last, other than one for a clear sign of attack, a
+	// broken limit counts as a repeat, which bans for repeatFactor times as
+	// long as that ban.
 	LimitBanRepeatWindow time.Duration
-	// MaxBanDuration is the longest ban; a ban that would be longer is
-	// permanent instead.
+	// MaxBanDuration is the longest ban for a broken limit; one that would
+	// be longer is permanent instead.
 	MaxBanDuration time.Duration
+	// AttackBanDuration is how long a first ban for a clear sign of attack
+	// lasts.
+	AttackBanDuration time.Duration
 	// MaxBans is the most bans held, at least one. Past it, the earliest
 	// ban of the netblock that has gone longest without a request is
 	// dropped.
 	MaxBans int
 }
 
-// Ban is a ban on a netblock for a broken limit, the only kind of ban
-// smallwebwaf makes so far.
+// Ban is a ban on a netblock.
 type Ban struct {
 	Netblock netip.Prefix
 	Start    time.Time
 	// Expires is when the ban ends, zero for a permanent ban.
 	Expires time.Time
-	Notes   Notes
+	// Cause is CauseLimit or CauseAttack, or "" for a ban an admin added
+	// without one.
+	Cause string
+	Notes Notes
 }
 
 // Permanent reports whether the ban never runs out.
@@ -66,15 +81,20 @@ func (b Ban) ActiveAt(now time.Time) bool {
 type Notes struct {
 	// Country is the client's country, when it was looked up.
 	Country string `json:"country"`
-	// Limit, Window and Count are the limit that was broken, its window,
-	// "minute", "hour" or "day", and the count reached: the client's
-	// requests in the window, the one that broke the limit included.
-	// These are the requests that counted toward the ban, and the window
-	// is the time over which they came.
-	Limit  int64   `json:"limit"`
-	Window string  `json:"window"`
-	Count  float64 `json:"count"`
-	// Request is the request that broke the limit.
+	// Limit, Window and Count are, for a ban for a broken limit, the limit
+	// that was broken, its window, "minute", "hour" or "day", and the
+	// count reached: the client's requests in the window, the one that
+	// broke the limit included. These are the requests that counted
+	// toward the ban, and the window is the time over which they came.
+	Limit  int64   `json:"limit,omitempty"`
+	Window string  `json:"window,omitempty"`
+	Count  float64 `json:"count,omitempty"`
+	// RuleID and Target are, for a ban for a clear sign of attack, the id
+	// of the rule file rule that matched, and its target.
+	RuleID string `json:"rule_id,omitempty"`
+	Target string `json:"target,omitempty"`
+	// Request is the request that broke the limit, or that was the clear
+	// sign of attack.
 	Request Request `json:"request"`
 	// Requests is how many requests the netblock has sent since it was
 	// first seen, and Refused how many of them the ban has refused so
@@ -112,8 +132,8 @@ type Ledger struct {
 	netblocks *simplelru.LRU[netip.Prefix, *[]Ban]
 	// held is how many bans netblocks holds, at most rules.MaxBans.
 	held int
-	// made is how many bans BanForLimit has made since the start.
-	made int
+	// made is how many bans the ledger has made since the start, by cause.
+	made map[string]int
 	// v4Lengths and v6Lengths are the lengths of the IPv4 and IPv6
 	// netblocks that have been banned. Check looks for a ban at each of
 	// them, so that a ban read from bans.json refuses every client in its
@@ -135,18 +155,21 @@ func New(rules Rules) *Ledger {
 		rules:     rules,
 		changed:   make(chan struct{}, 1),
 		netblocks: netblocks,
+		made:      map[string]int{},
 	}
 }
 
-// Changed receives a value after a ban is made, so that bans.json can be
-// written. Several bans made before it is read leave one value.
+// Changed receives a value after a ban is made or made permanent, so that
+// bans.json can be written. Several changes before it is read leave one
+// value.
 func (l *Ledger) Changed() <-chan struct{} {
 	return l.changed
 }
 
 // Check is called for a request from client, at now. It reports whether
 // a ban on a netblock client is in is active, and returns that ban, with
-// the request counted among those it refused.
+// the request counted among those it refused. A ban for a clear sign of
+// attack is made permanent by the request: the netblock is malicious.
 func (l *Ledger) Check(client netip.Addr, now time.Time) (Ban, bool) {
 	l.mu.Lock()
 	defer l.mu.Unlock()
@@ -159,6 +182,12 @@ func (l *Ledger) Check(client netip.Addr, now time.Time) (Ban, bool) {
 	ban.Notes.Requests++
 	ban.Notes.Refused++
 
+	if ban.Cause == CauseAttack && !ban.Permanent() {
+		ban.Expires = time.Time{}
+
+		l.markChanged()
+	}
+
 	return *ban, true
 }
 
@@ -192,54 +221,22 @@ func activeBan(bans []Ban, now time.Time) *Ban {
 
 // BanForLimit bans netblock at now for a broken limit, with notes, and
 // returns the ban. A first ban lasts LimitBanDuration. A ban made within
-// LimitBanRepeatWindow after the netblock's ban that ended last lasts
-// repeatFactor times as long as that one. A ban that would be longer
-// than MaxBanDuration is permanent instead. If a ban on netblock is still
-// active, as when two of its requests break a limit at once, that ban is
-// returned and no other is made. The ledger fills in the notes' Refused
-// and EarlierBans itself.
+// LimitBanRepeatWindow after the netblock's ban that ended last, other
+// than one for a clear sign of attack, lasts repeatFactor times as long as
+// that one. A ban that would be longer than MaxBanDuration is permanent
+// instead. If a ban on netblock is still active, as when two of its
+// requests break a limit at once, that ban is returned and no other is
+// made. The ledger fills in the notes' Refused and EarlierBans itself.
 func (l *Ledger) BanForLimit(netblock netip.Prefix, now time.Time, notes Notes) Ban {
-	l.mu.Lock()
-	defer l.mu.Unlock()
+	return l.ban(netblock, now, CauseLimit, notes)
+}
 
-	var last *Ban
-
-	bans, found := l.netblocks.Get(netblock)
-	if found {
-		active := activeBan(*bans, now)
-		if active != nil {
-			return *active
-		}
-
-		// No ban is active, so each has an end. A ban an admin adds to
-		// bans.json can start after another and end before it, so the
-		// ban that ended last is looked for among them all.
-		ended := slices.MaxFunc(*bans, func(a, b Ban) int {
-			return a.Expires.Compare(b.Expires)
-		})
-		last = &ended
-
-		// The netblock's first ban held counts the bans it had before that
-		// one, since dropped to make room, and each ban held adds one.
-		notes.EarlierBans = (*bans)[0].Notes.EarlierBans + len(*bans)
-	}
-
-	notes.Request = notes.Request.cut()
-	ban := Ban{
-		Netblock: netblock,
-		Start:    now,
-		Expires:  l.expiry(last, now),
-		Notes:    notes,
-	}
-	l.add(ban)
-	l.made++
-
-	select {
-	case l.changed <- struct{}{}:
-	default: // a value is waiting already
-	}
-
-	return ban
+// BanForAttack bans netblock at now for a clear sign of attack, with
+// notes, and returns the ban, as BanForLimit does. A first ban lasts
+// AttackBanDuration; once the netblock has had one, the next is
+// permanent.
+func (l *Ledger) BanForAttack(netblock netip.Prefix, now time.Time, notes Notes) Ban {
+	return l.ban(netblock, now, CauseAttack, notes)
 }
 
 // Bans returns the bans held on netblock, oldest first. It is not a
@@ -256,13 +253,13 @@ func (l *Ledger) Bans(netblock netip.Prefix) []Ban {
 	return slices.Clone(*bans)
 }
 
-// Made returns how many bans the ledger has made since the start; bans
-// read from bans.json are not among them.
-func (l *Ledger) Made() int {
+// Made returns how many bans for cause the ledger has made since the
+// start; bans read from bans.json are not among them.
+func (l *Ledger) Made(cause string) int {
 	l.mu.Lock()
 	defer l.mu.Unlock()
 
-	return l.made
+	return l.made[cause]
 }
 
 // Count returns how many of the bans held are active at now, and how many
@@ -332,6 +329,55 @@ func (l *Ledger) Load(bans []Ban) {
 	}
 }
 
+// ban bans netblock at now for cause, with notes, as BanForLimit and
+// BanForAttack describe, and returns the ban.
+func (l *Ledger) ban(
+	netblock netip.Prefix, now time.Time, cause string, notes Notes,
+) Ban {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	// held are the netblock's bans, none of them active.
+	var held []Ban
+
+	bans, found := l.netblocks.Get(netblock)
+	if found {
+		active := activeBan(*bans, now)
+		if active != nil {
+			return *active
+		}
+
+		held = *bans
+
+		// The netblock's first ban held counts the bans it had before that
+		// one, since dropped to make room, and each ban held adds one.
+		notes.EarlierBans = (*bans)[0].Notes.EarlierBans + len(*bans)
+	}
+
+	notes.Request = notes.Request.cut()
+	ban := Ban{Netblock: netblock, Start: now, Cause: cause, Notes: notes}
+
+	if cause == CauseAttack {
+		ban.Expires = l.attackExpiry(held, now)
+	} else {
+		ban.Expires = l.limitExpiry(held, now)
+	}
+
+	l.add(ban)
+	l.made[cause]++
+	l.markChanged()
+
+	return ban
+}
+
+// markChanged has Changed receive a value, unless one is waiting already.
+func (l *Ledger) markChanged() {
+	select {
+	case l.changed <- struct{}{}:
+	default: // a value is waiting already
+	}
+}
+
 // active returns the ban active at now on a netblock client is in, or
 // nil.
 func (l *Ledger) active(client netip.Addr, now time.Time) *Ban {
@@ -383,12 +429,23 @@ func (l *Ledger) add(ban Ban) {
 	}
 }
 
-// expiry returns when a ban for a broken limit made at now ends, or zero
-// when it is permanent. last is the netblock's ban that ended last, or nil
-// when it has none.
-func (l *Ledger) expiry(last *Ban, now time.Time) time.Time {
+// limitExpiry returns when a ban for a broken limit made at now ends, or
+// zero when it is permanent. held are the netblock's bans, none of them
+// active, of which the one that ended last, other than a ban for a clear
+// sign of attack, can make the new ban longer. A ban an admin adds to
+// bans.json can start after another and end before it, so that one is
+// looked for among them all.
+func (l *Ledger) limitExpiry(held []Ban, now time.Time) time.Time {
 	length := l.rules.LimitBanDuration
 
+	var last *Ban
+
+	for i, ban := range held {
+		if ban.Cause != CauseAttack && (last == nil || ban.Expires.After(last.Expires)) {
+			last = &held[i]
+		}
+	}
+
 	if last != nil && now.Sub(last.Expires) <= l.rules.LimitBanRepeatWindow {
 		lastLength := last.Expires.Sub(last.Start)
 		// This is repeatFactor * lastLength > MaxBanDuration, written so
@@ -407,6 +464,20 @@ func (l *Ledger) expiry(last *Ban, now time.Time) time.Time {
 	return now.Add(length)
 }
 
+// attackExpiry returns when a ban for a clear sign of attack made at now
+// ends. held are the netblock's bans, none of them active: if one of them
+// is for a clear sign of attack too, the new ban is permanent, and its
+// end zero; otherwise it ends AttackBanDuration later.
+func (l *Ledger) attackExpiry(held []Ban, now time.Time) time.Time {
+	for _, ban := range held {
+		if ban.Cause == CauseAttack {
+			return time.Time{}
+		}
+	}
+
+	return now.Add(l.rules.AttackBanDuration)
+}
+
 // dropOne drops the earliest ban of the netblock that has gone longest
 // without a request, and the netblock with it if that was its only ban.
 func (l *Ledger) dropOne() {