Add fail2ban dev test environment (Stage 0)

- Add bangui-sim filter (filter.d/bangui-sim.conf) matching the
  simulated authentication failure log format
- Add bangui-sim jail (jail.d/bangui-sim.conf) with maxretry=3,
  bantime=60s, findtime=120s, ignoreip safeguard, polling backend
- Mount Docker/logs/ into fail2ban container at /remotelogs/bangui
  in compose.debug.yml
- Add simulate_failed_logins.sh to write synthetic failure lines
- Add check_ban_status.sh with optional --unban flag
- Add dev-ban-test Makefile target for one-command smoke testing
- Write Docker/fail2ban-dev-config/README.md with setup and
  troubleshooting docs
- Update .gitignore to track custom config files while still
  excluding auto-generated linuxserver fail2ban files

Docker/check_ban_status.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+#  check_ban_status.sh
+#
+#  Queries the bangui-sim jail inside the running fail2ban
+#  container and optionally unbans a specific IP.
+#
+#  Usage:
+#    bash Docker/check_ban_status.sh
+#    bash Docker/check_ban_status.sh --unban 192.168.100.99
+#
+#  Requirements:
+#    The bangui-fail2ban-dev container must be running.
+#    (docker compose -f Docker/compose.debug.yml up -d fail2ban)
+# ──────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+readonly CONTAINER="bangui-fail2ban-dev"
+readonly JAIL="bangui-sim"
+
+# ── Helper: run a fail2ban-client command inside the container ─
+f2b() {
+    docker exec "${CONTAINER}" fail2ban-client "$@"
+}
+
+# ── Parse arguments ───────────────────────────────────────────
+UNBAN_IP=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --unban)
+            if [[ -z "${2:-}" ]]; then
+                echo "ERROR: --unban requires an IP address argument." >&2
+                exit 1
+            fi
+            UNBAN_IP="$2"
+            shift 2
+            ;;
+        *)
+            echo "ERROR: Unknown argument: '$1'" >&2
+            echo "Usage: $0 [--unban <IP>]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# ── Unban mode ────────────────────────────────────────────────
+if [[ -n "${UNBAN_IP}" ]]; then
+    echo "Unbanning ${UNBAN_IP} from jail '${JAIL}' ..."
+    f2b set "${JAIL}" unbanip "${UNBAN_IP}"
+    echo "Done. '${UNBAN_IP}' has been removed from the ban list."
+    echo ""
+fi
+
+# ── Jail status ───────────────────────────────────────────────
+echo "═══════════════════════════════════════════"
+echo "  Jail status: ${JAIL}"
+echo "═══════════════════════════════════════════"
+f2b status "${JAIL}"
+
+# ── Banned IPs with timestamps ────────────────────────────────
+echo ""
+echo "═══════════════════════════════════════════"
+echo "  Banned IPs with timestamps: ${JAIL}"
+echo "═══════════════════════════════════════════"
+f2b get "${JAIL}" banip --with-time || echo "(no IPs currently banned)"

Docker/compose.debug.yml

@@ -34,6 +34,7 @@ services:
       - ./fail2ban-dev-config:/config
       - fail2ban-dev-run:/var/run/fail2ban
       - /var/log:/var/log:ro
+      - ./logs:/remotelogs/bangui
     healthcheck:
       test: ["CMD", "fail2ban-client", "ping"]
       interval: 15s

Docker/fail2ban-dev-config/README.md

@@ -0,0 +1,141 @@
+# 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 `bangui-sim`
+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
+
+```bash
+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
+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
+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
+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
+bash Docker/check_ban_status.sh --unban 192.168.100.99
+```
+
+### One-command smoke test (Makefile shortcut)
+
+```bash
+make dev-ban-test
+```
+
+Chains steps 1–3 automatically with appropriate sleep intervals.
+
+---
+
+## Configuration Reference
+
+| File | Purpose |
+|------|---------|
+| `fail2ban/filter.d/bangui-sim.conf` | Defines the `failregex` that matches simulation log lines |
+| `fail2ban/jail.d/bangui-sim.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/bangui-sim.conf`:
+
+```ini
+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`:
+
+```yaml
+- ./logs:/remotelogs/bangui
+```
+
+and confirm `Docker/logs/auth.log` exists after running the simulation script.
+
+### Filter regex mismatch
+
+Test the regex manually:
+
+```bash
+docker exec bangui-fail2ban-dev \
+    fail2ban-regex /remotelogs/bangui/auth.log bangui-sim
+```
+
+The output should show matched lines. If nothing matches, check that the log
+lines produced by `simulate_failed_logins.sh` match this pattern exactly:
+
+```
+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:
+
+```bash
+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/bangui-sim.conf`:
+
+```ini
+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.

