GeoTech

Engineering / Case study

mail-spray-guard: a fail2ban rule that bans password spraying after one failed login

GeoTech Engineering · · 7 min read

fail2banEmail securityOpen sourceDovecot

Last week we wrote up a password-spraying campaign against one of the mail domains we host: hundreds of residential IP addresses, almost all of them trying exactly once. The rule that stopped it was small enough to fit on a screen, so we cleaned it up, made it work for any domain and any set of countries, and published it as mail-spray-guard under the MIT licence. This article is the engineering side: how it decides, how to install it, what it cost us in false positives, and the numbers from five days in production.

314addresses banned by the one-failure rule in 5 days
2banned by the classic 8-failures rule
509 / 530failing addresses that tried only once
0home-country addresses on the ban list

TL;DR

The problem in one log line

A sprayed login looks like any other typo:

dovecot[2211]: imap-login: Disconnected: Connection closed (auth failed, 1 attempts in 2 secs):
  user=<accounts@example.com>, method=PLAIN, rip=203.0.113.17, ...

The next attempt comes from a different address, a few minutes later. In the week of logs we checked for this article, 530 different addresses failed an IMAP or POP3 login on our server; 509 of them failed exactly once and never came back. Only 10 reached eight failures at all, spread over the whole week. Any per-address threshold either never fires or has to be set so low that it bans your own staff.

Why the usual fixes cost too much

The signal that is cheap and reliable is where the failure comes from. A regional business's users log in from a handful of countries. One wrong password from a country none of them is ever in is already strong evidence.

How it works

Both jails read the same filter, which matches failed Dovecot logins (IMAP, POP3, submission, ManageSieve) and failed Postfix SASL authentication. The difference is in the jail settings and in one helper script.

JailApplies toRuleBan
mail-spray-guardaddresses outside your home countries1 failure in 1 day30 days
mail-spray-guard-homeeveryone8 failures in 10 minutes1 hour, growing to 1 week

The first jail uses fail2ban's ignorecommand: before banning, fail2ban runs a script with the address, and exit code 0 means "skip".

[mail-spray-guard]
enabled       = true
filter        = mail-spray-guard
logpath       = /var/log/maillog
maxretry      = 1
findtime      = 1d
bantime       = 30d
ignorecommand = /usr/local/sbin/msg-ignore-home <ip>

msg-ignore-home does three checks in order: is the address on the known-good list; is it in one of HOME_COUNTRIES (a lookup in a MaxMind-format country database with mmdblookup); and if the database does not know the address at all, it does not ban on a single attempt and leaves it to the home jail. That last choice trades a little coverage for never banning on missing data.

msg-goodips runs from cron once a day. It reads the last 14 days of mail logs, collects addresses with a successful IMAP, POP3, submission or SASL login, keeps only those in a home country, and writes them into a fail2ban ignoreip file. Both jails then skip those addresses.

The mistake that shaped the known-good list

Our first version of that list, written during the incident, included every address that had logged in successfully. It looked like the safe choice: you do not want to ban people who know their password. But the attacker also knew a password, taken earlier by a phishing email, and had logged in successfully from abroad. Our whitelist was protecting the attacker.

The fix is one line in msg-goodips: a successful login only makes an address "good" if it comes from a home country. A stolen password used from abroad never earns immunity. If you take one idea from this article, take that one: success is not the same as trust.

Install

Requirements: fail2ban 0.11 or newer, Dovecot and/or Postfix logging to one file, mmdblookup, and a country database in MaxMind format (GeoLite2-Country or the free DB-IP Lite country file).

git clone https://github.com/geotech-engineering/mail-spray-guard.git
cd mail-spray-guard
sudo cp mail-spray-guard.conf.example /etc/mail-spray-guard.conf   # set HOME_COUNTRIES
sudo ./install.sh

Before you trust it, run the filter against your own log and against the sample in the repository:

fail2ban-regex /var/log/maillog /etc/fail2ban/filter.d/mail-spray-guard.conf
fail2ban-regex tests/sample.log filter.d/mail-spray-guard.conf
# expected on the sample: 6 lines, 4 matched, 2 missed (the 2 successful logins)

On our production log the filter matched 543 lines where the stock Dovecot filter matched 528, because it also covers aborted logins and Postfix SASL in the same pass. To protect only some domains on a shared server, replace _domain in the filter with an alternation of your domains.

Measured result

The numbers below come from our own mail server, where the original version of this rule has run since 17 November 2026. That version is scoped to the one domain that was under attack and has a single home country; the repository is the same logic made configurable. The classic 8-failure jail runs on every mailbox.

DayBans, one-failure jailBans, classic jail
17 Nov (enabled at midday)2481
18 Nov570
19 Nov60
20 Nov10
21 Nov21

Two things stand out. First, the one-failure rule did the work: 314 bans against 2 for the classic rule over the same days. Second, the curve falls fast. Most of the botnet's addresses were burned on the first afternoon, and by the third day there were single-digit new arrivals. Whether the campaign moved on or ran low on fresh addresses, we cannot tell from our side.

False positives: of the 315 addresses on the ban list by the morning of 22 November, none is in the home country and 294 are in the United States, which matches the residential-proxy picture from the incident. The one case that would have been a false positive under a naive rule (the home-country address with 188 failures on 21 November) was skipped because it was on the known-good list. The known-good list on our server currently holds 546 entries.

What it does not do

Checklist

  1. Count how many of your failing addresses fail only once. If it is most of them, per-address thresholds are not protecting you.
  2. List the countries your users really log in from, and nothing else.
  3. Whitelist by successful logins from those countries, refreshed daily, never by all successful logins.
  4. Keep the classic rule for home-country traffic, with a growing ban time.
  5. Test the filter with fail2ban-regex on your own log before enabling.
  6. Alert on successful logins from new countries. That is the attack this rule cannot see.

Need this?

mail-spray-guard is free and stays free. If you would rather not run it yourself, GeoTech Sentinel is the managed version we run for the mail domains we host: the same geo-aware rules, a scan of every domain every four hours, automatic blocking, and a plain-language report per domain when something happens. Talk to us at geotech.dev. Issues and pull requests on the repository are welcome.