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
This commit is contained in:
124
Docs/Tasks.md
124
Docs/Tasks.md
@@ -4,14 +4,122 @@ This document breaks the entire BanGUI project into development stages, ordered
|
||||
|
||||
---
|
||||
|
||||
## ✅ FIXED — Access list 404: `/api/api/dashboard/accesses` double prefix (2026-03-01)
|
||||
## Stage 0 — Fail2ban Dev Test Environment
|
||||
|
||||
**Root cause:** `fetchAccesses` in `src/api/dashboard.ts` passed the hardcoded absolute path
|
||||
`/api/dashboard/accesses` directly to `get()`. Because `get()` prepends `BASE_URL` (`/api`),
|
||||
the resulting URL became `/api/api/dashboard/accesses`, which has no backend route.
|
||||
**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.
|
||||
|
||||
**Fix:** Added `dashboardAccesses: "/dashboard/accesses"` to `ENDPOINTS` in `src/api/endpoints.ts`
|
||||
and changed `fetchAccesses` to use `ENDPOINTS.dashboardAccesses` — consistent with every other
|
||||
function in the same file.
|
||||
**Status: ✅ Complete** — all tasks 0.1–0.8 implemented.
|
||||
|
||||
**Commit:** _Fix double /api prefix in fetchAccesses by using ENDPOINTS constant_
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
Reference in New Issue
Block a user