What's new: learning mode
Put a site in learning mode for a few days. The WAF logs rule matches without blocking, turns what it sees into suggested exclusions with the evidence behind each one, and tells you when it's safe to switch to blocking. Nothing is applied until you accept it, and the site never switches to blocking by itself.
Rules → Suggestions
- Grouped by verdict: likely false positive, unclear and likely attack (keep blocking). Each suggestion shows the rules, the parameter and path, how many requests, clients and days are behind it, and plain-language reasons, e.g. "Triggered by 41 different clients", "38% of requests to /search trigger it", "Known noisy rule".
- IDs and array indexes are generalised.
/api/orders/8812/itemsanditems[3][note]become one suggestion forARGS:items[n][note] on /api/orders/*/items, which also covers orders the WAF hasn't seen yet. - Verify in sandbox replays real sample requests with the suggestion applied. If a request is still blocked by something else, it tells you which other suggestion is needed.
- Accept… lets you narrow or widen the scope first. Dismiss hides a suggestion unless its hits grow ten-fold. Accept all likely false positives handles the clear-cut ones in one go; likely attacks are never included.
- Every site gets suggestions. They refresh hourly for every site with recent blocked or detected requests, not only sites in learning mode.
Learning sessions
- Start learning… (1–30 days) on the Suggestions tab. The site logs instead of blocking, and its previous mode is remembered. Sites show a Learning · N days left badge.
- Readiness shows what blocking would have done over the session with your current exclusions, for example "67 requests from 9 clients: 3 look like attacks, 64 still need review". Once only attacks remain, it reads "Safe to switch to blocking".
- When the time is up, every notification channel receives "WAF learning finished" with the counts. The site stays in detection mode until you click Switch to blocking…. Cancel learning restores the previous mode.
How it tells false positives from attacks
- Points towards a false positive: many clients on several days, a large share of a path's traffic, otherwise-clean requests, and a short documented list of rules known to be noisy (listed in the User Guide).
- Points towards an attack: clients you have blocked in Threat Intel, scanner rules, several attack types at once, and libinjection detections from only a few clients.
- Attacks stay separate. An attack sent to a field that also has a real false positive becomes its own suggestion; it never rides along with the false positive.
Things to know
- Threat Intel scores aren't used. Only IPs you have blocked in Threat Intel count as an attack signal. Scores are computed from the same rule hits learning mode judges, so a user who keeps hitting a false positive would otherwise look like a threat.
- Readiness is an estimate. It covers logged requests, with default CRS scores and the site's current threshold. Use Verify in sandbox for an exact answer on specific requests.
- Database changes are automatic. The upgrade adds two tables and an index; they're created when the admin API starts.
- No compose changes. Verify uses the
waf-sandboxservice added in v1.0.25. Without it, everything else works and Verify reports the sandbox is unavailable.
The User Guide has a new Learning Mode & Suggestions section.
Upgrade
docker compose pull
docker compose up -d
latest points to this release. If you pin versions, set WAF_IMAGE_TAG=1.0.26 (no v prefix) before pulling.
Images: ghcr.io/socfortress/waf-caddy:1.0.26, ghcr.io/socfortress/waf-admin-api:1.0.26, ghcr.io/socfortress/waf-admin-ui:1.0.26