How to Protect MediaWiki Against Brute-Force Logins with Fail2Ban

Every public MediaWiki login form attracts credential-spraying and dictionary attacks. Strong passwords slow attackers but do not stop the attempts — which still cost CPU, database queries and user lockouts. The standard defense on a Linux host is fail2ban: it watches logs for failed logins and bans the source IP at the firewall. This guide covers the clean path: logging attempts with the Wiki2Ban extension, then filter + jail configuration.

1. Install Wiki2Ban

Wiki2Ban hooks into AuthManagerLoginAuthenticateAudit and writes one line per failed login. Install via Composer (it is not an extension in the classic sense — it lives on Packagist):

cat >> composer.local.json <<'EOF'
{
    "require": { "lucamauri/wiki2ban": "~1.0" }
}
EOF
composer install --no-dev

then load it in LocalSettings.php and point it at a log location fail2ban can read:

wfLoadExtension( 'Wiki2Ban' );
$wgW2BlogFilePath = '/var/log/mediawiki/wiki2ban.log';

mkdir -p /var/log/mediawiki
chown www-data:www-data /var/log/mediawiki

Every failed attempt now appends a line like 2026-08-15 01:00:00 FAILED LOGIN ATTEMPT by 203.0.113.5 to the log.

2. Alternative: no extension, the built-in log

MediaWiki already logs authentication failures on the authmanager channel. Enable channel logging without any extension:

$wgDebugLogGroups['authmanager'] = '/var/log/mediawiki/authmanager.log';

The log lines are less predictable across MediaWiki versions (failures are reported once on the authmanager channel per failed attempt, with varying messages), so the regex filter needs more care — Wiki2Ban's single-line format is the more reliable feedstock. Both approaches are valid; choose by how much post-upgrade log-drift you want to babysit.

3. fail2ban filter and jail

With Wiki2Ban's format, the filter is simple:

# /etc/fail2ban/filter.d/mediawiki.conf
[Definition]
failregex = FAILED LOGIN ATTEMPT by <HOST>

# /etc/fail2ban/jail.d/mediawiki.conf
[mediawiki]
enabled  = true
filter   = mediawiki
logpath  = /var/log/mediawiki/wiki2ban.log
datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S
maxretry = 5
findtime = 1h
bantime  = 1h

Restart and verify:

systemctl restart fail2ban
fail2ban-client status mediawiki

4. Tuning the thresholds

• maxretry — 3–5 failed attempts per hour per IP is already aggressive; legitimate users hit this rarely (and lose the password-reset mail). Lower values primarily catch bots
• bantime — 1 hour is the sane default; longer bans punish shared networks (corporate NAT, mobile carriers) that pool many users behind one IP
• findtime — 3600 s balances detection speed against noise
• Whitelist — ignoreip for your office/known monitors, so internal testing never locks you out

5. Defense in depth

fail2ban complements, not replaces, the in-wiki controls:

• MediaWiki rate limits — $wgRateLimits['badcaptcha'] and password-attempt throttling inside MediaWiki handle the same attacks app-level (useful even where fail2ban cannot run)
• Block reusability — the captured IPs can feed MediaWiki's $wgBlockDisablesLogin or local block list if you want the ban visible in-wiki
• Two-factor — fail2ban stops spray; a compromise of one credential stops only at 2FA (MediaWiki ships TOTP)
• Account policy — disable unused admin accounts; attacker enumeration focuses on them

The setup is a one-time job with a lasting effect: after the first hours, fail2ban bans the majority of scanner IPs at the firewall, and both the logs and the load stop accumulating. The Wiki2Ban page and fail2ban's own documentation cover the remaining details.