BanGUI/Docs/Features.md

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 redirects to the login page and cannot be used again.
• The SetupGuard component checks the setup status on every protected route; if setup is not complete it redirects the user to /setup.
• Security: The master password is SHA-256 hashed in the browser using the native SubtleCrypto API before it is transmitted. The backend then bcrypt-hashes the received hash with an auto-generated salt. The plaintext password never leaves the browser and is never stored.

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)

---

4. World Map View

A geographical overview of ban activity.

Map

• A full world map rendered with country outlines, showing ban activity through color-coded fills (no satellite imagery).
• Color coding: Countries are colored based on their ban count for the selected time range:
  • Red: High ban count (100+ bans by default)
  • Yellow: Medium ban count (50 bans by default)
  • Green: Low ban count (20 bans by default)
  • Transparent (no fill): Zero bans
  • Colors are smoothly interpolated between the thresholds (e.g., 35 bans shows a yellow-green blend)
  • The color threshold values are configurable through the application settings
• Interactive zoom and pan: Users can zoom in/out using mouse wheel or touch gestures, and pan by clicking and dragging. This allows detailed inspection of densely-affected regions. Zoom controls (zoom in, zoom out, reset view) are provided as overlay buttons in the top-right corner.
• For every country that has bans, the total count is displayed centred inside that country's borders in the selected time range.
• Countries with zero banned IPs show no number and no label — they remain blank and transparent.
• Clicking a country filters the companion table below to show only bans from that country.
• Time-range selector with the same quick presets:
  • Last 24 hours
  • Last 7 days
  • Last 30 days
  • Last 365 days

---

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.
• A toggle to also show Inactive Jails — jails that are defined in fail2ban config files but are not currently running.
• Each inactive jail has an Activate button that enables and reloads it immediately, with optional overrides for ban time, find time, max retries, port, and log path.

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

• The Jails, Filters, and Actions tabs each use a master/detail list layout:
  • A scrollable left pane lists all items (jail names, filter filenames, action filenames).
  • Each item displays an Active or Inactive badge. Active items are sorted to the top; items within each group are sorted alphabetically.
  • A jail is "active" if fail2ban reports it as enabled at runtime. A filter or action is "active" if it is referenced by at least one enabled jail.
  • Inactive jails (present in config files but not running) are discoverable from the Jails tab. Selecting one shows its config file settings and allows activating it.
  • Clicking an item loads its structured configuration form in the right detail pane.
  • On narrow screens (< 900 px) the list pane collapses into a dropdown above the detail pane.
• Show global fail2ban settings (ban time, find time, max retries, etc.) on the Global Settings tab.

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.
• Activate an inactive jail directly from the Jails tab detail pane, with optional parameter overrides.
• Deactivate a running jail from the Jails tab; writes enabled = false to a local override file and reloads fail2ban.

Raw Configuration Editing

• Every jail, filter, and action detail pane includes a collapsible Raw Configuration section at the bottom.
• The section shows the complete raw text of the config file (.conf) in an editable monospace textarea.
• The user can edit the raw text directly and click Save Raw to overwrite the file on disk.
• The textarea loads lazily — the raw file content is only fetched when the section is first expanded.
• A save-state indicator shows idle / saving / saved / error feedback after each save attempt.

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.

Map Settings

• Configure the three color thresholds that determine how countries are colored on the World Map view based on their ban count:
  • Low Threshold (Green): Ban count at which the color transitions from light green to full green (default: 20).
  • Medium Threshold (Yellow): Ban count at which the color transitions from green to yellow (default: 50).
  • High Threshold (Red): Ban count at which the color transitions from yellow to red (default: 100).
• Countries with ban counts between thresholds display smoothly interpolated colors.
• Countries with zero bans remain transparent (no fill).
• Changes take effect immediately on the World Map view without requiring a page reload.

Log

• A dedicated Log tab on the Configuration page shows fail2ban service health and a live log viewer in one place.
• Service Health panel (always visible):
  • Online/offline badge (Running / Offline).
  • When online: version, active jail count, currently banned IPs, and currently failed attempts as stat cards.
  • Log level and log target displayed as meta labels.
  • Warning banner when fail2ban is offline, prompting the user to check the server and socket configuration.
• Log Viewer (shown when fail2ban logs to a file):
  • Displays the tail of the fail2ban log file in a scrollable monospace container.
  • Log lines are color-coded by severity: errors and critical messages in red, warnings in yellow, debug lines in grey, and informational lines in the default color.
  • Toolbar controls:
    • Filter — substring input with 300 ms debounce; only lines containing the filter text are shown.
    • Lines — selector for how many tail lines to fetch (100 / 200 / 500 / 1000).
    • Refresh button for an on-demand reload.
    • Auto-refresh toggle with interval selector (5 s / 10 s / 30 s) for live monitoring.
  • Truncation notice when the total log file line count exceeds the requested tail limit.
  • Container automatically scrolls to the bottom after each data update.
• When fail2ban is configured to log to a non-file target (STDOUT, STDERR, SYSLOG, SYSTEMD-JOURNAL), an informational banner explains that file-based log viewing is unavailable.
• The log file path is validated against a safe prefix allowlist on the backend to prevent path-traversal reads.

---

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.