This repository contains an intermediary PHP "helper" script (and configuration) for submitting sanitized fail2ban events to the AbuseIPDB abuse reporting system.
This is the code that used to live on wiki.shaunc.com until I shut that down due (ironically) to relentless abuse from spambots. This code is licensed under the GPLv2, same as fail2ban itself, and can be freely incorporated into any project with a GPLv2-compliant license.
fail2ban is a utility that parses various system and software log files looking for signs of network abuse, and then firewalls out the offending IP addresses. It's becoming more common to crowdsource these incidents to centralized databases, so administrators can watch for patterns of abuse or pre-emptively block known malicious IPs. One of these efforts is AbuseIPDB.
fail2ban now comes with an action file for AbuseIPDB and it can be configured to report events there out-of-the-box. However, that action definition submits your log excerpts verbatim directly to AbuseIPDB. These reports are public, and system log lines can contain sensitive information. I needed a way to sanitize and redact these reports, so I wrote a helper script.
Instead of submitting reports directly to AbuseIPDB, a PHP script running on a web server you control is used as an intermediary:
This way, you can avoid having sensitive information like email addresses, server names, etc. showing up in your public AbuseIPDB reports. If you know PHP, you can tweak the helper script to perform other tasks, too; for example, mine also logs everything to a separate MySQL database.
You'll need to have:
One system running a web server like Apache or Nginx, with support for PHP (mod_php, PHP-FPM, etc.). PHP must have the cURL functions enabled.
One or more systems running fail2ban.
A registered AbuseIPDB account and its associated API key.
The fail2ban program on your client system(s) will send HTTP POST requests to the PHP script running on your web server. That script will do some sanitizing and redaction on your logs, and then submit the cleaned report to AbuseIPDB.
To get things up and running, follow these instructions.
If you don't already have an AbuseIPDB account, visit their site to register. Once you have an account, login and go to https://www.abuseipdb.com/account/api to obtain your API key.
Create a directory somewhere in your web server's document root to hold the PHP script and its config file. You only need to do this once. If you have multiple servers running fail2ban, you'll point them all at the same URL.
For purposes of these instructions, let's assume you called your new
directory abusereport and the corresponding URL is https://your.example.com/abusereport/.
This directory needs to be accessible to your servers that run fail2ban, but it shouldn't be accessible to anyone else. You don't want some moron to discover it and submit bogus abuse reports with your API key. It's wise to use .htaccess or some other mechanism to restrict access to this directory by IP address.
Place the abuseipdb-report-v2.php and config.php files in your abusereport
directory.
Edit config.php so it includes your AbuseIPDB API key.
Also in config.php is an array called $filters. This array manages the
redactions that the script will perform on your log excerpts. AbuseIPDB reports
are public, and system log lines can contain sensitive information. You should
edit the $filters array to include whatever strings you don't want to show
up in your public AbuseIPDB reports.
For example, a $filters array like this would strip out a server's hostname
and IP address from any logs:
$filters = [
'192.168.69.1',
'chungus.example.com',
];Place the abuseipdb.local file into fail2ban's action definition directory. This is
probably at /etc/fail2ban/action.d/ but your mileage may vary. When fail2ban
sees you have an abuseipdb.local file, it will use that one instead of the
default abuseipdb.conf.
Edit the abuseipdb.local file and find the [Init] section at the bottom.
Change the helper_script_url option so it points to your copy of the PHP
script. The URL should be in quotes. Here's an example:
[Init]
# Option: helper_script_url
# Notes: The URL to the helper PHP script on your web server
# Values: STRING
helper_script_url = "http://your.example.com/abusereport/abuseipdb-report-v2.php"Locate fail2ban's jail.local file and make a backup copy of it. The file is
probably in /etc/fail2ban but your mileage may vary.
After making a backup, edit the file and ensure the "ACTIONS" section near the top contains this line:
action_abuseipdb = abuseipdb
This line defines the action_abuseipdb action. Now you need to tell fail2ban
to use it. In the "JAILS" section of the jail.local file, you can configure
individual jails to use action_abuseipdb. When calling this action, you must
specify one or more AbuseIPDB category IDs.
For example, here's a jail config for sshd:
[sshd]
mode = aggressive
enabled = true
backend = gamin
port = ssh
findtime = 7200
bantime = 1209600
logpath = %(sshd_log)s
action = %(action_mwl)s
%(action_abuseipdb)s[abuseipdb_category="18,22"]Here you can see there are two actions configured. The first is action_mwl which
is a fail2ban built-in action that sends an email notification. Next is action_abuseipdb
which causes fail2ban to send an HTTP POST request to the PHP script URL you
specified in abuseipdb.local.
Notice how the categories are passed into the action. This is critical because the PHP script won't do anything without at least one category ID. AbuseIPDB has defined a bunch of category IDs you can use for different types of reports. This jail is set to use categories 18 (brute-force) and 22 (SSH).
Restart fail2ban, however that's done on your machine, or else just reboot the machine. Inspect fail2ban's log file for any error messages. You can login to your AbuseIPDB account and check out your reports page to see whether the reports are being submitted properly.
This step will not be required for most users. Don't perform this step unless you know for sure that SELinux is the problem.
If you're running fail2ban on a server where SELinux is enforcing, you may
encounter problems with this setup. That's because we're doing things that the
stock fail2ban and its SELinux policies weren't necessarily designed to do.
SELinux-related errors will appear in /var/log/messages
and /var/log/audit/audit.log, or the equivalent on your OS.
You can try installing the fail2ban-selinux package (RHEL/CentOS), which
contains additional SELinux policies. This may not be sufficient in some cases,
particularly if you've compiled your own PHP binary. If you're still running
into SELinux errors, this repository contains a custom SELinux policy module
that might help. To install it,
Copy the custom-fail2ban.te file to /tmp
Run the following commands:
/usr/bin/checkmodule -M -m -o /tmp/custom-fail2ban.mod /tmp/custom-fail2ban.te
/usr/bin/semodule_package -o /tmp/custom-fail2ban.pp -m /tmp/custom-fail2ban.mod
/usr/sbin/semodule -i /tmp/custom-fail2ban.ppYou can open a GitHub issue and I'll try to check it out. Please note this project is pretty low on my priority list and I might not address your ticket right away.
I'm not affiliated with fail2ban or AbuseIPDB. These projects and their names are the property of their respective owners.
Shaun Cummiskey
Web: https://shaunc.com/
Email: shaun {at} shaunc.com