fail2ban-dashboard

A web-based dashboard for fail2ban which uses the /var/run/fail2ban/fail2ban.sock socket to access fail2ban.
In addition to the dashboard, the application can provide Prometheus metrics related to fail2ban when enabled.

Tested with the following fail2ban versions

• 0.11.1
• 0.11.2
• 1.0.1
• 1.0.2
• 1.1.0

If the dashboard should be used with another version, please switch off the version check with the --skip-version-check flag, otherwise the application won't start.

Table of Contents

• Screenshots
  • Light mode
  • Dark mode
  • OAuth2
• Installation
  • Standalone application
  • Docker
• Usage
  • Command line
  • Configuration
    • Environment variables
    • Basic authentication
    • OAuth2
  • Config file
• Dashboard
  • Web application
  • Metrics
• Building the application
• Inspired by

Screenshots

Light mode

Overview	Detail

Dark mode

Overview	Detail

OAuth2

OAuth2

Login	Keycloak	Overview

Installation

Standalone application

When using fail2ban-dashboard as a standalone application, grab a released version from the releases page.

Docker

With Docker use

docker run --user=root -v /var/run/fail2ban/fail2ban.sock:/var/run/fail2ban/fail2ban.sock:ro -p 3000:3000 ghcr.io/webishdev/fail2ban-dashboard:latest

The root user is necessary as by default the fail2ban socket is only accessible for the root user.

Instead of latest you can use a specific version like v0.8.1

Usage

Command line

