Alerts to a JSON webhook, with a cooldown and an hourly summary (closes #26)

SWWAF_ALERT_WEBHOOK_URL gets one JSON POST per alert, in SPEC.md's schema, with SWWAF_ALERT_WEBHOOK_HEADERS: ban and permanent_ban, with the ban's notes, in observe mode too, marked mode observe and worked out only when the alert would be sent; source_failure for GeoJS; file_error for a rule or state file with an error. SWWAF_ALERT_EVENTS chooses; SWWAF_ALERT_COOLDOWN holds back repeats by netblock, file or source; past SWWAF_ALERT_MAX_PER_HOUR the hour ends in one summary. A bounded queue, retried with backoff, holds up no request; a 4xx other than 408 and 429 gives the alert up. alerts.json keeps the queue, the cooldowns and the hour. Nothing shows the URL's path or query. Judgement call: the summary's event is summary, which SPEC.md omits. Judgement call: an admin's ban raises no alert. Model: opus-5-5
2026-10-07 01:36:59 +00:00
parent 5d6f6ffaf9
commit 7d49123874
25 changed files with 3411 additions and 255 deletions
@@ -21,7 +21,7 @@ func TestRepeatsTripleUntilPermanent(t *testing.T) {
 	// Each ban is followed by another as soon as it ends: 1, 3, 9, 27 and
 	// 81 hours.
 	for i, hours := range []int{1, 3, 9, 27, 81} {
-		ban := ledger.BanForLimit(netblock, now, bans.Notes{})
+		ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})

 		length := time.Duration(hours) * time.Hour
 		if !ban.Expires.Equal(now.Add(length)) ||
@@ -35,12 +35,12 @@ func TestRepeatsTripleUntilPermanent(t *testing.T) {

 	// The sixth would last 243 hours, more than seven days: it is
 	// permanent, and never ends.
-	ban := ledger.BanForLimit(netblock, now, bans.Notes{})
+	ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
 	if !ban.Permanent() {
 		t.Fatalf("sixth ban ends at %s, want a permanent one", ban.Expires)
 	}

-	_, banned := ledger.Check(netblock.Addr(), now.Add(100*365*day))
+	_, banned, _ := ledger.Check(netblock.Addr(), now.Add(100*365*day))
 	if !banned {
 		t.Error("a permanent ban ended")
 	}
@@ -64,8 +64,8 @@ func TestRepeatWindowRunsOut(t *testing.T) {
 			ledger := bans.New(defaultRules())
 			netblock := netip.MustParsePrefix("203.0.113.9/32")

-			first := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
-			second := ledger.BanForLimit(netblock, first.Expires.Add(tc.gap), bans.Notes{})
+			first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+			second, _ := ledger.BanForLimit(netblock, first.Expires.Add(tc.gap), bans.Notes{})

 			if second.Expires.Sub(second.Start) != tc.want ||
 				second.Notes.EarlierBans != (bans.EarlierBans{Limit: 1}) {
@@ -83,7 +83,7 @@ func TestFirstBanLongerThanTheMaximumIsPermanent(t *testing.T) {
 	rules.LimitBanDuration = rules.MaxBanDuration + time.Hour
 	ledger := bans.New(rules)

-	ban := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.9/32"), midnight(),
+	ban, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.9/32"), midnight(),
 		bans.Notes{})
 	if !ban.Permanent() {
 		t.Errorf("first ban ends at %s, want a permanent one", ban.Expires)
@@ -103,7 +103,7 @@ func TestLongestBanSetFarOffDoesNotOverflow(t *testing.T) {
 	now := midnight()

 	for i := range 14 {
-		ban := ledger.BanForLimit(netblock, now, bans.Notes{})
+		ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
 		if !ban.Expires.After(ban.Start) {
 			t.Fatalf("ban %d starts at %s and ends at %s", i+1, ban.Start, ban.Expires)
 		}
@@ -111,7 +111,7 @@ func TestLongestBanSetFarOffDoesNotOverflow(t *testing.T) {
 		now = ban.Expires
 	}

-	ban := ledger.BanForLimit(netblock, now, bans.Notes{})
+	ban, _ := ledger.BanForLimit(netblock, now, bans.Notes{})
 	if !ban.Permanent() {
 		t.Errorf("15th ban ends at %s, want a permanent one", ban.Expires)
 	}
@@ -123,12 +123,22 @@ func TestBrokenLimitDuringABanMakesNoOther(t *testing.T) {
 	ledger := bans.New(defaultRules())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")

-	first := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
-	again := ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+	first, made := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	if !made {
+		t.Error("the first ban was not made")
+	}

-	if again != first || len(ledger.Bans(netblock)) != 1 {
-		t.Errorf("a limit broken during a ban gave %+v and %d bans, want %+v and 1",
-			again, len(ledger.Bans(netblock)), first)
+	again, made := ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+
+	if made || again != first || len(ledger.Bans(netblock)) != 1 {
+		t.Errorf("a limit broken during a ban gave %+v, made %t, and %d bans, "+
+			"want %+v, not made, and 1", again, made, len(ledger.Bans(netblock)), first)
+	}
+
+	again, made = ledger.BanForAttack(netblock, midnight().Add(time.Minute), bans.Notes{})
+	if made || again != first {
+		t.Errorf("an attack during a ban gave %+v, made %t, want %+v, not made",
+			again, made, first)
 	}
 }

@@ -137,21 +147,21 @@ func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {

 	ledger := bans.New(defaultRules())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
-	ban := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})

 	for range 3 {
-		got, banned := ledger.Check(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
+		got, banned, _ := ledger.Check(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
 		if !banned || got.Start != ban.Start {
 			t.Fatalf("check during the ban gives %+v and %t", got, banned)
 		}
 	}

-	_, banned := ledger.Check(netip.MustParseAddr("203.0.113.10"), midnight())
+	_, banned, _ := ledger.Check(netip.MustParseAddr("203.0.113.10"), midnight())
 	if banned {
 		t.Error("another netblock is banned")
 	}

-	_, banned = ledger.Check(netblock.Addr(), ban.Expires)
+	_, banned, _ = ledger.Check(netblock.Addr(), ban.Expires)
 	if banned {
 		t.Error("the ban did not end")
 	}
@@ -169,14 +179,14 @@ func TestFindCountsNothing(t *testing.T) {

 	ledger := bans.New(defaultRules())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
-	ban := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})

-	got, banned := ledger.Find(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
+	got, banned, _ := ledger.Find(netblock.Addr(), ban.Expires.Add(-time.Nanosecond))
 	if !banned || got != ban {
 		t.Errorf("find during the ban gives %+v and %t, want %+v", got, banned, ban)
 	}

-	_, banned = ledger.Find(netblock.Addr(), ban.Expires)
+	_, banned, _ = ledger.Find(netblock.Addr(), ban.Expires)
 	if banned {
 		t.Error("the ban did not end")
 	}
@@ -198,7 +208,7 @@ func TestMaxBansDropsTheEarliestBanOfTheNetblockSeenLongestAgo(t *testing.T) {
 	d := netip.MustParsePrefix("2001:db8::/64")
 	now := midnight()

-	first := ledger.BanForLimit(a, now, bans.Notes{})
+	first, _ := ledger.BanForLimit(a, now, bans.Notes{})
 	ledger.BanForLimit(b, now, bans.Notes{})
 	ledger.BanForLimit(c, now, bans.Notes{})

@@ -233,8 +243,8 @@ func TestFullLedgerDropsTheEarlierBanOfTheNetblockBannedAgain(t *testing.T) {
 	ledger := bans.New(rules)
 	netblock := netip.MustParsePrefix("203.0.113.9/32")

-	first := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
-	second := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})

 	held := ledger.Bans(netblock)
 	if len(held) != 1 || held[0] != second ||
@@ -251,7 +261,7 @@ func TestRequestDuringAnAttackBanMakesItPermanent(t *testing.T) {
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	notes := bans.Notes{RuleID: "env-file", Target: "path"}

-	ban := ledger.BanForAttack(netblock, midnight(), notes)
+	ban, _ := ledger.BanForAttack(netblock, midnight(), notes)
 	if !ban.Expires.Equal(midnight().Add(7*day)) || ban.Cause != bans.CauseAttack ||
 		ban.Notes.RuleID != "env-file" || ledger.Made(bans.CauseAttack) != 1 ||
 		ledger.Made(bans.CauseLimit) != 0 {
@@ -262,23 +272,31 @@ func TestRequestDuringAnAttackBanMakesItPermanent(t *testing.T) {

 	wantChanged(t, ledger, true)

-	// In observe mode the ban refuses nothing, and stays as it is.
-	got, _ := ledger.Find(netblock.Addr(), midnight().Add(time.Hour))
-	if got.Permanent() {
-		t.Fatal("a request found under the ban made it permanent")
+	// In observe mode the ban refuses nothing, and stays as it is, while
+	// Find tells that the request would have made it permanent.
+	got, _, wouldMakePermanent := ledger.Find(netblock.Addr(), midnight().Add(time.Hour))
+	if got.Permanent() || ledger.Bans(netblock)[0].Permanent() || !wouldMakePermanent {
+		t.Fatalf("a request found under the ban left it %+v, would have made it "+
+			"permanent %t, want it as it was, and true", got, wouldMakePermanent)
 	}

-	// A request it refuses makes it permanent, and bans.json due.
-	got, _ = ledger.Check(netblock.Addr(), midnight().Add(time.Hour))
-	if !got.Permanent() || !ledger.Bans(netblock)[0].Permanent() {
-		t.Fatalf("after a request during the ban, it is %+v, want it permanent", got)
+	wantChanged(t, ledger, false)
+
+	// A request it refuses makes it permanent, says so, and makes
+	// bans.json due.
+	got, _, madePermanent := ledger.Check(netblock.Addr(), midnight().Add(time.Hour))
+	if !madePermanent || !got.Permanent() || !ledger.Bans(netblock)[0].Permanent() {
+		t.Fatalf("after a request during the ban, it is %+v, made permanent %t, "+
+			"want it made permanent", got, madePermanent)
 	}

 	wantChanged(t, ledger, true)

-	_, banned := ledger.Check(netblock.Addr(), midnight().Add(100*365*day))
-	if !banned {
-		t.Error("the permanent ban ended")
+	// The next request finds it permanent already.
+	_, banned, madePermanent := ledger.Check(netblock.Addr(), midnight().Add(100*365*day))
+	if !banned || madePermanent {
+		t.Errorf("a later request is banned %t, and made the ban permanent %t, "+
+			"want banned by the permanent ban", banned, madePermanent)
 	}
 }

@@ -289,8 +307,8 @@ func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {
 	netblock := netip.MustParsePrefix("203.0.113.9/32")

 	// A ban for a broken limit before does not count.
-	first := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
-	second := ledger.BanForAttack(netblock, first.Expires, bans.Notes{})
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForAttack(netblock, first.Expires, bans.Notes{})

 	if second.Expires.Sub(second.Start) != 7*day {
 		t.Fatalf("the first ban for an attack lasts %s, want 7 days",
@@ -299,14 +317,14 @@ func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {

 	// Once that has run out without a request, the netblock is served, and
 	// its next clear sign of attack bans it for good.
-	_, banned := ledger.Check(netblock.Addr(), second.Expires)
+	_, banned, _ := ledger.Check(netblock.Addr(), second.Expires)
 	if banned {
 		t.Fatal("the ban did not end")
 	}

 	// Its notes show the earlier ban for an attack that makes it permanent,
 	// beside the one for a limit.
-	third := ledger.BanForAttack(netblock, second.Expires.Add(30*day), bans.Notes{})
+	third, _ := ledger.BanForAttack(netblock, second.Expires.Add(30*day), bans.Notes{})
 	if !third.Permanent() ||
 		third.Notes.EarlierBans != (bans.EarlierBans{Limit: 1, Attack: 1}) {
 		t.Errorf("the next ban for an attack is %+v, want a permanent one, "+
@@ -314,6 +332,50 @@ func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {
 	}
 }

+func TestWouldBanGivesTheBanWithoutMakingIt(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.9/32")
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	wantChanged(t, ledger, true)
+
+	// While the first ban lasts, none would be made.
+	during, would := ledger.WouldBanForAttack(netblock, midnight(), bans.Notes{})
+	if would || during != first {
+		t.Errorf("during the first ban, would ban %t with %+v, want false with %+v",
+			would, during, first)
+	}
+
+	// As it ends, a clear sign of attack would ban for seven days, and a
+	// limit broken again for three hours, but neither is made.
+	limitNotes := bans.Notes{Limit: 1, Window: "minute"}
+	attack, wouldAttack := ledger.WouldBanForAttack(netblock, first.Expires,
+		bans.Notes{RuleID: "git-dir"})
+	limit, wouldLimit := ledger.WouldBanForLimit(netblock, first.Expires, limitNotes)
+
+	if !wouldAttack || !attack.Expires.Equal(first.Expires.Add(7*day)) ||
+		attack.Reason != "matched the rule git-dir" || !wouldLimit ||
+		!limit.Expires.Equal(first.Expires.Add(3*time.Hour)) ||
+		limit.Reason != "requests per minute over the limit of 1" {
+		t.Errorf("would ban with %+v and %+v, want seven days for the attack and "+
+			"three hours for the limit", attack, limit)
+	}
+
+	if len(ledger.Bans(netblock)) != 1 || ledger.Made(bans.CauseLimit) != 1 ||
+		ledger.Made(bans.CauseAttack) != 0 {
+		t.Errorf("the ledger holds %+v, want the first ban alone", ledger.Bans(netblock))
+	}
+
+	wantChanged(t, ledger, false)
+
+	// The ban made is the one that would have been.
+	made, _ := ledger.BanForLimit(netblock, first.Expires, limitNotes)
+	if made != limit {
+		t.Errorf("the ban made is %+v, want %+v", made, limit)
+	}
+}
+
 func TestAttackBanDoesNotLengthenTheNextBanForALimit(t *testing.T) {
 	t.Parallel()

@@ -322,16 +384,16 @@ func TestAttackBanDoesNotLengthenTheNextBanForALimit(t *testing.T) {

 	// Three times the seven days would be permanent; a limit broken as the
 	// ban for an attack ends bans for an hour, as a first broken limit does.
-	attack := ledger.BanForAttack(netblock, midnight(), bans.Notes{})
-	limit := ledger.BanForLimit(netblock, attack.Expires, bans.Notes{})
+	attack, _ := ledger.BanForAttack(netblock, midnight(), bans.Notes{})
+	limit, _ := ledger.BanForLimit(netblock, attack.Expires, bans.Notes{})

 	if limit.Expires.Sub(limit.Start) != time.Hour || limit.Cause != bans.CauseLimit {
 		t.Errorf("the ban for a limit is %+v, want one of an hour", limit)
 	}

 	// And a request during the ban for a limit leaves it as it is.
-	got, _ := ledger.Check(netblock.Addr(), limit.Start)
-	if got.Permanent() {
+	got, _, madePermanent := ledger.Check(netblock.Addr(), limit.Start)
+	if got.Permanent() || madePermanent {
 		t.Error("a request during a ban for a limit made it permanent")
 	}
 }
@@ -346,7 +408,7 @@ func TestRequestTextsAreCutTo256Bytes(t *testing.T) {
 		Time: midnight(), Method: long, Host: long, Path: long, Status: 403, UserAgent: long,
 	}

-	ban := ledger.BanForLimit(netblock, midnight(), bans.Notes{Request: request})
+	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Request: request})

 	cut := long[:256]
 	want := bans.Request{