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:

```yaml
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:

```makefile
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.