lucamauri / wiki2ban
Log failed MediaWiki login attempts to a file consumable by Fail2Ban
Maintainers
Package info
Type:mediawiki-extension
pkg:composer/lucamauri/wiki2ban
README
Wiki2Ban
Wiki2Ban (W2B) is a MediaWiki extension that logs failed authentication attempts to a file that Fail2Ban can read, enabling automatic IP banning of attackers.
This extension is inspired by Extension:Fail2banlog, which is unmaintained and built for an older MediaWiki version. Wiki2Ban was written from scratch by Luca Mauri, originally for WikiTrek, and released as open source for the broader MediaWiki community.
Features
- Hooks into MediaWiki's authentication system to detect failed login attempts
- Writes a structured log line for each failure, including timestamp, username, wiki name, and client IP address
- Correctly resolves the client IP address behind reverse proxies and CDNs
- Log format is compatible with Fail2Ban out of the box
- Includes ready-to-use Fail2Ban filter and jail configuration files
- Includes an optional Log Navigator format definition for interactive log analysis
- No database changes required
- Configurable log file path
Requirements
- MediaWiki >= 1.42.0
- PHP >= 8.4
- Fail2Ban >= 0.10 (for progressive banning support)
Installation
The easiest way to install the extension is via Composer, which will automatically resolve all dependencies.
Add the following to composer.local.json at the root of your MediaWiki installation (create the file if it does not exist):
{
"require": {
"lucamauri/wiki2ban": "~1.1"
},
"extra": {
"merge-plugin": {
"include": []
}
}
}
Then run Composer from the root of your MediaWiki installation:
composer install --no-dev
Add the following line near the rest of the extension loading calls in LocalSettings.php:
wfLoadExtension('Wiki2ban');
Then add the configuration parameters described in the next section.
Configuration
Add the following to LocalSettings.php:
$wgW2BLogFilePath = "/var/log/mediawiki/wiki2ban.log";
$wgW2BLogFilePath
The full path to the log file that Wiki2Ban will write to and that Fail2Ban will monitor. The web server process must have write permission to this file and its parent directory.
Default value: /var/log/mediawiki/wiki2ban.log
Fail2Ban configuration
After installing and configuring the extension, you need to configure Fail2Ban to monitor the log file. The f2bconf/ directory in this repository contains ready-to-use configuration files.
Filter
Copy f2bconf/w2bfilter.conf to Fail2Ban's filter directory:
cp f2bconf/w2bfilter.conf /etc/fail2ban/filter.d/w2bfilter.conf
Jail rule
Copy f2bconf/w2brule.conf to Fail2Ban's jail directory:
cp f2bconf/w2brule.conf /etc/fail2ban/jail.d/wiki2ban.conf
Then edit the file to set logpath to match the value of $wgW2BLogFilePath in your LocalSettings.php.
Tuning for production
The default rule triggers after 5 failed attempts in 60 seconds and bans for 10 minutes. For a production wiki exposed to the internet, consider stricter values:
maxretry = 3 findtime = 300 bantime = 86400
This bans an IP for 24 hours after 3 failures within 5 minutes. Progressive banning is enabled by default in the provided configuration — each repeated offence doubles the ban duration up to a maximum of one week.
After making changes, reload Fail2Ban:
sudo systemctl reload fail2ban
Troubleshooting
To capture detailed debug log messages from Wiki2Ban, add the following to LocalSettings.php:
$wgShowExceptionDetails = true; $wgDebugLogGroups['Wiki2Ban'] = "/var/log/mediawiki/Wiki2Ban-{$wgDBname}.log";
Optional: Log Navigator format
f2bconf/wiki2ban.json is a format definition for the Log Navigator application, which allows interactive exploration and filtering of the Wiki2Ban log file. See the lnav format documentation for installation instructions.
License
GNU General Public License, version 2 or later