Enterprise-Grade Intrusion Detection System Management Platform
Fail2Ban UI is a management platform for operating Fail2Ban across one or more Linux hosts. It provides a central place to review bans, search and unban IP addresses, manage jails and filters, and receive notifications.
The project is maintained by Swissmakers GmbH and released under AGPL-3.0.
Quick start - Documentation - Configuration reference - Architecture - Screenshots
Fail2Ban UI does not replace Fail2Ban. Ban decisions are still made by the Fail2Ban daemon on each host. The UI connects to existing instances and adds:
- A dashboard of active jails and recent ban/unban activity, updated in real time over WebSocket
- A server manager for local, SSH-connected, and agent-connected Fail2Ban instances
- Centralized search, ban, and unban operations across all jails and servers
- Remote jail and filter configuration management (depending on connector capabilities)
- Filter debugging with live log-pattern testing
- Ban insights with a Kibana-like ban/unban timeline, incident comparison to isolate repeat attackers, one-click permanent blocking of a whole time range, and country-level analytics
- Recurring-offender handling with permanent blocks on MikroTik, pfSense, and OPNsense
- Persistent event history and permanent-block records, with data management built in
- Configurable alerts over Email (SMTP), Webhook, and Elasticsearch, with GeoIP/Whois enrichment and country filtering
- Optional OIDC login (Keycloak, Authentik, Pocket-ID)
- Least-privilege, SELinux-aware deployment patterns
The UI runs as a single Go binary, in a container or as a systemd service. Two independent data paths connect it to the managed hosts:
- Control path (blue) - Fail2ban UI manages each Fail2Ban instance through one of three connectors (see below): reading jail status, banning and unbanning, editing configuration, restarting the service.
- Event path (green) - a custom Fail2Ban action on each host posts every ban and unban event back to the UI over HTTP, authenticated by a shared callback secret. The UI stores the event, broadcasts it to connected browsers, and triggers alerts and advanced actions.
See docs/architecture.md for the data-flow description.
| Connector | Typical use | Notes |
|---|---|---|
| Local | Fail2Ban runs on the same host as the UI | Uses the Fail2Ban Unix socket and local files |
| SSH | Manage remote hosts without installing an agent | Key-based SSH and remote fail2ban-client; requires a dedicated service account with minimal sudo rules. Can optionally open a reverse SSH tunnel so ban callbacks reach the UI from hosts that cannot connect to it directly (NAT, isolated DMZ) |
| Agent | Environments where SSH from the UI host is not desired | HTTP agent runs on the Fail2Ban host; see fail2ban-ui-agent and the prebuilt image swissmakers/fail2ban-ui-agent |
- A Linux host with Podman or Docker
- For a local Fail2Ban instance: access to
/etc/fail2banand/var/run/fail2banfrom the container
Run the container with the local connector:
podman run -d --name fail2ban-ui --network=host \
-v /opt/fail2ban-ui:/config:Z \
-v /etc/fail2ban:/etc/fail2ban:Z \
-v /var/run/fail2ban:/var/run/fail2ban \
-v /var/log:/var/log:ro \
swissmakers/fail2ban-ui:latest- Open
http://localhost:8080. - In the UI, go to Settings -> Manage Servers, enable the local connector, and click Test connection.
For Compose, systemd, SELinux, and the remote connectors, see the documentation below.
- Installation
- Configuration reference - environment variables, callback URL and secret, OIDC
- Architecture overview
- Reverse proxy guide
- Security guidance - recommended deployment posture
- Alert providers - Email, Webhook, Elasticsearch
- Threat intelligence - AlienVault OTX, AbuseIPDB
- Webhook integration guide
- API reference
- Troubleshooting
Deployment guides in this repository:
- Container: deployment/container/README.md
- systemd: deployment/systemd/README.md
- Optional container SELinux modules (socket/log access): deployment/container/SELinux/ - host-side Fail2Ban
curlcallbacks often need thenis_enabledboolean instead; see docs/security.md
Development and testing stacks:
- OIDC dev stack: development/oidc/README.md
- SSH and local connector dev stack: development/ssh_and_local/README.md
Think before exposing the UI:
- Do not expose your Fail2ban-UI directly to the public Internet. Place it behind a reverse proxy, VPN, or firewall rules, and enable OIDC where possible.
- The SSH connector should use a dedicated service account with minimal sudo permissions and ACLs - at minimum
sudo fail2ban-client *andsudo systemctl restart fail2ban. - All IP addresses are validated with strict IPv4/IPv6/CIDR parsing before they reach any integration or command, which prevents command injection.
- WebSocket connections are protected by same-origin validation and require authentication when OIDC is enabled.
- For production proxy examples and WebSocket requirements, see docs/reverse-proxy.md.
See docs/security.md for details.
A set of screenshots is available in screenshots/
Overview of all active jails, banned IPs, and real-time statistics, total bans, recent activity, and quick access to the main features.
Unban an IP address directly from the dashboard. A confirmation dialog shows the affected jail before the unban runs.
Server management modal for configuring / adding and managing multiple Fail2Ban instances. Supports local, SSH, and API agent connections.
Overview of all configured jails with their enabled/disabled status. Allows centralized management of jail configurations across multiple servers.
Clicking Edit Filter / Jail opens the configuration editor. Edit the jail and filter settings, add or change log paths and test them, then save -> the change is pushed to the managed host and Fail2Ban is reloaded.
Logpath testing resolves the configured paths, including wildcards and Fail2Ban variables, and reports one of three results per path: found (green, with the matched files), not found (red), or cannot verify (yellow). The yellow state means the connector's SSH user cannot read the log directory. It is a warning, not a failure. Fail2Ban runs as root on the managed host and will still read the path, so the jail can be enabled.
The first button opens the modal for creating new Fail2Ban filter files. Includes filter configuration editor with syntax highlighting and validation.
The second button opens the jail creation modal for setting up new jails. It supports separate jail definitions with custom parameters and filter selection.
Search for an IP address across all active jails of every configured server. The result lists each jail that currently bans the address, so it can be unbanned in the right place.
Comprehensive log overview showing ban / unban events, timestamps, and associated jails and recurring offenders. Provides detailed information about past security events.
Whois lookup modal displaying detailed information about banned IP addresses, including geographic location, ISP details, and network information.
Detailed ban log view showing log lines that triggered the ban, timestamps, and context information for each security event.
Ban Insights brings SIEM-like analysis to environments without a full SIEM. The ban and unban activity timeline works similar like the one in Kibana -> drag to zoom into a time range, use presets from 8 hours to 30 days, or define a custom range of up to 12 months, so spikes and attack patterns become visible at a glance.
Typical workflows:
- Correlate two incidents. Pin one spike as Incident A and another as Incident B -> for example, last week's attack and this week's. The incident compare lists the IPs present in both. Addresses that return across incidents are repeat attackers rather than false positives, and can be banned permanently right to the recurring-offenders list.
- Block a botnet in one click. Select a time range in which no legitimate user is normally active, such as a nightly spike, and permanently block every IP in it on the configured firewall integration (MikroTik, pfSense, OPNsense).
The modal also suggests similar past periods, exports IP lists as CSV or JSON, and shows country-level analytics on an interactive 3D globe together with the top recurring IPs.
Filter debugging interface for testing Fail2Ban filter regex patterns against log lines. Helps validate filter configurations before deployment.
Results from filter testing showing matched lines, regex performance, and validation feedback. Displays which log lines match the filter pattern.
Main settings page with sections for different configuration categories including general settings, advanced ban actions, alert settings, and global fail2ban settings.
When enabled, the debug console streams the live application log into the browser -> useful for troubleshooting without querying the container logs manually. Leave it disabled in normal operation.
Permanent blocking, firewall integrations (MikroTik, pfSense, OPNsense), and recurring-offender thresholds.
Three alert providers, Email (SMTP), Webhook, and Elasticsearch, with country filtering, GeoIP provider selection, and per-event toggles. See docs/alert-providers.md.
Global Fail2Ban defaults: bantime, findtime, maxretry, and the banaction backend (nftables, firewalld, iptables). When bantime increment is enabled, the escalation behavior can be tuned with bantime.rndtime, bantime.maxtime (cap for escalating bans), bantime.factor (escalation multiplier), and bantime.overalljails (count repeat offenses across all jails).
Documentation and deployment guidance in security tooling is never "done", and engineers are not always the fastest at writing it down in docs.
If you see a clearer way to describe installation steps, safer container defaults, better reverse-proxy examples, SELinux improvements, or a more practical demo environment, please contribute. Small improvements (typos, wording, examples) are just as valuable as code changes.
To add a UI language: copy pkg/web/locales/en.json, translate all values, save it as pkg/web/locales/<lang>.json, and open a pull request. Use a lowercase locale code for <lang>, for example ch, ch_de, es, or pt_br.
See CONTRIBUTING.md for details.
AGPL-3.0. See LICENSE.