Repository navigation
Home
Asynchronous fail2ban → AbuseIPDB reporting. Every ban is queued locally in SQLite and turned into a rich, evidence-backed abuse report on a schedule — without slowing down, breaking or flooding the ban path.
|
|
|
|
|
Fail2Ban already knows who attacked and why. AbuseIPDB wants a short factual report per abusive IP. The stock integration runs curl inside the ban action, which couples the ban, the network and the API: a slow API delays bans, a rate limit makes them fail, a restart re-reports everything, and <matches> (attacker-controlled log text) is interpolated into a root shell command.
This project separates the two paths. The ban stays local and instant; a small SQLite queue stores what happened; a scheduled worker (systemd timer or cron, every 16 minutes) builds the report from fail2ban's own evidence, respects AbuseIPDB limits and retries failures. The API key lives in its own file, and abuseipdb-upgrade can update the installation from GitHub without losing key, configuration, queue or jail list.
fail2ban ──► nftables ban (instant)
└──────► abuseipdb-async action ──► SQLite queue ──► worker (16 min) ──► AbuseIPDB
▲ │
└── retries ─────┘
| 🔌 Any jail |
sshd, nginx filters, proftpd, exim-*, custom filters — the action is attached to the jails you list. |
| 🧱 Zero dependencies | Python standard library only; ~13 MB RSS per run; no daemons. |
| 🗄️ Durable queue | SQLite/WAL on disk, survives reboots and fail2ban restarts (norestored = 1). |
| 🚦 Rate-limit aware | One report per IP per 20 minutes, 900/day, 25/run — inside the free AbuseIPDB plan. |
| 🧾 Evidence-backed comments | Attack type, time window, ban duration, counters, patterns and the attacker's own URLs read from fail2ban's database. |
| 🔑 Key file |
/etc/abuseipdb/.abuseipdb.key (mode 600), never part of config, code or release archive. |
| 👋 First-run wizard | No key? An interactive run asks once and saves it; systemd/cron never hangs. |
| 🔄 Self-update |
abuseipdb-upgrade --check/--upgrade, SHA-256-verified release archives, key/config/queue preserved. |
| 📣 Self-advertising footer | Every report ends with Reported via Fail2Ban_AbuseIPDB Monitor: … (configurable). |
| 🧪 Tested | 88 unit/integration tests, shellcheck, staged install and a real self-update in CI. |
| OS | Linux with systemd (recommended) or cron |
| Python | 3.9+ (standard library only) |
| Fail2Ban | 0.10+ (tested on 1.1.0) |
| Privileges | root for installation; the worker runs as root via a hardened oneshot unit |
| Account | a free AbuseIPDB API key |
Full details: Getting Started.
Fail2Ban_AbuseIPDB/
├─ install.sh / uninstall.sh production installer: backups, key file, state, uninstall
├─ bin/ abuseipdb-report · abuseipdb-enqueue · abuseipdb-upgrade
├─ src/abuseipdb_reporter/ stdlib-only package (queue, reporter, evidence, keys, updater)
├─ config/reporter.conf.example annotated configuration
├─ fail2ban/ action.d + jail.d template
├─ systemd/ · cron/ · logrotate/ scheduling and log rotation
├─ tests/ unit tests + mock-API integration test
├─ tools/mock_abuseipdb.py local AbuseIPDB stand-in for tests/demos
├─ docs/ install, configuration, architecture, updater, troubleshooting
└─ updater.json release manifest used by abuseipdb-upgrade
Honesty corner. Reports are public. They contain the attacker's IP, jail, counters and (for web jails) the attacker's own request URLs; attempted usernames, mail content and client domains are deliberately excluded. The updater requires a SHA-256 checksum but trusts the manifest over HTTPS; automatic background updates are deliberately not provided. Details in Security and Self-Update.
Wiki language: English. Every command in this wiki was executed against the published release (v1.1.1) or against a staging installation on a Linux host; measured caveats are marked where they matter.