# BanGUI — Feature List A web application to monitor, manage, and configure fail2ban from a clean, accessible interface. --- ## 1. Setup Page - Displayed automatically on first launch when no configuration exists. - As long as no configuration is saved, every route redirects to the setup page. - Once setup is complete and a configuration is saved, the setup page is never shown again and cannot be accessed. ### Options - **Master Password** — Set a single global password that protects the entire web interface. - **Database Path** — Define where the application stores its own SQLite database. - **fail2ban Connection** — Specify how the application connects to the running fail2ban instance (socket path or related settings). - **General Preferences** — Any additional application-level settings such as default time zone, date format, or session duration. --- ## 2. Login Page - A simple password prompt with a single input field and a submit button. - No username — only the master password set during setup. - Every page in the application (except the setup page) requires the user to be authenticated. - If a user is not logged in and tries to access any page, they are automatically redirected to the login page. - After entering the correct password the user is taken to the page they originally requested. - A logout option is available from every page so the user can end their session. --- ## 3. Ban Overview (Dashboard) The main landing page after login. Shows recent ban activity at a glance. ### Server Status Bar - A persistent status indicator showing whether the fail2ban server is running or unreachable. - Displays the fail2ban version, the number of active jails, and total bans across all jails. - Shows combined statistics: total failures detected and total bans issued since the server started. ### Ban List - A table displaying all IPs that were banned within a selected time window. - **Columns:** Time of ban, IP address, requested URL / service, country of origin, target domain, target subdomain. - Rows are sorted by time, newest first. - A time-range selector with quick presets: - Last 24 hours - Last 7 days (week) - Last 30 days (month) - Last 365 days (year) ### Access List - A secondary view (tab or toggle) on the same page showing **all recorded accesses**, not just bans. - Uses the same table format: time, IP address, requested URL, country, domain, subdomain. - Shares the same time-range presets so the user can compare total traffic against banned traffic for the same period. --- ## 4. World Map View A geographical overview of ban activity. ### Map - A full world map rendered with country outlines only (no fill colours, no satellite imagery). - For every country that has at least one banned IP in the selected time range, the total count is displayed centred inside that country's borders. - Countries with zero banned IPs show no number and no label — they remain blank. - Time-range selector with the same quick presets: - Last 24 hours - Last 7 days - Last 30 days - Last 365 days ### Access List (Map context) - A companion table below or beside the map listing all accesses for the selected time range. - Same columns as the Ban Overview tables: time, IP, URL, country, domain, subdomain. - Selecting a country on the map filters the table to show only entries from that country. --- ## 5. Jail Management A dedicated view for managing fail2ban jails and taking manual ban actions. ### Jail Overview - A list of all jails showing their name, current status (running / stopped / idle), backend type, and key metrics. - For each jail: number of currently banned IPs, total bans since start, current failures detected, and total failures. - Quick indicators for the jail's find time, ban time, and max retries. ### Jail Detail - Selecting a jail opens a detailed view with all of its settings. - Shows every monitored log file path attached to that jail. - Shows all fail regex and ignore regex patterns in a readable list. - Shows the date pattern and log encoding used for parsing. - Shows all actions attached to the jail and their configuration. - Shows ban-time escalation settings if incremental banning is enabled (factor, formula, multipliers, max time). ### Jail Controls - Start or stop individual jails. - Toggle a jail into idle mode (pauses monitoring without fully stopping it) and back. - Reload a single jail to pick up configuration changes without restarting the entire server. - Reload all jails at once. ### Ban an IP - Input field to enter an IP address. - Option to select which jail the ban should apply to. - Confirm and execute the ban. - Visual feedback confirming the IP has been banned successfully. ### Unban an IP - Input field to enter an IP address, or select from the list of currently banned IPs. - Option to select the jail from which the IP should be unbanned, or unban from all jails. - Option to unban all IPs at once across every jail. - Confirm and execute the unban. - Visual feedback confirming the IP has been unbanned successfully. ### Currently Banned IPs - A quick-reference list of all IPs that are currently banned across all jails. - Each entry shows the IP, the jail it belongs to, when the ban started, and when it will expire (if applicable). - Shows how many times this IP has been banned before (ban count / repeat offender indicator). - Direct unban button next to each entry for convenience. ### IP Lookup - Enter any IP address to check whether it is currently banned, and if so in which jails. - Show the ban history for that IP: how many times it was banned, when each ban occurred, and from which jails. - Display enriched IP information: country, ASN (network operator), and Regional Internet Registry (RIR). ### IP Whitelist (Ignore List) - View the list of IP addresses or networks that are excluded from banning, per jail and globally. - Add an IP address or network range to a jail's ignore list so it will never be banned. - Remove an IP from the ignore list. - Toggle the "ignore self" option per jail, which automatically excludes the server's own IP addresses. --- ## 6. Configuration View A page to inspect and modify the fail2ban configuration without leaving the web interface. ### View Configuration - Display all active fail2ban jails and their current settings. - For each jail, show the associated filter and its regex patterns in a readable format. - Show global fail2ban settings (ban time, find time, max retries, etc.). ### Edit Configuration - Inline editing of jail parameters (ban time, max retries, enabled/disabled, etc.). - Inline editing of filter regex patterns. - Add or remove fail regex and ignore regex patterns per jail. - Edit the prefix regex used for pre-filtering log lines. - Configure the date pattern and log time zone for each jail. - Configure DNS resolution mode per jail (resolve all hostnames, IP only, etc.). - Configure ban-time escalation: enable incremental banning and set factor, formula, multipliers, maximum ban time, and random jitter. - Save changes and optionally reload fail2ban to apply them immediately. - Validation feedback if a regex pattern or setting value is invalid before saving. ### Add Log Observation - Option to register additional log files that fail2ban should monitor. - For each new log, specify: - The path to the log file. - One or more regex patterns that define what constitutes a failure. - The jail name and basic jail settings (ban time, retries, etc.). - Choose whether the file should be read from the beginning or only new lines (head vs. tail). - Preview matching lines from the log against the provided regex before saving, so the user can verify the pattern works. ### Regex Tester - Paste or type a sample log line into a text field. - Enter a fail regex pattern. - Immediately see whether the pattern matches the sample, with the matched groups highlighted. - Useful for crafting and debugging new filter rules before applying them to a live jail. ### Server Settings - View and change the fail2ban log level (e.g. Critical, Error, Warning, Info, Debug). - View and change the log target (file path, stdout, stderr, syslog, systemd journal). - View and change the syslog socket if syslog is used. - Flush and re-open log files (useful after log rotation). - View and change the fail2ban database file location. - Set the database purge age — how long historical ban records are kept before automatic cleanup. - Set the maximum number of log-line matches stored per ban record in the database. --- ## 7. Ban History A view for exploring historical ban data stored in the fail2ban database. ### History Table - Browse all past bans across all jails, not just the currently active ones. - **Columns:** Time of ban, IP address, jail, ban duration, ban count (how many times this IP was banned), country. - Filter by jail, by IP address, or by time range. - See at a glance which IPs are repeat offenders (high ban count). ### Per-IP History - Select any IP to see its full ban timeline: every ban event, which jail triggered it, when it started, and how long it lasted. - Merged view showing total failures and matched log lines aggregated across all bans for that IP. --- ## 8. External Blocklist Importer Automated downloading and applying of external IP blocklists to block known malicious IPs on a recurring schedule. ### Blocklist Sources - Manage a list of external blocklist URLs (e.g. `https://lists.blocklist.de/lists/all.txt`). - Add, edit, or remove blocklist source URLs through the web interface. - Each source has a name, URL, and an enabled/disabled toggle. - Support for plain-text lists with one IP address per line. - Preview the contents of a blocklist URL before enabling it (download and display a sample of entries). ### Schedule - Configure when the blocklist import runs using a simple time-and-frequency picker (no raw cron syntax required). - Default schedule: daily at 03:00 (server local time). - Available frequency presets: - Every X hours - Daily at a specific time - Weekly on a specific day and time - Option to run an import manually at any time via a "Run Now" button. - Show the date and time of the last successful import and the next scheduled run. ### Import Behaviour - On each scheduled run, download all enabled blocklist sources. - Validate that each downloaded entry is a well-formed IP address or CIDR range before applying it. - Apply downloaded IPs as bans through fail2ban (preferred) or directly via an iptables chain, depending on configuration. - If using an iptables chain: flush the chain before re-populating it so stale entries are removed automatically. - If using fail2ban: ban each IP in a dedicated jail created for blocklist imports so they are tracked separately from regular bans. - Skip empty lines and malformed entries gracefully instead of aborting the entire import. - Clean up temporary downloaded files after processing. ### Import Log - Keep a log of every import run: timestamp, source URL, number of IPs imported, number of entries skipped (invalid), and any errors. - Display the import log in the web interface, filterable by source and date range. - Show a warning badge in the navigation if the most recent import encountered errors. ### Error Handling - If a blocklist URL is unreachable, log the error and continue with remaining sources. - If curl (or the download mechanism) is unavailable, surface a clear error in the import log. - Notify the user (via the UI status bar) when a scheduled import fails so it does not go unnoticed. --- ## 9. General Behaviour - **Responsive layout** — Usable on desktop and tablet screens. - **Session persistence** — The user stays logged in until they explicitly log out or the session expires. - **Consistent navigation** — A sidebar or top navigation bar is visible on every page, providing quick access to all sections: Dashboard, World Map, Jails, Configuration, History, and Logout. - **Time zone awareness** — All displayed times respect the time zone configured during setup. - **Connection health** — The application continuously checks whether the fail2ban server is reachable and shows a clear warning when the connection is lost.