Name log fields, metrics and the Core Rule Set package for what they are (closes #192)

Log field, metric, action and event names now say what they count
and, for timings, the unit. Package internal/waf is internal/coreruleset.

Model: opus-5-5

internal/bans/admin_test.go

@@ -13,7 +13,7 @@ func TestBanWithoutACauseIsAnAdmins(t *testing.T) {
 	t.Parallel()
 
 	netblock := netip.MustParsePrefix("203.0.113.0/24")
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{{Netblock: netblock, Start: midnight()}})
 
 	if got := ledger.Bans(netblock)[0].Cause; got != bans.CauseAdmin {
@@ -24,9 +24,9 @@ func TestBanWithoutACauseIsAnAdmins(t *testing.T) {
 func TestAdminsBansAreNeverDroppedAndDoNotCountTowardMaxBans(t *testing.T) {
 	t.Parallel()
 
-	rules := defaultRules()
-	rules.MaxBans = 1
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 1
+	ledger := bans.New(params)
 	adminsOnly := netip.MustParsePrefix("198.51.100.0/24")
 	both := netip.MustParsePrefix("203.0.113.1/32")
 	second := netip.MustParsePrefix("203.0.113.2/32")
@@ -64,9 +64,9 @@ func TestAdminsBansAreNeverDroppedAndDoNotCountTowardMaxBans(t *testing.T) {
 func TestEarlierBansCountABanDroppedAfterAnAdminsBan(t *testing.T) {
 	t.Parallel()
 
-	rules := defaultRules()
-	rules.MaxBans = 2
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 2
+	ledger := bans.New(params)
 	netblock := netip.MustParsePrefix("203.0.113.1/32")
 	other := netip.MustParsePrefix("203.0.113.2/32")
 
@@ -93,7 +93,7 @@ func TestEarlierBansCountABanDroppedAfterAnAdminsBan(t *testing.T) {
 func TestEarlierBansCountABanAnAdminKeepsOnce(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.1/32")
 
 	// The netblock breaks a limit twice, the second time after its first
@@ -117,7 +117,7 @@ func TestEarlierBansCountABanAnAdminKeepsOnce(t *testing.T) {
 func TestReasonOfTheBansSwwMakes(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 
 	limit, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.1/32"), midnight(),
 		bans.Notes{Kind: "requests", Limit: 1000, Window: "minute"})
@@ -150,7 +150,7 @@ func TestLiftedBanForALimitRefusesNothingAndMakesNoBanLonger(t *testing.T) {
 		Lifted:   midnight().Add(10 * time.Minute),
 	}
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{lifted})
 
 	// While it would still last, it refuses nothing, and a limit broken
@@ -181,7 +181,7 @@ func TestLiftedBanForAnAttackRefusesNothingAndMakesNoBanLonger(t *testing.T) {
 
 	// A permanent ban for a clear sign of attack, lifted.
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{{
 		Netblock: netblock,
 		Start:    midnight(),
@@ -211,7 +211,7 @@ func TestLiftedBanForAnAttackRefusesNothingAndMakesNoBanLonger(t *testing.T) {
 func TestLoadEditCountsTheBansAnAdminMade(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	made, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.1/32"), midnight(),
 		bans.Notes{})
 	atStart := bans.Ban{
@@ -246,7 +246,7 @@ func TestAdminsBanIsMadeWhileAnotherLasts(t *testing.T) {
 	t.Parallel()
 
 	netblock := netip.MustParsePrefix("203.0.113.0/24")
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 
 	// An hour's ban for a broken limit.
 	ledger.BanForLimit(netblock, midnight(), bans.Notes{})
@@ -292,7 +292,7 @@ func TestLiftLiftsEveryActiveBanCoveringTheClient(t *testing.T) {
 	wide := netip.MustParsePrefix("203.0.113.0/24")
 	other := netip.MustParsePrefix("203.0.113.10/32")
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{
 		// Ended an hour ago.
 		{
@@ -346,7 +346,7 @@ func TestPermanentBanOnAWiderNetblockIsReturnedOverATemporaryBan(t *testing.T) {
 	t.Parallel()
 
 	client := netip.MustParseAddr("203.0.113.9")
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 
 	// The temporary ban is made first, so that its netblock is looked at first.
 	ledger.BanForLimit(netip.MustParsePrefix("203.0.113.9/32"), midnight(), bans.Notes{})
@@ -360,7 +360,7 @@ func TestOlderPermanentBanIsReturnedOverANewerTemporaryBan(t *testing.T) {
 	t.Parallel()
 
 	netblock := netip.MustParsePrefix("203.0.113.0/24")
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 
 	ledger.BanForAdmin(netblock, midnight(), time.Time{}, "for good")
 	ledger.BanForAdmin(netblock, midnight().Add(time.Minute), midnight().Add(time.Hour),

internal/bans/bans.go

@@ -40,8 +40,8 @@ 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 lasts, and how many bans are held.
-type Rules struct {
+// Params are how long a ban lasts, and how many bans are held.
+type Params struct {
 	// 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
@@ -180,7 +180,7 @@ type Request struct {
 
 // Ledger holds the bans. It is safe for concurrent use.
 type Ledger struct {
-	rules Rules
+	params Params
 	// changed receives a value when a ban is made, unless one is waiting
 	// already.
 	changed chan struct{}
@@ -190,7 +190,7 @@ type Ledger struct {
 	// Find make each netblock they find the most recently seen.
 	netblocks *simplelru.LRU[netip.Prefix, *[]Ban]
 	// held is how many bans netblocks holds whose cause is not CauseAdmin,
-	// at most rules.MaxBans.
+	// at most params.MaxBans.
 	held int
 	// made is how many bans have been made since the start, by cause: by
 	// the ledger, and by an admin, through BanForAdmin or in an edit of
@@ -205,7 +205,7 @@ type Ledger struct {
 }
 
 // New returns a Ledger with no ban yet.
-func New(rules Rules) *Ledger {
+func New(params Params) *Ledger {
 	// The ledger drops bans itself, and never those whose cause is
 	// CauseAdmin, however many there are, so the LRU has no limit of its
 	// own: it keeps the netblocks in the order they were last seen.
@@ -215,7 +215,7 @@ func New(rules Rules) *Ledger {
 	}
 
 	return &Ledger{
-		rules:     rules,
+		params:    params,
 		changed:   make(chan struct{}, 1),
 		netblocks: netblocks,
 		made:      map[string]int{},
@@ -812,7 +812,7 @@ func (l *Ledger) covering(client netip.Addr) []*[]Ban {
 // unless ban's cause is CauseAdmin, which does not count toward MaxBans.
 func (l *Ledger) add(ban Ban) {
 	counted := ban.Cause != CauseAdmin
-	if counted && l.held == l.rules.MaxBans {
+	if counted && l.held == l.params.MaxBans {
 		l.dropOne()
 	}
 
@@ -847,7 +847,7 @@ func (l *Ledger) add(ban Ban) {
 // 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
+	length := l.params.LimitBanDuration
 
 	var last *Ban
 
@@ -858,18 +858,18 @@ func (l *Ledger) limitExpiry(held []Ban, now time.Time) time.Time {
 		}
 	}
 
-	if last != nil && now.Sub(last.Expires) <= l.rules.LimitBanRepeatWindow {
+	if last != nil && now.Sub(last.Expires) <= l.params.LimitBanRepeatWindow {
 		lastLength := last.Expires.Sub(last.Start)
 		// This is repeatFactor * lastLength > MaxBanDuration, written so
 		// that it cannot overflow.
-		if lastLength > l.rules.MaxBanDuration/repeatFactor {
+		if lastLength > l.params.MaxBanDuration/repeatFactor {
 			return time.Time{}
 		}
 
 		length = repeatFactor * lastLength
 	}
 
-	if length > l.rules.MaxBanDuration {
+	if length > l.params.MaxBanDuration {
 		return time.Time{}
 	}
 
@@ -887,7 +887,7 @@ func (l *Ledger) attackExpiry(held []Ban, now time.Time) time.Time {
 		}
 	}
 
-	return now.Add(l.rules.AttackBanDuration)
+	return now.Add(l.params.AttackBanDuration)
 }
 
 // dropOne drops the earliest ban whose cause is not CauseAdmin of the

internal/bans/bans_test.go

@@ -15,7 +15,7 @@ const day = 24 * time.Hour
 func TestRepeatsTripleUntilPermanent(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	now := midnight()
 
@@ -62,7 +62,7 @@ func TestRepeatWindowRunsOut(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 
-			ledger := bans.New(defaultRules())
+			ledger := bans.New(defaultParams())
 			netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 			first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
@@ -80,9 +80,9 @@ func TestRepeatWindowRunsOut(t *testing.T) {
 func TestFirstBanLongerThanTheMaximumIsPermanent(t *testing.T) {
 	t.Parallel()
 
-	rules := defaultRules()
-	rules.LimitBanDuration = rules.MaxBanDuration + time.Hour
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.LimitBanDuration = params.MaxBanDuration + time.Hour
+	ledger := bans.New(params)
 
 	ban, _ := ledger.BanForLimit(netip.MustParsePrefix("203.0.113.9/32"), midnight(),
 		bans.Notes{})
@@ -97,9 +97,9 @@ func TestLongestBanSetFarOffDoesNotOverflow(t *testing.T) {
 	// With bans of up to 100,000 days, the 14th ban in a row, of 3^13
 	// hours, is within the maximum, and three times as long would not fit
 	// in a time.Duration. The 15th is permanent.
-	rules := defaultRules()
-	rules.MaxBanDuration = 100000 * day
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBanDuration = 100000 * day
+	ledger := bans.New(params)
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	now := midnight()
 
@@ -121,7 +121,7 @@ func TestLongestBanSetFarOffDoesNotOverflow(t *testing.T) {
 func TestBrokenLimitDuringABanMakesNoOther(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	first, made := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
@@ -146,7 +146,7 @@ func TestBrokenLimitDuringABanMakesNoOther(t *testing.T) {
 func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
 
@@ -178,7 +178,7 @@ func TestCheckRefusesWhileTheBanLastsAndCountsTheRefusals(t *testing.T) {
 func TestFindCountsNothing(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	ban, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{Requests: 5})
 
@@ -200,9 +200,9 @@ func TestFindCountsNothing(t *testing.T) {
 func TestMaxBansDropsTheEarliestBanOfTheNetblockSeenLongestAgo(t *testing.T) {
 	t.Parallel()
 
-	rules := defaultRules()
-	rules.MaxBans = 3
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 3
+	ledger := bans.New(params)
 	a := netip.MustParsePrefix("203.0.113.1/32")
 	b := netip.MustParsePrefix("203.0.113.2/32")
 	c := netip.MustParsePrefix("203.0.113.3/32")
@@ -239,9 +239,9 @@ func TestFullLedgerDropsTheEarlierBanOfTheNetblockBannedAgain(t *testing.T) {
 
 	// With room for one ban, the netblock's ended ban goes to make room for
 	// its new one, whose notes still count it.
-	rules := defaultRules()
-	rules.MaxBans = 1
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 1
+	ledger := bans.New(params)
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
@@ -258,7 +258,7 @@ func TestFullLedgerDropsTheEarlierBanOfTheNetblockBannedAgain(t *testing.T) {
 func TestRequestDuringAnAttackBanMakesItPermanent(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	notes := bans.Notes{RuleID: "env-file", Target: "path"}
 
@@ -304,7 +304,7 @@ func TestRequestDuringAnAttackBanMakesItPermanent(t *testing.T) {
 func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	// A ban for a broken limit before does not count.
@@ -336,7 +336,7 @@ func TestAttackAfterAnAttackBanHasEndedBansPermanently(t *testing.T) {
 func TestWouldBanGivesTheBanWithoutMakingIt(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
 	wantChanged(t, ledger, true)
@@ -380,7 +380,7 @@ func TestWouldBanGivesTheBanWithoutMakingIt(t *testing.T) {
 func TestWouldBePermanentAnswersAsTheBanWouldBeMade(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	now := midnight()
 
@@ -414,7 +414,7 @@ func TestWouldBePermanentAnswersAsTheBanWouldBeMade(t *testing.T) {
 func TestAttackBanDoesNotLengthenTheNextBanForALimit(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	// Three times the seven days would be permanent; a limit broken as the
@@ -436,7 +436,7 @@ func TestAttackBanDoesNotLengthenTheNextBanForALimit(t *testing.T) {
 func TestRequestTextsAreCutTo256Bytes(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	long := strings.Repeat("a", 300)
 	request := bans.Request{
@@ -458,7 +458,7 @@ func TestRequestTextsAreCutTo256Bytes(t *testing.T) {
 func TestLookupFillsTheNotesOfTheNetblocksBansWithoutOne(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	other := netip.MustParsePrefix("198.51.100.7/32")
 
@@ -494,9 +494,9 @@ func TestLookupFillsTheNotesOfTheNetblocksBansWithoutOne(t *testing.T) {
 	}
 }
 
-// defaultRules are the rules at the settings' defaults.
-func defaultRules() bans.Rules {
-	return bans.Rules{
+// defaultParams are the params at the settings' defaults.
+func defaultParams() bans.Params {
+	return bans.Params{
 		LimitBanDuration:     time.Hour,
 		LimitBanRepeatWindow: day,
 		MaxBanDuration:       7 * day,

internal/bans/crowdsec_test.go

@@ -15,7 +15,7 @@ const scenario = "crowdsecurity/ssh-bf"
 func TestCrowdSecBanLastsUntilTheDecisionEnds(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	expires := midnight().Add(4 * time.Hour)
 
@@ -49,7 +49,7 @@ func TestCrowdSecBanLastsUntilTheDecisionEnds(t *testing.T) {
 func TestCrowdSecBanIsNeverMadePermanent(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	expires := midnight().Add(4 * time.Hour)
 	ledger.BanForCrowdSec(netblock, midnight(), expires, scenario, bans.Notes{})
@@ -72,7 +72,7 @@ func TestCrowdSecBanIsNeverMadePermanent(t *testing.T) {
 func TestCrowdSecBanIsCountedAndDoesNotLengthenTheNextBanForALimit(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	// Three times the three days would be permanent; a limit broken as the

internal/bans/snapshot_test.go

@@ -14,7 +14,7 @@ import (
 func TestChangedAfterABanIsMade(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 
 	wantChanged(t, ledger, false)
@@ -38,7 +38,7 @@ func TestChangedAfterABanIsMade(t *testing.T) {
 func TestSnapshotListsEveryBanByNetblock(t *testing.T) {
 	t.Parallel()
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	v6 := netip.MustParsePrefix("2001:db8::/64")
 	high := netip.MustParsePrefix("203.0.113.10/32")
 	low := netip.MustParsePrefix("203.0.113.9/32")
@@ -67,14 +67,14 @@ func TestSnapshotListsEveryBanByNetblock(t *testing.T) {
 func TestLoadedBansCarryOn(t *testing.T) {
 	t.Parallel()
 
-	before := bans.New(defaultRules())
+	before := bans.New(defaultParams())
 	netblock := netip.MustParsePrefix("203.0.113.9/32")
 	ban, _ := before.BanForLimit(netblock, midnight(), bans.Notes{Limit: 1})
 
 	// Loaded into a new ledger, as across a restart, the ban still refuses
 	// while it lasts, and once it has ended a broken limit bans for three
 	// times as long, with the loaded ban counted among the earlier ones.
-	after := bans.New(defaultRules())
+	after := bans.New(defaultParams())
 	after.Load(before.Snapshot())
 
 	_, banned, _ := after.Check(netblock.Addr(), ban.Expires.Add(-time.Second))
@@ -96,7 +96,7 @@ func TestLoadedBanRefusesEveryClientInItsNetblock(t *testing.T) {
 	// Two entries as an admin might write them, with addresses not masked
 	// to their lengths, the IPv6 one shorter than the /64 an IPv6 client's
 	// ban covers, beside a ban the ledger makes on one IPv4 address.
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{
 		{Netblock: netip.MustParsePrefix("203.0.113.9/24"), Start: midnight()},
 		{Netblock: netip.MustParsePrefix("2001:db8::1/48"), Start: midnight()},
@@ -145,7 +145,7 @@ func TestPermanentBanStartedBeforeAnEndedOneRefuses(t *testing.T) {
 		Expires:  midnight().Add(time.Hour),
 	}
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{permanent, ended})
 
 	now := midnight().Add(2 * time.Hour)
@@ -189,7 +189,7 @@ func TestNextBanWorkedOutFromTheBanThatEndedLast(t *testing.T) {
 		Expires:  midnight().Add(2 * time.Hour),
 	}
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{nineHours, admins})
 
 	// Once both have ended, a limit broken within the repeat window bans
@@ -219,9 +219,9 @@ func TestLoadKeepsAtMostMaxBansDroppingTheEarliest(t *testing.T) {
 		Cause:    bans.CauseLimit,
 	}
 
-	rules := defaultRules()
-	rules.MaxBans = 1
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 1
+	ledger := bans.New(params)
 	ledger.Load([]bans.Ban{later, earlier})
 
 	held := ledger.Snapshot()
@@ -235,9 +235,9 @@ func TestLoadReplacesTheBansHeld(t *testing.T) {
 
 	// Room for three bans, so that the second load, were it added to the
 	// two bans held, would drop none of them to make room.
-	rules := defaultRules()
-	rules.MaxBans = 3
-	ledger := bans.New(rules)
+	params := defaultParams()
+	params.MaxBans = 3
+	ledger := bans.New(params)
 	kept := bans.Ban{
 		Netblock: netip.MustParsePrefix("2001:db8::/64"),
 		Start:    midnight(),
@@ -285,7 +285,7 @@ func TestLoadCutsTheTextsTo256Bytes(t *testing.T) {
 		}},
 	}
 
-	ledger := bans.New(defaultRules())
+	ledger := bans.New(defaultParams())
 	ledger.Load([]bans.Ban{ban})
 
 	cut := long[:256]