BanGUI/Docs/Tasks.md

BanGUI — Task List

This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.

---

Stage 0 — Fail2ban Dev Test Environment

Goal: Set up a self-contained test environment where a script simulates failed login attempts, those attempts are written to a log file in Docker/logs/, fail2ban monitors that log and bans the offending IP. This provides a reproducible way to test the ban/unban lifecycle without a real service.

Status: ✅ Complete — all tasks 0.1–0.8 implemented.

---

Task 0.1 — Create the custom fail2ban filter

Create a new filter definition file at Docker/fail2ban-dev-config/fail2ban/filter.d/bangui-sim.conf. This filter must define a failregex that matches the log lines the simulation script will produce. Use a simple, deterministic log format such as:

<timestamp> bangui-auth: authentication failure from <HOST>

The filter file should contain:

• A [Definition] section.
• A failregex line that captures <HOST> from lines matching the format above (e.g. ^.* bangui-auth: authentication failure from <HOST>\s*$).
• An empty ignoreregex.

Reference: existing filters in Docker/fail2ban-dev-config/fail2ban/filter.d/ for syntax examples.

---

Task 0.2 — Create a jail definition for the simulated service

Create Docker/fail2ban-dev-config/fail2ban/jail.d/bangui-sim.conf (or add to a .local file). This jail must:

• Set enabled = true.
• Reference the filter from Task 0.1 (filter = bangui-sim).
• Point logpath to the log file inside the container. The log file in Docker/logs/ will be mounted into the fail2ban container; choose a mount target such as /remotelogs/bangui/auth.log and set logpath accordingly.
• Use a low maxretry (e.g. 3) and a short bantime (e.g. 60 seconds) so testing is fast.
• Set findtime to something reasonable (e.g. 120 seconds).
• Set banaction to iptables-allports (or whichever action is appropriate for the container — the linuxserver/fail2ban image supports iptables).
• Optionally set backend = auto (pyinotify/polling).

Reference: existing jails in Docker/fail2ban-dev-config/fail2ban/jail.d/ and jail.conf.

---

Task 0.3 — Mount Docker/logs/ into the fail2ban container

Update Docker/compose.debug.yml so the fail2ban service mounts the host directory ./logs into the container at a path that matches the logpath configured in Task 0.2 (e.g. /remotelogs/bangui). Add an entry like:

volumes:
  - ./logs:/remotelogs/bangui

Make sure the path is consistent with paths-lsio.conf (remote_logs_path = /remotelogs). If you chose a different mount target, adjust the jail's logpath to match.

---

Task 0.4 — Create the failed-login simulation script

Create a script at Docker/simulate_failed_logins.sh (bash). The script must:

1. Accept optional arguments: number of failed attempts (default 5), source IP to simulate (default 192.168.100.99), and target log file path (default ./logs/auth.log).
2. Create the log directory if it does not exist.
3. In a loop, append lines to the log file matching the exact format the filter expects, e.g.:

   2026-03-03 12:00:01 bangui-auth: authentication failure from 192.168.100.99
   

   Use the current timestamp for each line (via date). Sleep briefly between writes (e.g. 0.5 s) so the timestamps differ.
4. After all lines are written, print a summary: how many failure lines were written, which IP, and which file.
5. Mark the script as executable (chmod +x).

Reference: the failregex in Task 0.1 — the log format must match exactly.

---

Task 0.5 — Create a verification / status-check script

Create Docker/check_ban_status.sh that:

1. Runs docker exec bangui-fail2ban-dev fail2ban-client status bangui-sim to show the jail status (current failures, banned IPs).
2. Runs docker exec bangui-fail2ban-dev fail2ban-client get bangui-sim banip --with-time (or equivalent) to list banned IPs with timestamps.
3. Accepts an optional --unban <IP> flag that calls docker exec bangui-fail2ban-dev fail2ban-client set bangui-sim unbanip <IP> so the tester can quickly reset.
4. Mark the script as executable.

---

Task 0.6 — Add an ignoreip safeguard

In the jail created in Task 0.2, add ignoreip = 127.0.0.0/8 ::1 (and optionally the Docker bridge subnet) so that the host machine and localhost are never accidentally banned during development.

---

Task 0.7 — End-to-end manual test & documentation

Write a brief section in Docker/fail2ban-dev-config/README.md that documents:

1. Prerequisites: Docker / Podman running, compose available.
2. Quick start:
   • docker compose -f Docker/compose.debug.yml up -d fail2ban (start only the fail2ban service).
   • bash Docker/simulate_failed_logins.sh (run the simulation).
   • bash Docker/check_ban_status.sh (verify the IP was banned).
   • bash Docker/check_ban_status.sh --unban 192.168.100.99 (unban and re-test).
3. Configuration reference: where the filter, jail, and log file live; how to change maxretry, bantime, etc.
4. Troubleshooting: common issues (log file not mounted, filter regex mismatch, container not seeing file changes — suggest backend = polling if inotify doesn't work inside Docker).

---

Task 0.8 — (Optional) Add a Makefile target

Add a dev-ban-test target to the top-level Makefile that chains the workflow:

dev-ban-test:
	docker compose -f Docker/compose.debug.yml up -d fail2ban
	sleep 5
	bash Docker/simulate_failed_logins.sh
	sleep 3
	bash Docker/check_ban_status.sh

This lets a developer (or CI) run make dev-ban-test for a one-command smoke test of the ban pipeline.