BanGUI/Docker/fail2ban-dev-config/README.md

BanGUI — Fail2ban Dev Test Environment

This directory contains the fail2ban configuration and supporting scripts for a self-contained development test environment. A simulation script writes fake authentication-failure log lines, fail2ban detects them via the manual-Jail jail, and bans the offending IP — giving a fully reproducible ban/unban cycle without a real service.

---

Prerequisites

• Docker or Podman installed and running.
• docker compose (v2) or podman-compose available on the PATH.
• The repo checked out; all commands run from the repo root.

---

Quick Start

1 — Start the fail2ban container

docker compose -f Docker/compose.debug.yml up -d fail2ban
# or: make up  (starts the full dev stack)

Wait ~15 s for the health-check to pass (docker ps shows healthy).

2 — Run the login-failure simulation

bash Docker/simulate_failed_logins.sh

Default: writes 5 failure lines for IP 192.168.100.99 to Docker/logs/auth.log.
Optional overrides:

bash Docker/simulate_failed_logins.sh <COUNT> <SOURCE_IP> <LOG_FILE>
# e.g. bash Docker/simulate_failed_logins.sh 10 203.0.113.42

3 — Verify the IP was banned

bash Docker/check_ban_status.sh

The output shows the current jail counters and the list of banned IPs with their ban expiry timestamps.

4 — Unban and re-test

bash Docker/check_ban_status.sh --unban 192.168.100.99

One-command smoke test (Makefile shortcut)

make dev-ban-test

Chains steps 1–3 automatically with appropriate sleep intervals.

---

Configuration Reference

File	Purpose
fail2ban/filter.d/manual-Jail.conf	Defines the failregex that matches simulation log lines
fail2ban/jail.d/manual-Jail.conf	Jail settings: maxretry=3, bantime=60s, findtime=120s
Docker/logs/auth.log	Log file written by the simulation script (host path)

Inside the container the log file is mounted at /remotelogs/bangui/auth.log (see fail2ban/paths-lsio.conf — remote_logs_path = /remotelogs).

To change sensitivity, edit fail2ban/jail.d/manual-Jail.conf:

maxretry = 3    # failures before a ban
findtime = 120  # look-back window in seconds
bantime  = 60   # ban duration in seconds

---

Troubleshooting

Log file not detected

The jail uses backend = polling for reliability inside Docker containers. If fail2ban still does not pick up new lines, verify the volume mount in Docker/compose.debug.yml:

- ./logs:/remotelogs/bangui

and confirm Docker/logs/auth.log exists after running the simulation script.

Filter regex mismatch

Test the regex manually:

docker exec bangui-fail2ban-dev \
    fail2ban-regex /remotelogs/bangui/auth.log manual-Jail

The output should show matched lines. If nothing matches, check that the log lines match the corresponding failregex pattern:

# manual-Jail (auth log):
YYYY-MM-DD HH:MM:SS bangui-auth: authentication failure from <IP>

iptables / permission errors

The fail2ban container requires NET_ADMIN and NET_RAW capabilities and network_mode: host. Both are already set in Docker/compose.debug.yml. If you see iptables errors, check that the host kernel has iptables loaded:

sudo modprobe ip_tables

IP not banned despite enough failures

Check whether the source IP falls inside the ignoreip range defined in fail2ban/jail.d/manual-Jail.conf:

ignoreip = 127.0.0.0/8 ::1 172.16.0.0/12

The default simulation IP 192.168.100.99 is outside these ranges and will be banned normally.