138 lines
5.5 KiB
Markdown
138 lines
5.5 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## Agent Operating Instructions
|
|
|
|
These instructions apply to every AI agent working in this repository. Read them fully before touching any file.
|
|
|
|
### Before You Begin
|
|
|
|
1. Read [Instructions.md](Instructions.md) in full — it defines the project context, coding standards, and workflow rules. Every rule there is authoritative and takes precedence over any assumption you make.
|
|
2. Read [Architekture.md](Architekture.md) to understand the system structure before touching any component.
|
|
3. Read the development guide relevant to your task: [Backend-Development.md](Backend-Development.md) or [Web-Development.md](Web-Development.md) (or both).
|
|
4. Read [Features.md](Features.md) so you understand what the product is supposed to do and do not accidentally break intended behaviour.
|
|
|
|
### How to Work Through This Document
|
|
|
|
- Tasks are grouped by feature area. Each group is self-contained.
|
|
- Work through tasks in the order they appear within a group; earlier tasks establish foundations for later ones.
|
|
- Mark a task **in-progress** before you start it and **completed** the moment it is done. Never batch completions.
|
|
- If a task depends on another task that is not yet complete, stop and complete the dependency first.
|
|
- If you are uncertain whether a change is correct, read the relevant documentation section again before proceeding. Do not guess.
|
|
|
|
### Code Quality Rules (Summary)
|
|
|
|
- No TODOs, no placeholders, no half-finished functions.
|
|
- Full type annotations on every function (Python) and full TypeScript types on every symbol (no `any`).
|
|
- Layered architecture: routers → services → repositories. No layer may skip another.
|
|
- All backend errors are raised as typed HTTP exceptions; all unexpected errors are logged via structlog before re-raising.
|
|
- All frontend state lives in typed hooks; no raw `fetch` calls outside of the `api/` layer.
|
|
- After every code change, run the full test suite (`make test`) and ensure it is green.
|
|
|
|
### Definition of Done
|
|
|
|
A task is done when:
|
|
- The code compiles and the test suite passes (`make test`).
|
|
- The feature works end-to-end in the dev stack (`make up`).
|
|
- No new lint errors are introduced.
|
|
- The change is consistent with all documentation rules.
|
|
|
|
---
|
|
|
|
## Bug Fixes
|
|
|
|
---
|
|
|
|
### BUG-001 — fail2ban: `bangui-sim` jail fails to start due to missing `banaction`
|
|
|
|
**Status:** Open
|
|
|
|
#### Error
|
|
|
|
```
|
|
Failed during configuration: Bad value substitution: option 'action' in section 'bangui-sim'
|
|
contains an interpolation key 'banaction' which is not a valid option name.
|
|
Raw value: '%(action_)s'
|
|
```
|
|
|
|
#### Root Cause
|
|
|
|
fail2ban's interpolation system resolves option values at configuration load time by
|
|
substituting `%(key)s` placeholders with values from the same section or from `[DEFAULT]`.
|
|
|
|
The chain that fails is:
|
|
|
|
1. Every jail inherits `action = %(action_)s` from `[DEFAULT]` (no override in `bangui-sim.conf`).
|
|
2. `action_` is defined in `[DEFAULT]` as `%(banaction)s[port="%(port)s", protocol="%(protocol)s", chain="%(chain)s"]`.
|
|
3. `banaction` is **commented out** in `[DEFAULT]`:
|
|
```ini
|
|
# Docker/fail2ban-dev-config/fail2ban/jail.conf [DEFAULT]
|
|
#banaction = iptables-multiport ← this line is disabled
|
|
```
|
|
4. Because `banaction` is absent from the interpolation namespace, fail2ban cannot resolve
|
|
`action_`, which makes it unable to resolve `action`, and the jail fails to load.
|
|
|
|
The same root cause affects every jail in `jail.d/` that does not define its own `banaction`,
|
|
including `blocklist-import.conf`.
|
|
|
|
#### Fix
|
|
|
|
**File:** `Docker/fail2ban-dev-config/fail2ban/jail.conf`
|
|
|
|
Uncomment the `banaction` line inside the `[DEFAULT]` section so the value is globally
|
|
available to all jails:
|
|
|
|
```ini
|
|
banaction = iptables-multiport
|
|
banaction_allports = iptables-allports
|
|
```
|
|
|
|
This is safe: the dev compose (`Docker/compose.debug.yml`) already grants the fail2ban
|
|
container `NET_ADMIN` and `NET_RAW` capabilities, which are the prerequisites for
|
|
iptables-based banning.
|
|
|
|
#### Tasks
|
|
|
|
- [ ] **BUG-001-T1 — Uncomment `banaction` in `jail.conf` [DEFAULT]**
|
|
|
|
Open `Docker/fail2ban-dev-config/fail2ban/jail.conf`.
|
|
Find the two commented-out lines near the `action_` definition:
|
|
```ini
|
|
#banaction = iptables-multiport
|
|
#banaction_allports = iptables-allports
|
|
```
|
|
Remove the leading `#` from both lines so they become active options.
|
|
Do not change any other part of the file.
|
|
|
|
- [ ] **BUG-001-T2 — Restart the fail2ban container and verify clean startup**
|
|
|
|
Bring the dev stack down and back up:
|
|
```bash
|
|
make down && make up
|
|
```
|
|
Wait for the fail2ban container to reach `healthy`, then inspect its logs:
|
|
```bash
|
|
make logs # or: docker logs bangui-fail2ban-dev 2>&1 | grep -i error
|
|
```
|
|
Confirm that no `Bad value substitution` or `Failed during configuration` lines appear
|
|
and that both `bangui-sim` and `blocklist-import` jails show as **enabled** in the output.
|
|
|
|
- [ ] **BUG-001-T3 — Verify ban/unban cycle works end-to-end**
|
|
|
|
With the stack running, trigger the simulation script:
|
|
```bash
|
|
bash Docker/simulate_failed_logins.sh
|
|
```
|
|
Then confirm fail2ban has recorded a ban:
|
|
```bash
|
|
bash Docker/check_ban_status.sh
|
|
```
|
|
The script should report at least one banned IP in the `bangui-sim` jail.
|
|
Also verify that the BanGUI dashboard reflects the new ban entry.
|
|
|
|
---
|
|
|