{"id":20121820,"url":"https://github.com/parseword/fail2ban-abuseipdb","last_synced_at":"2025-05-06T16:32:15.844Z","repository":{"id":38261274,"uuid":"506480621","full_name":"parseword/fail2ban-abuseipdb","owner":"parseword","description":"An intermediary PHP script to submit sanitized fail2ban reports to AbuseIPDB","archived":false,"fork":false,"pushed_at":"2023-08-26T19:56:16.000Z","size":17,"stargazers_count":16,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-09T14:14:11.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parseword.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-23T03:11:06.000Z","updated_at":"2025-04-04T22:21:18.000Z","dependencies_parsed_at":"2024-11-13T19:34:14.036Z","dependency_job_id":"b10dda80-b6f6-4c64-93b1-d73c84b8ca83","html_url":"https://github.com/parseword/fail2ban-abuseipdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Ffail2ban-abuseipdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Ffail2ban-abuseipdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Ffail2ban-abuseipdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Ffail2ban-abuseipdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parseword","download_url":"https://codeload.github.com/parseword/fail2ban-abuseipdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252721083,"owners_count":21793748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T19:32:48.176Z","updated_at":"2025-05-06T16:32:15.564Z","avatar_url":"https://github.com/parseword.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fail2ban-abuseipdb\n\nThis repository contains an intermediary PHP \"helper\" script (and configuration) \nfor submitting sanitized [fail2ban](https://github.com/fail2ban/fail2ban/) \nevents to the [AbuseIPDB](https://abuseipdb.com) abuse reporting system.\n\nThis is the code that used to live on wiki.shaunc.com until I shut that down\ndue (ironically) to relentless abuse from spambots. This code is licensed\nunder the GPLv2, same as fail2ban itself, and can be freely incorporated into\nany project with a GPLv2-compliant license.\n\n## Background\n\nfail2ban is a utility that parses various system and software log files looking\nfor signs of network abuse, and then firewalls out the offending IP addresses.\nIt's becoming more common to crowdsource these incidents to centralized databases,\nso administrators can watch for patterns of abuse or pre-emptively block known\nmalicious IPs. One of these efforts is [AbuseIPDB](https://abuseipdb.com).\n\nfail2ban now comes with an action file for AbuseIPDB and it can be configured\nto report events there out-of-the-box. However, that action definition\nsubmits your log excerpts **verbatim** directly to AbuseIPDB. These reports\nare public, and system log lines can contain sensitive information. I needed\na way to sanitize and redact these reports, so I wrote a helper script.\n\nInstead of submitting reports directly to AbuseIPDB, a PHP script running on a\nweb server you control is used as an intermediary: \n\n1. fail2ban submits its data to the PHP script on your server;\n2. The PHP script performs whatever scrubbing/redaction you need it to do;\n3. The report is then passed on to AbuseIPDB.\n\nThis way, you can avoid having sensitive information like email addresses, \nserver names, etc. showing up in your public AbuseIPDB reports. If you know PHP,\nyou can tweak the helper script to perform other tasks, too; for example, \nmine also logs everything to a separate MySQL database.\n\n## Requirements\n\nYou'll need to have:\n\n- One system running a web server like Apache or Nginx, with support for PHP \n(mod_php, PHP-FPM, etc.). PHP must have the cURL functions enabled.\n\n- One or more systems running fail2ban.\n\n- A registered AbuseIPDB account and its associated API key.\n\nThe fail2ban program on your client system(s) will send HTTP POST requests to the \nPHP script running on your web server. That script will do some sanitizing and\nredaction on your logs, and then submit the cleaned report to AbuseIPDB.\n\n## Installing / Configuring\n\nTo get things up and running, follow these instructions.\n\n### Register for AbuseIPDB\n\nIf you don't already have an AbuseIPDB account, visit [their site](https://abuseipdb.com/) \nto register. Once you have an account, login and go \nto [https://www.abuseipdb.com/account/api](https://www.abuseipdb.com/account/api) \nto obtain your API key.\n\n### Set up your web environment\n\nCreate a directory somewhere in your web server's document root to hold the\nPHP script and its config file. You only need to do this once. If you have \nmultiple servers running fail2ban, you'll point them all at the same URL.\n\nFor purposes of these instructions, let's assume you called your new\ndirectory `abusereport` and the corresponding URL is `https://your.example.com/abusereport/`.\n\nThis directory needs to be accessible to your servers that run fail2ban, but it \nshouldn't be accessible to anyone else. You don't want some moron to discover\nit and submit bogus abuse reports with your API key. It's wise to use .htaccess\nor some other mechanism to restrict access to this directory by IP address.\n\n### Install the intermediary script\n\nPlace the `abuseipdb-report-v2.php` and `config.php` files in your `abusereport`\ndirectory.\n\nEdit `config.php` so it includes your AbuseIPDB API key.\n\nAlso in `config.php` is an array called `$filters`. This array manages the\nredactions that the script will perform on your log excerpts. AbuseIPDB reports \nare public, and system log lines can contain sensitive information. You should\nedit the `$filters` array to include whatever strings you don't want to show\nup in your public AbuseIPDB reports. \n\nFor example, a `$filters` array like this would strip out a server's hostname\nand IP address from any logs:\n\n```php\n$filters = [\n    '192.168.69.1',\n    'chungus.example.com',\n];\n```\n\n### Install the abuseipdb.local action file\n\nPlace the `abuseipdb.local` file into fail2ban's action definition directory. This is\nprobably at `/etc/fail2ban/action.d/` but your mileage may vary. When fail2ban\nsees you have an `abuseipdb.local` file, it will use that one instead of the\ndefault `abuseipdb.conf`.\n\nEdit the `abuseipdb.local` file and find the `[Init]` section at the bottom.\nChange the `helper_script_url` option so it points to your copy of the PHP \nscript. The URL should be in quotes. Here's an example:\n\n    [Init]\n    # Option:  helper_script_url\n    # Notes:   The URL to the helper PHP script on your web server\n    # Values:  STRING\n    helper_script_url = \"http://your.example.com/abusereport/abuseipdb-report-v2.php\"\n\n### Edit fail2ban's jail.local file\n\nLocate fail2ban's `jail.local` file and make a backup copy of it. The file is\nprobably in `/etc/fail2ban` but your mileage may vary. \n\nAfter making a backup, edit the file and ensure the \"ACTIONS\" section near\nthe top contains this line:\n\n`action_abuseipdb = abuseipdb`\n\nThis line defines the `action_abuseipdb` action. Now you need to tell fail2ban\nto use it. In the \"JAILS\" section of the `jail.local` file, you can configure\nindividual jails to use `action_abuseipdb`. When calling this action, you must\nspecify one or more [AbuseIPDB category IDs](https://abuseipdb.com/categories). \n\nFor example, here's a jail config for sshd:\n\n    [sshd]\n    mode    = aggressive\n    enabled = true\n    backend = gamin\n    port    = ssh\n    findtime = 7200\n    bantime = 1209600\n    logpath = %(sshd_log)s\n    action  = %(action_mwl)s\n              %(action_abuseipdb)s[abuseipdb_category=\"18,22\"]\n\nHere you can see there are two actions configured. The first is `action_mwl` which\nis a fail2ban built-in action that sends an email notification. Next is `action_abuseipdb` \nwhich causes fail2ban to send an HTTP POST request to the PHP script URL you \nspecified in `abuseipdb.local`.\n\nNotice how the categories are passed into the action. This is critical because\nthe PHP script won't do anything without at least one category ID. AbuseIPDB\nhas defined a bunch of [category IDs](https://abuseipdb.com/categories) you can\nuse for different types of reports. This jail is set to use categories 18 \n(brute-force) and 22 (SSH).\n\n### Restart fail2ban\n\nRestart fail2ban, however that's done on your machine, or else just reboot the\nmachine. Inspect fail2ban's log file for any error messages. You can login to\nyour AbuseIPDB account and check out your [reports page](https://www.abuseipdb.com/account/reports)\nto see whether the reports are being submitted properly.\n\n### (Optional) SELinux module installation\n\n**This step will not be required for most users**. Don't perform this step\nunless you know for sure that SELinux is the problem.\n\nIf you're running fail2ban on a server where SELinux is enforcing, you may\nencounter problems with this setup. That's because we're doing things that the\nstock fail2ban and its SELinux policies weren't necessarily designed to do. \nSELinux-related errors will appear in `/var/log/messages` \nand `/var/log/audit/audit.log`, or the equivalent on your OS.\n\nYou can try installing the `fail2ban-selinux` package (RHEL/CentOS), which \ncontains additional SELinux policies. This may not be sufficient in some cases, \nparticularly if you've compiled your own PHP binary. If you're still running \ninto SELinux errors, this repository contains a custom SELinux policy module \nthat might help. To install it,\n\n1. Copy the `custom-fail2ban.te` file to `/tmp`\n\n2. Run the following commands:\n\n```bash\n/usr/bin/checkmodule -M -m -o /tmp/custom-fail2ban.mod /tmp/custom-fail2ban.te\n/usr/bin/semodule_package -o /tmp/custom-fail2ban.pp -m /tmp/custom-fail2ban.mod\n/usr/sbin/semodule -i /tmp/custom-fail2ban.pp\n```\n\n## This $#!7 Sucks And Doesn't Work!!!\n\nYou can [open a GitHub issue](https://github.com/parseword/fail2ban-abuseipdb/issues/new) \nand I'll try to check it out. Please note this project is pretty low on my \npriority list and I might not address your ticket right away.\n\n## Disclaimer\n\nI'm not affiliated with fail2ban or AbuseIPDB. These projects and their names \nare the property of their respective owners.\n\n## Author\n\nShaun Cummiskey    \nWeb: [https://shaunc.com/](https://shaunc.com/)    \nEmail: shaun {at} shaunc.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseword%2Ffail2ban-abuseipdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparseword%2Ffail2ban-abuseipdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseword%2Ffail2ban-abuseipdb/lists"}