12 KiB
12 KiB
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.