Usage:
  fail2ban-dashboard [flags]
  fail2ban-dashboard [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  serve       Start the fail2ban dashboard server (default)
  version     Print the version number and git hash

Flags:
  -a, --address string               address to serve the dashboard on, also F2BD_ADDRESS (default "127.0.0.1:3000")
      --auth-password string         password for basic auth, also F2BD_AUTH_PASSWORD
      --auth-user string             username for basic auth, also F2BD_AUTH_USER
      --base-path string             base path of the application, also F2BD_BASE_PATH (default "/")
  -c, --cache-dir string             directory to cache GeoIP data, also F2BD_CACHE_DIR (default current working directory)
  -h, --help                         help for fail2ban-dashboard
      --log-level string             log level (trace, debug, info, warn, error), also F2BD_LOG_LEVEL (default "info")
  -m, --metrics                      will provide metrics endpoint, also F2BD_METRICS
      --metrics-address string       address to make metrics available, also F2BD_METRICS_ADDRESS (default "127.0.0.1:9100")
      --oauth2-auth-url string       OAuth2 authentication URL, also F2BD_OAUTH2_AUTH_URL
      --oauth2-client-id string      OAuth2 client identifier, also F2BD_OAUTH2_CLIENT_ID
      --oauth2-redirect-url string   OAuth2 redirect URL, also F2BD_OAUTH2_REDIRECT_URL
      --oauth2-token-url string      OAuth2 token URL, also F2BD_OAUTH2_TOKEN_URL
      --refresh-seconds int          fail2ban data refresh in seconds (value from 10 to 600), also F2BD_REFRESH_SECONDS (default 30)
      --scheduled-geoip-download     will keep GeoIP cache update even without accessing the dashboard, also F2BD_SCHEDULED_GEOIP_DOWNLOAD (default true)
      --skip-version-check           skip fail2ban version check (use at your own risk), also F2BD_SKIP_VERSION_CHECK
  -s, --socket string                location of the fail2ban socket, also F2BD_SOCKET (default "/var/run/fail2ban/fail2ban.sock")
      --trust-proxy-headers          trust proxy headers like X-Forwarded-For, also F2BD_TRUST_PROXY_HEADERS

Use "fail2ban-dashboard [command] --help" for more information about a command.

Configuration

Environment variables

Environment variables can be used to set parameters without using command line flags.

Environment Variable	Command Line Flag	Description	Default
F2BD_ADDRESS	-a, --address	Address to serve the dashboard on	127.0.0.1:3000
F2BD_BASE_PATH	--base-path	Base path of the application	/
F2BD_CACHE_DIR	-c, --cache-dir	Directory to cache GeoIP data	Current working directory
F2BD_LOG_LEVEL	--log-level	Log level (trace, debug, info, warn, error)	info
F2BD_METRICS	-m, --metrics	Enables Prometheus metrics	false
F2BD_METRICS_ADDRESS	--metrics-address	Address to serve the metrics	127.0.0.1:9100
F2BD_REFRESH_SECONDS	--refresh-seconds	Refresh seconds for fail2ban data (10-600)	30
F2BD_SKIP_VERSION_CHECK	--skip-version-check	Skip fail2ban version check	false
F2BD_SOCKET	-s, --socket	Fail2ban socket path	/var/run/fail2ban/fail2ban.sock
F2BD_TRUST_PROXY_HEADERS	--trust-proxy-headers	Trust proxy headers like X-Forwarded-For	false

Basic authentication

Basic authentication can be enabled with the --auth-user and/or --auth-password flags.
When only --auth-user is provided, the password will be generated and shown in the logs/console.
When only --auth-password is provided, the user will be named admin.

Environment Variable	Command Line Flag	Description	Default
F2BD_AUTH_PASSWORD	--auth-password	Password for basic auth	-
F2BD_AUTH_USER	--auth-user	Username for basic auth	-

OAuth2

When using OAuth2 authentication, fail2ban-dashboard requires the following environment variables or command line flags to be set when no default value is provided:

Environment Variable	Command Line Flag	Description	Default
F2BD_OAUTH2_CLIENT_ID	--oauth2-client-id	OAuth2 client identifier	-
F2BD_OAUTH2_AUTH_URL	--oauth2-auth-url	OAuth2 authorization URL	-
F2BD_OAUTH2_TOKEN_URL	--oauth2-token-url	OAuth2 token URL	-
F2BD_OAUTH2_REDIRECT_URL	--oauth2-redirect-url	OAuth2 redirect URL	-
F2BD_OAUTH2_TIMEOUT_MINUTES	--oauth2-timeout-minutes	OAuth2 session timeout minutes	30

All values that do not provide a default value are required and must be set. The OAuth2 redirect URL must be set to the URL of the fail2ban-dashboard application, which is usually http://127.0.0.1:3000 but allows to provide URLs when used with a reverse proxy like https://fail2ban.example.com.

Example CLI setup with a local Keycloak instance running at http://localhost:8080 and providing a demo realm:

./fail2ban-dashboard serve --oauth2-client-id mysecretclient --oauth2-auth-url http://localhost:8080/realms/demo/protocol/openid-connect/auth --oauth2-token-url http://localhost:8080/realms/demo/protocol/openid-connect/token --oauth2-redirect-url http://localhost:3000

Configuration file

It is also possible to configure fail2ban-dashboard using a config file. Supported config file formats are the ones supported by the viper library.

The config file can be located at the current working directory, the user home directory ~/.config/fail2ban-dashboard/ or /etc/fail2ban-dashboard/.

For example, for a TOML file located at /etc/fail2ban-dashboard/config.toml to change the address should look like:

address = "127.0.0.1:4000"

Supported configuration names are similar to flags and environment variables:

Configuration
socket
address
auth-user
auth-password
cache-dir
log-level
base-path
metrics-address
oauth2-client-id
oauth2-auth-url
oauth2-token-url
oauth2-redirect-url

Dashboard

Web application

When started, check http://127.0.0.1:3000/

Metrics

When metrics are enabled with -m the metrics endpoint is available at http://127.0.0.1:9100/metrics and the address can be changed with --metrics-address.

The following example shows which metrics are provided

# HELP f2b_banned_total The total number of banned addresses
# TYPE f2b_banned_total gauge
f2b_banned_total 46
# HELP f2b_jail_banned_current Amount of banned IPs currently in jail
# TYPE f2b_jail_banned_current gauge
f2b_jail_banned_current{jail="postfix"} 13
f2b_jail_banned_current{jail="sshd"} 33
# HELP f2b_jail_banned_total Amount of banned IPs total in jail
# TYPE f2b_jail_banned_total gauge
f2b_jail_banned_total{jail="postfix"} 13
f2b_jail_banned_total{jail="sshd"} 33
# HELP f2b_jail_count The number of jails in fail2ban
# TYPE f2b_jail_count gauge
f2b_jail_count 2
# HELP f2b_jail_failed_current Amount of failed IPs currently in jail
# TYPE f2b_jail_failed_current gauge
f2b_jail_failed_current{jail="postfix"} 0
f2b_jail_failed_current{jail="sshd"} 0
# HELP f2b_jail_failed_total Amount of failed IPs total in jail
# TYPE f2b_jail_failed_total gauge
f2b_jail_failed_total{jail="postfix"} 0
f2b_jail_failed_total{jail="sshd"} 0
# HELP fail2ban_dashboard_info The fail2ban Dashboard build information
# TYPE fail2ban_dashboard_info gauge
fail2ban_dashboard_info{fail2ban_version="1.1.0",version="development"} 1

Building the application

Requirements

To build the application, the Go version specificed in the go.mod file must be installed. Furthermore, the make utility must be installed.

Building

To build the application, use make with the following options:

> make help

Available targets:
  all         - Run tests, lint, and build for all platforms (default)
  build-all   - Build for all platforms (Intel and ARM)
  build-intel - Build Linux binary for Intel CPUs (amd64)
  build-arm   - Build Linux binary for ARM CPUs (arm64)
  build       - Build for specified GOOS/GOARCH
  lint        - Run golangci-lint
  test        - Run tests
  test-ci     - Run tests with JSON output for CI/CD
  clean       - Remove build artifacts
  help        - Show this help message

Variables:
  VERSION - Version to embed in binary (default: development)
  GOOS    - Target operating system (default: linux)
  GOARCH  - Target architecture (default: amd64)

Examples:
  make build-all
  make build-intel VERSION=v1.0.0
  make build GOOS=darwin GOARCH=arm64
  make clean

Inspired by

• https://github.com/fail2ban/fail2ban
• https://gitlab.com/hctrdev/fail2ban-prometheus-exporter/-/tree/main?ref_type=heads
• https://github.com/VerifiedJoseph/intruder-alert?tab=readme-ov-file