https://github.com/swissmakers/fail2ban-ui
Fail2Ban UI is a swissmade web interface 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.
https://github.com/swissmakers/fail2ban-ui
dashboard fail2ban fail2ban-dashboard golang intrusion-detection linux remote-management webui
Last synced: 28 days ago
JSON representation
Fail2Ban UI is a swissmade web interface 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.
- Host: GitHub
- URL: https://github.com/swissmakers/fail2ban-ui
- Owner: swissmakers
- License: gpl-3.0
- Created: 2025-01-25T14:57:53.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-31T22:07:53.000Z (about 1 month ago)
- Last Synced: 2026-04-01T01:19:39.816Z (about 1 month ago)
- Topics: dashboard, fail2ban, fail2ban-dashboard, golang, intrusion-detection, linux, remote-management, webui
- Language: Go
- Homepage: https://fail2ban-ui.com
- Size: 28.9 MB
- Stars: 201
- Watchers: 4
- Forks: 17
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: docs/security.md
Awesome Lists containing this project
README
# Fail2Ban UI
**Enterprise-Grade Intrusion Detection System Management Platform**
[](https://polyformproject.org/licenses/shield/1.0.0/)
[](https://golang.org/)
[](https://www.linux.org/)
*Swiss-made solution for centralized Fail2Ban management across distributed infrastructure*
[Quick Start](#quick-start-container) • [Documentation](#documentation) • [Configuration Reference](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/configuration.md) • [Screenshots](#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 the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/).
## What this project does
Fail2Ban UI does not replace Fail2Ban. It connects to existing Fail2Ban instances and adds:
- Dashboard for active jails and recent ban/unban activity with real-time WebSocket updates
- Server manager for local, SSH, and agent-managed Fail2Ban instances
- Centralized search, ban, and unban operations across jails and servers
- Remote jail/filter configuration management (connector-dependent)
- Filter debug and live log-pattern testing
- Ban insights with an interactive 3D globe by country
- Advanced recurring-offender actions (MikroTik, pfSense, OPNsense)
- Persistent event and permanent-block data management
- Configurable alerts (Email/SMTP, Webhook, Elasticsearch) with GeoIP/Whois enrichment
- Optional OIDC login (Keycloak, Authentik, Pocket-ID)
- Least-privilege, SELinux-aware deployment patterns
## Connector types
| 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 and remote `fail2ban-client` |
| Agent (technical preview) | Environments where SSH is not desired | Limited functionality; work in progress |
## Quick start (container)
Prerequisites:
- A Linux host with Podman or Docker
- If you manage a local Fail2Ban instance: access to `/etc/fail2ban` and `/var/run/fail2ban` is needed by Fail2ban-UI
Procedure (local connector example):
```bash
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
````
Verification:
* 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.
## Documentation
* Installation: [`docs/installation.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/installation.md)
* Configuration reference (env vars, callback URL/secret, OIDC): [`docs/configuration.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/configuration.md)
* Reverse proxy guide: [`docs/reverse-proxy.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/reverse-proxy.md)
* Webhook integration guide: [`docs/webhooks.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/webhooks.md)
* Security guidance (recommended deployment posture): [`docs/security.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/security.md)
* Architecture overview: [`docs/architecture.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/architecture.md)
* API reference: [`docs/api.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/api.md)
* Alert providers (Email, Webhook, Elasticsearch): [`docs/alert-providers.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/alert-providers.md)
* Threat intelligence (AlienVault OTX / AbuseIPDB): [`docs/threat-intel.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/threat-intel.md)
* Troubleshooting: [`docs/troubleshooting.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/troubleshooting.md)
Existing deployment guides in this repository:
* Container: [`deployment/container/README.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/deployment/container/README.md)
* systemd: [`deployment/systemd/README.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/deployment/systemd/README.md)
* Optional container SELinux modules (socket/log access): [`deployment/container/SELinux/`](https://github.com/swissmakers/fail2ban-ui/blob/main/deployment/container/SELinux/) — host Fail2Ban `curl` callbacks often need the `nis_enabled` boolean instead; see [`docs/security.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/security.md#selinux)
Development / testing stacks:
* OIDC dev stack: [`development/oidc/README.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/development/oidc/README.md)
* SSH and local connector dev stack: [`development/ssh_and_local/README.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/development/ssh_and_local/README.md)
## Screenshots
A set of screenshots is available in `screenshots/`
### Main Dashboard
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.
#### Unban IP
Unbanning a IP addresses directly from the dashboard. Shows the unban confirmation dialog.
### Server Management
Server management modal for configuring / adding and managing multiple Fail2Ban instances. Supports local, SSH, and API agent connections.
### Jail / Filter Management
Overview of all configured jails with their enabled/disabled status. Allows centralized management of jail configurations across multiple servers.
#### Edit Jail Configuration
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 Test
Logpath testing functionality that verifies log file paths and checks if files are accessible. Shows test results with visual indicators (✓/✗) for each log path.
#### Create new Filter
The first button opens the modal for creating new Fail2Ban filter files. Includes filter configuration editor with syntax highlighting and validation.
#### Create new Jail
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 Functionality
Search for a specific IPs, that where blocked in a specific jail - searches in all active jails. Provides a quick and painless filtering.
### Internal Log Overview
Comprehensive log overview showing ban / unban events, timestamps, and associated jails and recurring offenders. Provides detailed information about past security events.
#### Whois Information
Whois lookup modal displaying detailed information about banned IP addresses, including geographic location, ISP details, and network information.
#### Ban Logs
Detailed ban log view showing log lines that triggered the ban, timestamps, and context information for each security event.
### Filter Debugging
Filter debugging interface for testing Fail2Ban filter regex patterns against log lines. Helps validate filter configurations before deployment.
#### Filter Test Results
Results from filter testing showing matched lines, regex performance, and validation feedback. Displays which log lines match the filter pattern.
### Settings
Main settings page with sections for different configuration categories including general settings, advanced ban actions, alert settings, and global fail2ban settings.
#### Debug Console
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.
#### Advanced Ban Actions
Configuration for advanced ban actions including permanent blocking, firewall integrations (Mikrotik, pfSense, OPNsense), and threshold settings for recurring offenders.
#### Alert Settings
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`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/alert-providers.md) for details.
#### Global Settings
Global Fail2Ban settings including default bantime, findtime, maxretry, banaction configuration (nftables/firewalld/iptables) and so on.
## Security notes (think before exposing the UI)
* 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 *` and `sudo 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.
* For production proxy examples and WebSocket requirements, see [`docs/reverse-proxy.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/reverse-proxy.md).
See [`docs/security.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/docs/security.md) for details.
## Contributing
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.
Want to add a new UI language? Copy `internal/locales/en.json`, translate all values, save it as `internal/locales/.json`, and open a pull request.
Please use a proper lowercase locale short code for `` (for example `ch`, `ch_de`, `es`, or `pt_br`).
See [`CONTRIBUTING.md`](https://github.com/swissmakers/fail2ban-ui/blob/main/CONTRIBUTING.md) for more info.
## License
Fail2ban UI is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/). See the [`LICENSE`](LICENSE) file for the full terms and required notices.