fail2ban-dashboard

KO | EN

gitlite — search

#javascript #react #android #machine-learning #rust #docker #macos #nodejs #cli #vue #awesome-list #ios #mcp #open-source

fail2ban-dashboard

(★ 18)

A web based dashboard for fail2ban

fail2ban-dashboard 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# fail2ban-dashboard

![build](https://github.com/webishdev/fail2ban-dashboard/actions/workflows/build.yml/badge.svg)
![GitHub Release](https://img.shields.io/github/v/release/webishdev/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](#screenshots)
    - [Light mode](#light-mode)
    - [Dark mode](#dark-mode)
    - [OAuth2](#oauth2)
- [Installation](#installation)
    - [Standalone application](#standalone-application)
    - [Docker](#docker)
- [Usage](#usage)
    - [Command line](#command-line)
    - [Configuration](#configuration)
        - [Environment variables](#environment-variables)
        - [Basic authentication](#basic-authentication)
        - [OAuth2](#oauth2-1)
    - [Config file](#config-file)
- [Dashboard](#dashboard)
    - [Web application](#web-application)
    - [Metrics](#metrics)
- [Building the application](#building-the-application)
- [Inspired by](#inspired-by)

## Screenshots

### Light mode

| Overview                                                                                                                          | Detail                                                                                                                                |
|-----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| ![Screenshot of fail2ban-dashboard overview light](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/overview_light.png "Screenshot of fail2ban-dashboard overview light") | ![Screenshot of fail2ban-dashboard detail view light](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/detail_light.png "Screenshot of fail2ban-dashboard detail view light") |

### Dark mode

| Overview                                                                                                                       | Detail                                                                                                                             |
|--------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| ![Screenshot of fail2ban-dashboard overview dark](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/overview_dark.png "Screenshot of fail2ban-dashboard overview dark") | ![Screenshot of fail2ban-dashboard detail view dark](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/detail_dark.png "Screenshot of fail2ban-dashboard detail view dark") |

### OAuth2

<details>
<summary>OAuth2</summary>

| Login                                                                                                                             | Keycloak                                                                                    | Overview                                                                                                                                                  |
|-----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| ![Screenshot of fail2ban-dashboard OAuth2 login](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/oauth2_login_light.png "Screenshot of fail2ban-dashboard OAuth2 login") | ![Screenshot of Keycloak login](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/keycloak_login.png "Screenshot of Keycloak login") | ![Screenshot of fail2ban-dashboard overview with logout](https://raw.githubusercontent.com/webishdev/fail2ban-dashboard/main/images/overview_with_logout_light.png "Screenshot of fail2ban-dashboard overview with logout") |

</details>

## Installation

### Standalone application

When using `fail2ban-dashboard` as a standalone application, grab a released version from
the [releases page](https://github.com/webishdev/fail2ban-dashboard/releases).

### 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](https://github.com/spf13/viper#reading-config-files)
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:

```toml
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

```text
# 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

fail2ban-dashboard

fail2ban-dashboard 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

fail2ban-dashboard

fail2ban-dashboard 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README