273 lines
12 KiB
Markdown
273 lines
12 KiB
Markdown
# 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.
|
|
|
|
|