Feature Request: Optional fail2ban Integration

[Humble-Helper-96]

The Problem

A production OpenTAKServer running on a server with a public IP receives a continuous, high volume of unsolicited probe traffic against the nginx-facing ports (80, 443, 8443, 8446). On my deployment, in a representative 24-hour window I observed roughly 800+ remote HTTP requests from over 100 unique source IPs, with the bulk concentrated in three families of scanners:

• Asus router exploit scanners hitting /SETTINGS.CFG, /login.cgi, and /appGet.cgi?hook=get_cfg_clientlist() with the asusrouter-- user agent
• Generic CGI/path-traversal probes against URLs like /cgi-bin/.%2e/.%2e/.%2e/bin/sh
• Censys/Shodan-style inventory scanners

All of these are rejected by nginx with a 400 response and never reach OTS itself — so functionally my server is fine. But the noise has practical costs:

1. AbuseIPDB shows the top two scanner IPs in my logs (a /24 in Romania, ASN 47890) have each been reported over 4,000 times. This is not background internet noise — it's targeted, persistent, automated probing that will not stop on its own.
2. The eud_handler_ssl.log fills with PEER_DID_NOT_RETURN_A_CERTIFICATE SSL handshake warnings every few minutes from scanners hitting :8443 without a client cert. This obscures real SSL issues with legitimate EUDs.
3. The nginx access log grows much faster than it would otherwise, making forensic review harder and chewing through disk on smaller deployments.
4. Every probe consumes a small amount of CPU and a TLS handshake. Multiplied by hundreds per day across multiple scanners, this is a measurable load on smaller hardware (RPi installs especially).

A standard, well-understood remediation for this exists — fail2ban — and it's already a dependency-friendly addition on every platform OTS currently supports. But setting it up correctly requires knowing the OTS log file paths, the nginx access log location, what a legitimate vs. malicious request looks like, and which ports to protect. None of that is documented in the OTS install path today, so most operators either don't deploy it or set it up incorrectly.

Proposed Solution

Add optional fail2ban integration to the OpenTAKServer installer (OpenTAKServer-Installer). On supported platforms, the installer would:

1. Prompt the user (or accept a CLI flag like --install-fail2ban) to enable fail2ban integration during the OTS install
2. Install fail2ban if not already present
3. Drop in OTS-specific filter files and a jail config that fail2ban can pick up automatically
4. Pre-populate sensible defaults for the threshold/findtime/bantime that match the threat profile (persistent scanners with no legitimate use case → long bans)
5. Add a documentation section in docs.opentakserver.io explaining what the jails do and how to tune them

The default config would protect the nginx-facing ports (80, 443, 8443, 8446) by banning IPs that generate excessive 400 responses from nginx. Legitimate ATAK/iTAK/WinTAK clients hit /Marti/api/... endpoints with 200/201/401 responses and would never trigger the filter. I have verified this on my own deployment across a representative sample of normal client traffic vs. scanner traffic — they are cleanly distinguishable by status code alone.

This would be opt-in since some operators run OTS behind their own WAF, reverse proxy, or VPN where fail2ban would be redundant or harmful.

Implementation Outline

Within the existing OTS ecosystem, this could be done with relatively few moving pieces:

OpenTAKServer-Installer changes

In ubuntu_installer, debian_installer, and raspberry_pi_installer:

1. Add a step (after nginx config) that asks: "Install and configure fail2ban to protect OTS from internet scanners? [Y/n]" — or skip the prompt if --install-fail2ban / --no-fail2ban is passed
2. If yes:
   • apt install -y fail2ban
   • Copy filter file to /etc/fail2ban/filter.d/opentakserver-nginx.conf
   • Copy jail file to /etc/fail2ban/jail.d/opentakserver.conf
   • Restart fail2ban

Filter file: /etc/fail2ban/filter.d/opentakserver-nginx.conf

[Definition]
# Match any 400 response in nginx access log for OTS-facing ports
# Legitimate TAK clients (ATAK/iTAK/WinTAK) hitting /Marti/api/* endpoints
# get 200/201/401 responses, not 400 - so this is scanner-specific.
failregex = ^<HOST> - .* "(GET|POST|HEAD|OPTIONS|PROPFIND|PRI) .* HTTP/.*" 400 .*$
ignoreregex =

Jail file: /etc/fail2ban/jail.d/opentakserver.conf

[opentakserver-nginx]
enabled = true
filter = opentakserver-nginx
action = iptables-multiport[name=ots-nginx, port="80,443,8443,8446", protocol=tcp]
logpath = /var/log/nginx/access.log
maxretry = 10
findtime = 3600
bantime = 30d

Defaults rationale

