Watch mode: how to enable a fail2ban jail without banning your own

Turning a new fail2ban jail straight to ban mode is nerve-wracking. A web filter that looked harmless can catch monitoring, a payment provider's webhook or your own office, and you'll learn about it from a customer who can't reach the site. It's safer to first see whom the jail would ban without blocking anything. Here's how to build such a watch mode in plain fail2ban, and how it works in KIPBan.

Step 0. Test the filter on an old log

The first check doesn't require enabling the jail at all. fail2ban-regex runs a log through a filter and shows the matches:

fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/nginx-botsearch.conf --print-all-matched | less

Look not at the match count but at the lines and addresses themselves. If your monitoring, office or partners' addresses are among them, fix the filter or add those addresses to ignoreip.

This check has one limit: it shows matching lines, not bans. It doesn't count how many addresses would reach maxretry within findtime. That's what watch mode is for.

Step 1. A jail that counts but doesn't ban

fail2ban ships a dummy action: it blocks nothing and only writes banned addresses to a file. Give a jail only this action and fail2ban works as usual, keeps its counters and “bans”, but leaves the firewall alone:

# /etc/fail2ban/jail.d/nginx-botsearch-watch.local
[nginx-botsearch]
enabled  = true
port     = http,https
logpath  = /var/log/nginx/access.log
maxretry = 2
findtime = 10m
bantime  = 1h
action   = dummy

fail2ban-client reload
fail2ban-client status nginx-botsearch

After a few hours or a day, see whom the jail “banned”:

grep 'nginx-botsearch.*Ban ' /var/log/fail2ban.log
cat /var/run/fail2ban/fail2ban.dummy

If the list holds only scanners and bots, switch the jail to ban mode: remove the action = dummy line so the default action from banaction applies, and run fail2ban-client reload.

How to read the “would have banned” count

• None of your addresses — switch to ban mode.
• A few of yours — add them to ignoreip and watch for another day.
• Many of yours — the filter is too broad. Typical causes: a rule on any 404 or 403, a rule on an empty User-Agent or an empty request. Monitoring, load balancers and API clients look like that, and they must not be banned.
• Nobody — either the server gets no attacks of this kind, or the jail is watching the wrong log. Check logpath with fail2ban-client get NAME logpath.

Threshold and window

The right maxretry and findtime depend on what the jail catches:

• Unambiguous signs of an attack: a request for /.git/config, sqlmap in the User-Agent, a known exploit in the URL. Nobody does this by accident, so the threshold is 1. Scanners almost always arrive from a separate address and make one or two attempts; with a threshold of 5 they'll never be banned.
• Password guessing: a real person can mistype too, so 3–5 within 10 minutes.
• Slow guessing: bots that try once every few minutes slip past a 10-minute window. For them, use a one-hour or one-day window with the same threshold.

How KIPBan does it

In KIPBan, watch mode is the default for every new jail:

• Enabling. With the “Enable jail” button in the log analysis report or “Add jail” on the server page. Only patterns that fit the logs found on the server can be selected.
• Watching. A new jail counts whom it would ban and blocks nothing. The count is visible in the dashboard.
• Switching to ban — once you can see your own people don't fall under it. The address is then blocked as usual in KIPBan: with terms that grow on repeat offences, a Telegram notification and a report to the shared database.
• Settings. A threshold from 1 to 100 hits, a window from one minute to one day, up to 20 jails per server.
• Applying. The agent writes the fail2ban configuration itself, checks it and restarts fail2ban without losing bans, all within 5 minutes. If fail2ban rejects some jail, the others are applied and the dashboard shows the error.
• Logs. A jail uses the same logs the analysis found and refreshes the list hourly. A new site on the server is picked up automatically.

The KIPBan whitelist applies here too: addresses on it aren't blocked by any jail. Add your office and VPN to it before switching a jail to ban mode.

Limits: jails from the dashboard are available only on Linux with agent 21.6 or newer, are configured per server, and can only be chosen from the KIPBan pattern catalogue. Your own jails in jail.local are still connected to KIPBan by the agent automatically.

Questions