Offenders is a terminal-first investigation and diagnostics tool for Fail2Ban.
Combine historical ban activity with current jail state, investigate IPs and jails,
and explore IP/ASN/Country summaries over SSH or in a local Linux terminal.
Use explicit Registration/RDNS lookups, optional GeoIP, manual Coverage and
validation, CSV Export, and global contextual ? Help.
Current Offenders dashboard using synthetic documentation data.
- Export a committed report with
e, or acquire one fresh CSV bundle withoffenders export --period 30d(see Usage). - Press
? Helpfrom any product screen for contextual controls and a concise in-app guide;Esc/qreturns to your place. - Explore rolling history periods, live jail status, and IP/ASN/Country summaries.
- Filter loaded results and investigate individual jails and IPs.
- Review Coverage evidence and explicitly validate copy-only filter candidates.
- Open manual
n Enforcementto compare fresh current bans with supported nftables, iptables or UFW rule evidence; direct observation is not packet or reachability proof (see Usage).
Reports and investigation are read-only with respect to Fail2Ban configuration and bans. There is no ban/unban action or automatic Fail2Ban mutation. Coverage never installs filters/jails or enables/reloads Fail2Ban. Persistent application changes are limited to explicit or opt-in GeoIP data/policy under your XDG data root; validation also uses temporary local sample files.
Supported baseline: Ubuntu 24.04 / Python >=3.12 / Fail2Ban 1.0.2. Qualified stock Enforcement action versions: 1.0.2, 1.1.0 and 1.1.1; support remains limited to recognized runtime shapes and fails closed. Fail2Ban, readable logs, and narrowly scoped noninteractive sudo permissions must be supplied separately; see installation and permissions.
Before installing or upgrading from PyPI, update OS certificates and securely bootstrap pipx's shared pip. This is required for existing environments too; upgrading Offenders alone does not update pip's embedded CA bundle. Then run:
pipx install offenders
offendersRun offenders --help (or -h) to discover commands and their option help;
offenders --version (or -V) reports the installed version. These standalone
forms exit without launching the TUI or acquiring data.
GeoIP enrichment is optional. Installation downloads no databases; an explicit update fetches DB-IP Lite, and automatic updates require opt-in. See the GeoIP guide for lifecycle and attribution. Coverage analysis and validation are explicit, manual, and copy-only; a sample match never establishes filter safety. See Coverage.
Operator documentation · PyPI · Releases · Changelog · Development · MIT license