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.

---

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 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 to understand the system structure before touching any component.
3. Read the development guide relevant to your task: Backend-Development.md or Web-Development.md (or both).
4. Read 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: Done

Summary: jail.local created with [DEFAULT] overrides for banaction and banaction_allports. The container init script (init-fail2ban-config) overwrites jail.conf from the image's /defaults/ on every start, so modifying jail.conf directly is ineffective. jail.local is not in the container's defaults and thus persists correctly. Additionally fixed a TypeError in config_file_service.py where except jail_service.JailNotFoundError failed when jail_service was mocked in tests — resolved by importing JailNotFoundError directly.

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]:

   # 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:

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 — Add banaction override via jail.local [DEFAULT]

  Open Docker/fail2ban-dev-config/fail2ban/jail.conf. Find the two commented-out lines near the action_ definition:

  #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:

  make down && make up
  

  Wait for the fail2ban container to reach healthy, then inspect its logs:

  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 Docker/simulate_failed_logins.sh
  

  Then confirm fail2ban has recorded a ban:

  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.

---