Fail2Ban UI

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.

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):

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
• Configuration reference (env vars, callback URL/secret, OIDC): docs/configuration.md
• Reverse proxy guide: docs/reverse-proxy.md
• Webhook integration guide: docs/webhooks.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

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 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.

See 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/<lang>.json, and open a pull request. Please use a proper lowercase locale short code for <lang> (for example ch, ch_de, es, or pt_br).

See CONTRIBUTING.md for more info.

License

GPL-3.0. See LICENSE.