waf: each heuristic holds its own settings and parts #441

Open
opened 2026-11-19 17:13:13 +01:00 by clawbot · 1 comment
Collaborator

From the architecture review, "The decision pipeline: the heuristics", under "A heuristic declares nothing it needs": #283 (comment). Approved for building: #283 (comment). The code was read at 809d266 on next, where discriminator is now waf. Line numbers are that commit's.

This is the first of three steps the review orders inside the heuristics. The other two, typed facts on decision and the status on the verdict, build on it.

What is there

  • All sixteen heuristics in internal/waf are empty structs: type denyNets struct{}.
  • check(ctx, rq *request, now) is handed the whole request. Through rq.h it reaches the whole handler: every part waf is given, and all of config.WAF.
  • The six lists in internal/waf/heuristics.go are functions that build their slice again for every request: beforeLookup(), afterLookup(), besideLookup(), afterBesideLookup(), afterAnswer(), onReport().
  • findBesideLookup and runBesideLookup (internal/waf/besidelookup.go) make a heuristic only to read its name: trapPaths{}.name().

Why it matters

  • What a heuristic reads is found only by reading its body. The comment at the top of each file names its settings, and nothing holds that comment to the code.
  • None can be built with test values and called. Every heuristic's test starts a whole waf from a map of settings, sends requests over HTTP and reads the log line.
  • A heuristic with a new collaborator needs a new field on handler: a change outside its file. The issue that ordered modular heuristics (#195) asked for one file and one line in one place.

What changes

  • Each heuristic is a struct that holds its own settings and collaborators.
  • newHandler builds the six lists once, and the handler keeps them. That one place then shows which settings and parts each heuristic uses.
  • A heuristic's check no longer reads rq.h.

Before (denynets.go, heuristics.go):

type denyNets struct{}

func (denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict {
	for _, netblock := range rq.h.config.DenyNets {
		// ...

func beforeLookup() []heuristic {
	return []heuristic{headerLimits{}, tagLists{}, routeWatchTags{}, denyNets{}, activeBan{}}
}

After (the field names are placeholders):

type denyNets struct {
	netblocks []netip.Prefix // SWW_WAF_DENY_NETS
}

func (d denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict {
	for _, netblock := range d.netblocks {
		// ...

// in newHandler, once
h.beforeLookup = []heuristic{
	headerLimits{},
	tagLists{lists: params.Lists},
	routeWatchTags{routeWatch: params.RouteWatch},
	denyNets{netblocks: cfg.DenyNets},
	activeBan{ledger: params.Ledger, observe: cfg.Observe},
}
  • The review does not say what becomes of the code several heuristics share: banForLimit, banForAttack, alertBan, noteHit, limitPercentages, countedByRateLimits, clientGroup. It stays shared. It takes what it needs as arguments, or lives on a small struct that the heuristics using it hold. A heuristic never reaches the handler for it.
  • The work beside the lookup (findBesideLookup) uses the same three built heuristics as the list, in place of making new ones for their names.
  • One test builds one heuristic by itself with test values, such as denyNets, gives it a request with a client address, and checks the verdict.
  • The comment at the top of heuristics.go on adding a heuristic says where its settings and parts are handed to it.

What stays

  • The heuristic interface, the order of every list, and the rule that the first verdict ends the checks.
  • The request's own steps that are no heuristic keep using the handler: startLookUp, allow, deny, finish, addToHistory, countAnomalies.
  • The tests that drive a whole waf.

Done when

  • no heuristic is an empty struct unless it needs nothing, and no check reads rq.h;
  • the lists are built once, in newHandler;
  • behaviour is unchanged: every existing test passes with no assertion changed;
  • make check passes;
  • the PR body lists every new type and field name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (#213).

If this is more than one PR can carry, say so on this issue instead of starting.

Model: fable-5-2

From the architecture review, "The decision pipeline: the heuristics", under "A heuristic declares nothing it needs": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173833. Approved for building: https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`, where `discriminator` is now `waf`. Line numbers are that commit's. This is the first of three steps the review orders inside the heuristics. The other two, typed facts on `decision` and the status on the verdict, build on it. ### What is there - All sixteen heuristics in `internal/waf` are empty structs: `type denyNets struct{}`. - `check(ctx, rq *request, now)` is handed the whole request. Through `rq.h` it reaches the whole `handler`: every part `waf` is given, and all of `config.WAF`. - The six lists in `internal/waf/heuristics.go` are functions that build their slice again for every request: `beforeLookup()`, `afterLookup()`, `besideLookup()`, `afterBesideLookup()`, `afterAnswer()`, `onReport()`. - `findBesideLookup` and `runBesideLookup` (`internal/waf/besidelookup.go`) make a heuristic only to read its name: `trapPaths{}.name()`. ### Why it matters - What a heuristic reads is found only by reading its body. The comment at the top of each file names its settings, and nothing holds that comment to the code. - None can be built with test values and called. Every heuristic's test starts a whole `waf` from a map of settings, sends requests over HTTP and reads the log line. - A heuristic with a new collaborator needs a new field on `handler`: a change outside its file. The issue that ordered modular heuristics (https://git.eeqj.de/sneak/smallwebwaf/issues/195) asked for one file and one line in one place. ### What changes - Each heuristic is a struct that holds its own settings and collaborators. - `newHandler` builds the six lists once, and the handler keeps them. That one place then shows which settings and parts each heuristic uses. - A heuristic's `check` no longer reads `rq.h`. Before (`denynets.go`, `heuristics.go`): ```go type denyNets struct{} func (denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict { for _, netblock := range rq.h.config.DenyNets { // ... func beforeLookup() []heuristic { return []heuristic{headerLimits{}, tagLists{}, routeWatchTags{}, denyNets{}, activeBan{}} } ``` After (the field names are placeholders): ```go type denyNets struct { netblocks []netip.Prefix // SWW_WAF_DENY_NETS } func (d denyNets) check(_ context.Context, rq *request, _ time.Time) *verdict { for _, netblock := range d.netblocks { // ... // in newHandler, once h.beforeLookup = []heuristic{ headerLimits{}, tagLists{lists: params.Lists}, routeWatchTags{routeWatch: params.RouteWatch}, denyNets{netblocks: cfg.DenyNets}, activeBan{ledger: params.Ledger, observe: cfg.Observe}, } ``` - The review does not say what becomes of the code several heuristics share: `banForLimit`, `banForAttack`, `alertBan`, `noteHit`, `limitPercentages`, `countedByRateLimits`, `clientGroup`. It stays shared. It takes what it needs as arguments, or lives on a small struct that the heuristics using it hold. A heuristic never reaches the handler for it. - The work beside the lookup (`findBesideLookup`) uses the same three built heuristics as the list, in place of making new ones for their names. - One test builds one heuristic by itself with test values, such as `denyNets`, gives it a request with a client address, and checks the verdict. - The comment at the top of `heuristics.go` on adding a heuristic says where its settings and parts are handed to it. ### What stays - The `heuristic` interface, the order of every list, and the rule that the first verdict ends the checks. - The request's own steps that are no heuristic keep using the handler: `startLookUp`, `allow`, `deny`, `finish`, `addToHistory`, `countAnomalies`. - The tests that drive a whole `waf`. ### Done when - no heuristic is an empty struct unless it needs nothing, and no `check` reads `rq.h`; - the lists are built once, in `newHandler`; - behaviour is unchanged: every existing test passes with no assertion changed; - `make check` passes; - the PR body lists every new type and field name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (https://git.eeqj.de/sneak/smallwebwaf/issues/213). If this is more than one PR can carry, say so on this issue instead of starting. Model: fable-5-2
clawbot self-assigned this 2026-11-19 17:13:13 +01:00
Author
Collaborator

PR: #462 (branch issue-441-heuristic-structs).

Every heuristic now holds its own settings and parts, built once in newHandler. Shared code lives on three small structs the heuristics hold: banMaker, reputationHitNoter and biasedThresholds. A standalone denyNets test builds the heuristic and checks it with no handler.

  • Rule suppressed: //nolint:funlen on newHandler, following the existing config and metrics precedent.
  • Unrelated flake: in one make check run, with host load near 280, TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode/SQL_injection_after_1000_query_parameters hit a read timeout under -race. The next runs passed.

Model: opus-5-5

PR: https://git.eeqj.de/sneak/smallwebwaf/pulls/462 (branch `issue-441-heuristic-structs`). Every heuristic now holds its own settings and parts, built once in `newHandler`. Shared code lives on three small structs the heuristics hold: `banMaker`, `reputationHitNoter` and `biasedThresholds`. A standalone `denyNets` test builds the heuristic and checks it with no handler. - Rule suppressed: `//nolint:funlen` on `newHandler`, following the existing `config` and `metrics` precedent. - Unrelated flake: in one `make check` run, with host load near 280, `TestCoreRuleSetRefusesAttacksInBlockModeAndOnlyLogsThemInDetectMode/SQL_injection_after_1000_query_parameters` hit a read timeout under `-race`. The next runs passed. Model: opus-5-5
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#441