• maxretry = 10 — Generous enough that legitimate misconfigured clients aren't penalized for a handful of bad requests; tight enough to catch determined scanners quickly
• findtime = 1 hour — Matches the cadence of the most persistent scanners observed in the wild (typically one probe every 5–15 minutes)
• bantime = 30 days — These scanners are not transient or accidental. They've been reported thousands of times across the internet. There is no benefit to a short ban; the same IP will return the moment the ban expires

Optional: second jail for EUD handler SSL probes

The EUD handler logs PEER_DID_NOT_RETURN_A_CERTIFICATE warnings to ~/ots/logs/eud_handler_ssl.log when scanners hit :8443 without a client cert. A second jail could ban on this pattern with similar thresholds. This would have to be configured carefully since the OTS logs live in the OTS user's home directory by default (~/ots/logs/), but fail2ban needs to be able to read them — either by symlinking into /var/log/opentakserver/ or by adjusting fail2ban's permissions config. The nginx-based jail alone catches roughly 90% of the scanner traffic in my observation, so this could be a phase-2 enhancement.

Documentation

Add a "Hardening" section to the docs covering:

• What the fail2ban integration does and doesn't protect against
• How to view currently banned IPs (fail2ban-client status opentakserver-nginx and iptables -L f2b-ots-nginx -n)
• How to unban an IP if needed
• How to whitelist trusted source IPs via ignoreip
• How to disable the jail without uninstalling fail2ban
• Note that this is a complement to, not a replacement for, proper OTS authentication and certificate-based EUD enrollment

Why This Is Worth Building In Rather Than Documenting

The pattern detection is mechanical and well-understood — every operator who deploys OTS to the public internet is going to face the same scanner traffic and benefit from the same configuration. Documenting it as a "highly recommended optional step" works, but most operators won't do it. Bundling it as an opt-in installer step makes secure-by-default deployment practical without sacrificing flexibility for operators who don't want it.

[Humble-Helper-96]

Companion Feature Request: fail2ban Management UI in the OTS Admin Panel

Companion to the fail2ban installer integration feature request. That request adds fail2ban to the OTS install path. This request adds a management surface for it inside the OTS UI itself.

The Problem

If fail2ban becomes part of the standard OTS deployment, operators still need to manage it. Today that means SSH'ing into the server and running CLI commands:

• fail2ban-client status <jail> to see who's banned
• fail2ban-client set <jail> unbanip <ip> to release someone who got caught by mistake
• iptables -L f2b-<jail> -n to see the actual firewall state
• tail /var/log/fail2ban.log to understand recent activity
• Editing /etc/fail2ban/jail.d/opentakserver.conf to tune thresholds

For an operator who knows fail2ban, this is fine. For the broader OTS user base — especially the substantial number of operators running OTS on a Raspberry Pi at home or a small VPS — terminal-only management is a real friction point, and the answer is often "just leave it at the defaults forever and never look at it again." That works until a legitimate user gets banned and the operator has to figure out how to free them.

The OTS Admin panel already exposes administrative functions (Users, Groups, Scheduled Jobs, Plugin Updates, Device Profiles, Server Plugin Manager, Link TAK.gov Account). Adding fail2ban management here keeps the operator in one familiar interface and turns "scanner mitigation" from a hidden background concern into something the operator can actually see and tune.

Proposed Solution

Add a "Security → Banned IPs" (or similar) page to the OTS Admin section of the UI. The page would provide:

1. A live list of currently banned IPs across all OTS-managed fail2ban jails
2. A view of recent ban/unban activity (last 24 hours, last 7 days)
3. Per-jail configuration tuning (maxretry, findtime, bantime, whitelist)
4. A "Manually Ban IP" action for operator-initiated bans
5. An "Unban" action for releasing IPs from the firewall
6. AbuseIPDB reputation lookup as an optional enrichment layer

This builds on the installer integration. If fail2ban wasn't installed via the installer, the UI page would gracefully show "fail2ban not configured" with a link to the docs.

What the UI Could Look Like

Top of page — summary cards

Similar to the existing Server Status dashboard cards:

• Currently Banned — count of IPs currently banned across all OTS jails
• Banned (24h) — count of new bans in the last 24 hours
• Top Offender — most-banned IP this week (with country flag from GeoIP if available)
• Jail Status — green/yellow/red indicator for each OTS-managed jail (active, partial, error)

Main table — currently banned IPs

Columns:

IP Address	Country	Jail	Banned Since	Time Remaining	Reason / Last Match	Actions
193.46.255.72	🇷🇴 RO	opentakserver-nginx	14 Jun 13:42	29d 23h	GET /SETTINGS.CFG 400	[Unban] [Lookup]
80.94.95.226	🇧🇬 BG	opentakserver-nginx	14 Jun 14:01	29d 23h	POST /login.cgi 400	[Unban] [Lookup]

