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.
TL;DR
- Spraying botnets rotate through residential proxies and try one password per address. A rule like "ban after 5 failures in 10 minutes" never fires.
- mail-spray-guard adds a second fail2ban jail: one failed login from outside your home countries = 30-day ban. Users at home are judged by the classic rule instead.
- Addresses with a successful login from a home country in the last 14 days are never banned. A successful login from abroad does not count, because attackers log in successfully too.
- It is four small files on top of stock fail2ban and a free country database. No new daemon, no cloud service.
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
- Lower the threshold to 1 for everyone. Every phone with an old saved password gets banned. In the same week one address in our home country failed 188 times in a single day: a user's device still trying a password that had been changed. A global "one strike" rule would have cut that office off.
- Block datacenter ranges. Residential proxies are home routers and phones. There is no range to block.
- Account lockout. At one attempt every few minutes the attacker stays under any lockout that does not also lock out the real owner, and lockouts turn spraying into a denial-of-service tool.
- A commercial mail-security gateway. It works, but for a small business on a single mail server the cost is out of proportion to the fix.
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.
| Jail | Applies to | Rule | Ban |
|---|---|---|---|
mail-spray-guard | addresses outside your home countries | 1 failure in 1 day | 30 days |
mail-spray-guard-home | everyone | 8 failures in 10 minutes | 1 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.
| Day | Bans, one-failure jail | Bans, classic jail |
|---|---|---|
| 17 Nov (enabled at midday) | 248 | 1 |
| 18 Nov | 57 | 0 |
| 19 Nov | 6 | 0 |
| 20 Nov | 1 | 0 |
| 21 Nov | 2 | 1 |
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
- Stolen passwords. If the password is already known, the attacker does not fail, so nothing fires. Watch successful logins from new countries as well. In our incident the way in was a phishing click, not the spray.
- Travellers. One typo from a hotel abroad bans that address for 30 days. Unban with
fail2ban-client set mail-spray-guard unbanip <ip>, or add the country. - Webmail. Webmail logs in from
127.0.0.1, so it is inALWAYS_IGNOREand needs its own login protection.
Checklist
- Count how many of your failing addresses fail only once. If it is most of them, per-address thresholds are not protecting you.
- List the countries your users really log in from, and nothing else.
- Whitelist by successful logins from those countries, refreshed daily, never by all successful logins.
- Keep the classic rule for home-country traffic, with a growing ban time.
- Test the filter with
fail2ban-regexon your own log before enabling. - 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.