Enterprise-Grade Intrusion Detection System Management Platform
Swissmade open-source solution for centralized Fail2Ban management across distributed infrastructure
Quick Start • Documentation • Configuration Reference • Screenshots
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 IPs, manage jails and filters, and receive notifications.
The project is maintained by Swissmakers GmbH and released under GPL-3.0.
Fail2Ban UI does not replace Fail2Ban. It connects to existing Fail2Ban instances and adds:
- A Dashboard for active jails and recent ban/unban activity with real-time WebSocket updates
- Server Manager for adding new fail2ban servers to Fail2ban-UI
- Central search and unban / ban across jails and servers
- Remote editing / creating, of jail/filter configuration (depending on connector)
- Filter debug integration and live log-pattern testing
- Ban Insights with an interactive 3D threat globe showing blocks per country
- Advanced ban actions for recurring offenders e.g. automatically ban on pfSense, Mikrotik, or OPNsense when threshold is reached
- Data management possibility for permanent block logs and stored ban events
- Configurable alert notifications (Email/SMTP, Webhook, or Elasticsearch) with GeoIP/Whois enrichment and country-based filtering
- Optional OIDC login (Keycloak, Authentik, Pocket-ID)
- Least-privilege, SELinux-aware container deployment (policies provided)
- .. and much more to come.
| Connector | Typical use | Notes |
|---|---|---|
| Local | Fail2Ban runs on the same host as the UI | Uses the Fail2Ban socket and local files |
| SSH | Manage remote Fail2Ban hosts without installing an agent | Uses key-based SSH, remote sudo fail2ban-client, and sudo systemctl restart fail2ban (with reload fallback) |
| Agent (technical preview) | Environments where SSH is not desired | Limited functionality; work in progress |
Prerequisites:
- A Linux host with Podman or Docker
- If you manage a local Fail2Ban instance: access to
/etc/fail2banand/var/run/fail2banis needed by Fail2ban-UI
Procedure (local connector example):
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:latestVerification:
- Open
http://localhost:8080 - In the UI: Settings → Manage Servers → enable "Local connector” and run "Test connection”
Next steps:
- For Compose, systemd, SELinux, and remote connectors, see the documentation links below.
- Installation:
docs/installation.md - Configuration reference (env vars, callback URL/secret, OIDC):
docs/configuration.md - Security guidance (recommended deployment posture):
docs/security.md - Architecture overview:
docs/architecture.md - API reference:
docs/api.md - Alert providers (Email, Webhook, Elasticsearch):
docs/alert-providers.md - Threat intelligence (AlienVault OTX / AbuseIPDB):
docs/threat-intel.md - Troubleshooting:
docs/troubleshooting.md
Existing deployment guides in this repository:
- Container:
deployment/container/README.md - systemd:
deployment/systemd/README.md - SELinux policies:
deployment/container/SELinux/
Development / testing stacks:
- OIDC dev stack:
development/oidc/README.md - SSH and local connector dev stack:
development/ssh_and_local/README.md
A set of screenshots is available in screenshots/
The main dashboard view showing an overview of all active jails, banned IPs, and real-time statistics. Displays total bans, recent activity, and quick access to key features.
Unbanning a IP addresses directly from the dashboard. Shows the unban confirmation dialog.
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.
When clicking on "Edit Filter / Jail" the Jail configuration editor is opened. It shows the current filter and jail configuration with all options to modify the settings, test or add / modify the logpaths, and save changes.
Logpath testing functionality that verifies log file paths and checks if files are accessible. Shows test results with visual indicators (✓/✗) for each log path.
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. Allows configuration of seperate jails with special parameters, filter selection, with automatic configuration generation.
Search for a specific IPs, that where blocked in a specific jail - searches in all active jails. Provides a quick and painless filtering.
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.
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 showing real-time application logs, system messages, and debugging information. Useful for troubleshooting and monitoring without the need to query the container logs manually everytime.
Configuration for advanced ban actions including permanent blocking, firewall integrations (Mikrotik, pfSense, OPNsense), and threshold settings for recurring offenders.
Alert configuration supporting three providers: Email (SMTP), Webhook, and Elasticsearch. Includes country-based filtering, GeoIP provider selection, and per-event toggles for bans and unbans. See docs/alert-providers.md for details.
Global Fail2Ban settings including default bantime, findtime, maxretry, banaction configuration (nftables/firewalld/iptables) and so on.
- Do not expose the UI directly to the public Internet. Put it behind a reverse proxy, VPN, firewall rules, and/or OIDC.
- 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 (strict IPv4/IPv6/CIDR parsing) before being passed to any integration or command, preventing command injection.
- WebSocket connections are protected by origin validation (same-origin only) and require authentication when OIDC is enabled.
See docs/security.md for details.
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.
See CONTRIBUTING.md for more info.
GPL-3.0. See LICENSE.