The [Lookup] action could open a modal with AbuseIPDB data (if the operator has configured an API key) showing report count and confidence score — useful context for deciding whether to make a ban permanent or extend it.

Configuration section

Editable form for each OTS-managed jail:

Jail: opentakserver-nginx                                [Enabled ✓]
  Max retries before ban:    [10]
  Time window:               [60 minutes]
  Ban duration:              [30 days]
  Protected ports:           [80, 443, 8443, 8446]
  Whitelist (ignoreip):      [127.0.0.1/8, 10.0.0.0/8, ...]
                             [+ Add IP/CIDR]
  [Save] [Reset to defaults]

Changes would write to /etc/fail2ban/jail.d/opentakserver.conf and reload fail2ban.

Manual ban / whitelist actions

A simple form: "Ban this IP" with a duration selector, or "Whitelist this IP" to add it to ignoreip. Both useful for operators who get a report of suspicious activity but want to act before fail2ban catches it on its own.

Activity log

A scrollable log of recent ban/unban events, filterable by jail and time range. Useful for diagnosing complaints like "user X says they can't reach the server" — a 30-second check confirms whether their IP got swept up in a ban.

Implementation Outline

Backend (OTS Python / Flask)

Add a new blueprint at opentakserver/blueprints/security.py with these endpoints:

GET  /api/security/fail2ban/status          → status of all OTS-managed jails
GET  /api/security/fail2ban/banned          → list of currently banned IPs
GET  /api/security/fail2ban/activity        → recent ban/unban events
POST /api/security/fail2ban/ban             → manually ban an IP
POST /api/security/fail2ban/unban           → manually unban an IP
GET  /api/security/fail2ban/config/<jail>   → current jail config
PUT  /api/security/fail2ban/config/<jail>   → update jail config
POST /api/security/abuseipdb/lookup/<ip>    → AbuseIPDB lookup (optional)

The backend can either shell out to fail2ban-client or talk to the fail2ban socket directly (Python's socket module works against /var/run/fail2ban/fail2ban.sock). Direct socket access is faster and gives structured responses. Activity log can be read from /var/log/fail2ban.log with a simple parser.

Permission considerations: OTS runs as a non-root user. Fail2ban-client requires either root or membership in a privileged group. Options:

• Add the OTS user to a group that has read access to the fail2ban socket and read/write access to /etc/fail2ban/jail.d/opentakserver.conf
• Use a small setuid helper binary (cleaner, more constrained surface)
• Use sudo with a tightly scoped sudoers rule (matches what most fail2ban web UIs already do)

The installer integration (companion request) would set this up automatically.

Frontend (OTS-UI / TypeScript + Mantine)

Add a new section to the Admin nav: Security, with subitems:

• Banned IPs
• Activity Log
• Configuration

Each maps to a Mantine-styled page consuming the backend endpoints above. Existing OTS-UI patterns (tables, modals, the alert/banner system) carry over cleanly.

Optional integrations

• AbuseIPDB lookup — if the operator adds an AbuseIPDB API key in the existing OTS config, the UI shows the report count + confidence inline. Free tier of AbuseIPDB allows 1,000 checks/day which is plenty for any single deployment.
• GeoIP country lookup — bundle MaxMind GeoLite2 Country (free, ~6MB) to show country flags next to IPs in the banned list. Helpful for at-a-glance threat assessment.
• Export ban list — CSV/JSON export of currently banned IPs for sharing with other operators or as evidence for upstream reports.

Why This Belongs in the UI Rather Than Just Docs

The OTS admin user persona is, in many cases, the same person who runs the church AV setup, the small-team field operation, or a hobbyist meshtastic deployment — competent enough to follow an installer script, but not necessarily someone who's going to comfortably manage fail2ban from the command line. Putting management in the UI accomplishes two things:

1. It makes the security feature visible — operators see what's happening, develop intuition for normal vs. abnormal traffic, and learn to recognize when a real attack is in progress vs. routine scanner noise
2. It removes the "I think I banned my friend, how do I undo this" support burden — a one-click unban is dramatically less intimidating than fail2ban-client set opentakserver-nginx unbanip 1.2.3.4

This also fits cleanly with OTS's overall design philosophy of "TAK server administration that doesn't require a TAK admin background."

Suggested Phasing

Given the scope, this could ship in stages:

Phase 1 — Read-only

Banned IP list, activity log, jail status. No configuration changes from the UI yet. Lowest risk to land; immediately useful.

Phase 2 — Actions

Manual ban/unban, whitelist management. Requires the permission model to be settled.

Phase 3 — Configuration

Editable jail configs from the UI. Requires careful validation to avoid bricking fail2ban with malformed input.

Phase 4 — Enrichment

AbuseIPDB, GeoIP, export. Pure additive value once the foundation is solid.

---