799953468/frp-ban

What it does

frp-ban is a security plugin for frps, the frp server component. frps calls the plugin's HTTP POST /handler endpoint before Login and NewUserConn, and the plugin rejects any IP present in its in-memory ban list, so banned hosts cannot open tunnels. The ban list is backed by a JSON file and expired entries are cleaned up automatically.

The distribution path is the other half: FrpBan.Client runs on separate machines, watches log files with FileSystemWatcher, matches lines against YAML rules (for example, repeated SSH failures from the same IP), and sends ban requests to the server over a TLS-encrypted binary TCP protocol. The server enforces connection and message rate limits, a 64 KiB body cap, TLS 1.2/1.3 only, and pooled frame buffers. It is aimed at operators running frps who want automatic IP blocking driven by logs from multiple hosts.

Quick start

Prerequisites: .NET SDK for source builds, an existing frps instance, and a TLS certificate (a self-signed one is fine for development).

1. Configure the server in src/FrpBan/appsettings.json: set PluginSettings.Token to a long random secret, BanFilePath, and Tls.CertificatePath/CertificatePassword. Startup rejects placeholder tokens and secrets shorter than 32 characters. Secrets can instead be supplied as environment variables such as PluginSettings__Token.
2. Generate a development certificate:

openssl req -x509 -newkey rsa:4096 -keyout server-key.pem -out server-cert.pem -days 365 -nodes \
  -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
openssl pkcs12 -export -out server.pfx -inkey server-key.pem -in server-cert.pem

3. Build and run the server, then the client:

cd src/FrpBan && dotnet run
cd src/FrpBan.Client && dotnet run

4. In the client's appsettings.json, set ServerAddress, ServerPort (default 9443), the same Token, and TLS trust options. Point CaCertificatePath at server-cert.pem when testing with the self-signed certificate.
5. Add a rule under src/FrpBan.Client/rules.d/, for example a threshold rule on /var/log/auth.log matching Failed password.*from (?<ip>\d+\.\d+\.\d+\.\d+) with maxMatches: 5, windowSeconds: 300 and banDurationSeconds: 3600.
6. Register the plugin in frps.toml:

[[httpPlugins]]
name = "frp-ban"
addr = "127.0.0.1:9000"
path = "/handler"
ops  = ["Login", "NewUserConn"]

Result: bans triggered by matched log lines are sent over TLS and rejected at frps login time. Prebuilt packages for Windows, macOS, Linux (deb, rpm, Arch, Alpine, portable) on x64 and ARM64 are described in the release packaging guide.

Constraints

• Rules support only logSource.type: file; journal is defined but not implemented and is rejected at rule loading.
• The client retry queue is memory-only: queued bans survive reconnection but not a process restart.
• HTTP callbacks bind to loopback by default; if frps runs on another host you must change the listener and trusted callback addresses explicitly.
• TLS 1.2/1.3 only, with per-IP limits of 10 new connections and 120 messages per minute, and at most 100 concurrent TLS connections by default. All are configurable.
• The client service account needs read access to monitored logs (for example, membership in adm on systems where auth.log is owned by that group).
• Performance figures in the README are implementation limits, not benchmarks; latency and memory use depend on workload.
• MIT licensed. IPv6 has not been fully tested, and journal monitoring, a whitelist, metrics, a web UI and container images are listed as roadmap items.

HotRepo's take

On 2026-11-10 the project was recorded on the new-project list with 127 stars, up 26 in the observed growth window; there is no GitHub daily ranking entry. The repository is young and forks remain at 0, so the in-memory ban approach and the TLS client/server split are the concrete things to evaluate. The design is straightforward: lookup via a concurrent dictionary, file-based monitoring instead of log polling, and a binary protocol with explicit rate limits — the README is unusually explicit about what is enforced versus what is still planned, which helps operators judge fit before deploying.