Docker/fail2ban-dev-config/fail2ban/filter.d/bangui-sim.conf

@@ -0,0 +1,12 @@
+# ──────────────────────────────────────────────────────────────
+#  BanGUI — Simulated authentication failure filter
+#
+#  Matches lines written by Docker/simulate_failed_logins.sh
+#  Format: <timestamp> bangui-auth: authentication failure from <HOST>
+# ──────────────────────────────────────────────────────────────
+
+[Definition]
+
+failregex = ^.* bangui-auth: authentication failure from <HOST>\s*$
+
+ignoreregex =

Docker/fail2ban-dev-config/fail2ban/jail.d/bangui-sim.conf

@@ -0,0 +1,20 @@
+# ──────────────────────────────────────────────────────────────
+#  BanGUI — Simulated authentication failure jail
+#
+#  Watches Docker/logs/auth.log (mounted at /remotelogs/bangui)
+#  for lines produced by Docker/simulate_failed_logins.sh.
+# ──────────────────────────────────────────────────────────────
+
+[bangui-sim]
+
+enabled    = true
+filter     = bangui-sim
+logpath    = /remotelogs/bangui/auth.log
+backend    = polling
+maxretry   = 3
+findtime   = 120
+bantime    = 60
+banaction  = iptables-allports
+
+# Never ban localhost, the Docker bridge network, or the host machine.
+ignoreip   = 127.0.0.0/8 ::1 172.16.0.0/12

Docker/simulate_failed_logins.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+#  simulate_failed_logins.sh
+#
+#  Writes synthetic authentication-failure log lines to a file
+#  that matches the bangui-sim fail2ban filter.
+#
+#  Usage:
+#    bash Docker/simulate_failed_logins.sh [COUNT] [SOURCE_IP] [LOG_FILE]
+#
+#  Defaults:
+#    COUNT    : 5
+#    SOURCE_IP: 192.168.100.99
+#    LOG_FILE : Docker/logs/auth.log       (relative to repo root)
+#
+#  Log line format (must match bangui-sim failregex exactly):
+#    YYYY-MM-DD HH:MM:SS bangui-auth: authentication failure from <IP>
+# ──────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+# ── Defaults ──────────────────────────────────────────────────
+readonly DEFAULT_COUNT=5
+readonly DEFAULT_IP="192.168.100.99"
+
+# Resolve script location so defaults work regardless of cwd.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly DEFAULT_LOG_FILE="${SCRIPT_DIR}/logs/auth.log"
+
+# ── Arguments ─────────────────────────────────────────────────
+COUNT="${1:-${DEFAULT_COUNT}}"
+SOURCE_IP="${2:-${DEFAULT_IP}}"
+LOG_FILE="${3:-${DEFAULT_LOG_FILE}}"
+
+# ── Validate COUNT is a positive integer ──────────────────────
+if ! [[ "${COUNT}" =~ ^[1-9][0-9]*$ ]]; then
+    echo "ERROR: COUNT must be a positive integer, got: '${COUNT}'" >&2
+    exit 1
+fi
+
+# ── Ensure log directory exists ───────────────────────────────
+LOG_DIR="$(dirname "${LOG_FILE}")"
+mkdir -p "${LOG_DIR}"
+
+# ── Write failure lines ───────────────────────────────────────
+echo "Writing ${COUNT} authentication-failure line(s) for ${SOURCE_IP} to ${LOG_FILE} ..."
+
+for ((i = 1; i <= COUNT; i++)); do
+    TIMESTAMP="$(date '+%Y-%m-%d %H:%M:%S')"
+    printf '%s bangui-auth: authentication failure from %s\n' \
+        "${TIMESTAMP}" "${SOURCE_IP}" >> "${LOG_FILE}"
+    sleep 0.5
+done
+
+# ── Summary ───────────────────────────────────────────────────
+echo "Done."
+echo "  Lines written : ${COUNT}"
+echo "  Source IP     : ${SOURCE_IP}"
+echo "  Log file      : ${LOG_FILE}"