v0.0.7

v0.0.7

One on/off switch for slow brute-force protection, now covering forwarded ports, and an activity log that explains every ban.

English guide ·
Chinese guide

Changes

• SSH_SLOW_PROTECTION=on/off replaces SSH_SLOW_MODE. It sits directly below
  JAIL_PER_PORT and is on for new installations. on detects, logs and bans;
  off does none of these.
• Forwarded ports are now covered. Logins through the tunnel are invisible, so new
  connections are counted: more than 300 per source across all forwarded ports in
  24 hours with shared jails (banned on all ports), or 100 on one port with per-port
  jails (banned on that port). Port 22 keeps 20 failed logins in 24 hours.
• Administrators are learned automatically: LEARN_ADMINS=on whitelists the source
  of a successful login to this server by root, the settings owner, or a member of
  sudo, admin or wheel, with no usernames to type in. Each new login renews
  the 90-day period. It is also enabled on upgrade; it only adds trust.
• Sources in whitelist.conf under any port are known administrators and are never
  counted by slow protection.
• Administrators on unstable networks are no longer banned by their own key retries.
  Keys rejected inside a login that then succeeds do not count; rejected keys in a
  dropped connection count once per connection.
• New default ban durations: 12 hours for a first offense, then 3 days, 7 days,
  30 days and 90 days. Existing settings keep their own values; see the migration
  notes to adopt the new ones.
• Repeat offenders keep their step. A ban within 90 days after the previous ban
  ended moves one step up, and a source released from a 90-day jail that offends
  again gets another 90 days. A clean 90 days after a ban starts over;
  unban/release forgives.
• ~/.frp-ssh-guard/frp-ssh-guard.log replaces alerts.log. It records every ban
  with its reason, limit and end time, plus manual bans, strike escalations, releases
  and accepted settings; newest first, capped by LOG_MAX_SIZE (formerly
  ALERT_LOG_MAX_SIZE).
• One section per port in blocklist.conf and whitelist.conf. Busy lists no
  longer repeat headers such as [22]; automatic bans follow the manual lines,
  sorted by address, with an address's runtime and strike lines together.
• settings.conf explains when and how changes take effect. blocklist.conf
  explains that an entry without a time is permanent and gives examples.
• Fix: a list holding a subnet plus an address inside it (same ports) no longer
  makes nftables reject every rule. Covered entries are skipped in the firewall and
  kept in the file; overlaps that cannot be stored are reported with both lines.
• List errors name the cause and line; several smaller fixes are listed in the changelog.

Upgrading

sha256sum --ignore-missing -c SHA256SUMS
sudo apt install ./frp-ssh-guard_0.0.7.deb

An active guard is refreshed automatically. If you downloaded v0.0.7 before,
download both files again; APT upgrades the earlier download. Upgrades never start
bans you did not choose: SSH_SLOW_MODE=enforce becomes on (which now also covers
forwarded ports), while observe, off or a missing value become off. To enable
it later, whitelist administrators who use many forwarded machines, set
SSH_SLOW_PROTECTION=on, then run sudo frp-ssh-guard check && sudo frp-ssh-guard reload.
The settings file is converted in place with a private backup, so status shows
pending edits until the next check and reload. See the
migration notes.

Limits

Connection counts are an approximate token bucket that refills across the window,
and a SYN retransmission counts as a new attempt. Heavy legitimate users of
forwarded ports who are not whitelisted can reach the limits. Kernel bans are
sampled about once a minute for the log. Validation status is recorded in
VALIDATION.md.

_{An X-project by XyberMind.}

v0.0.6

v0.0.6

Add automatic upgrade activation, slow SSH detection with enforcement for fresh installations, private local alerts and timestamped reports.
Existing fast protection, jail scope and ban lifetimes stay in place.

English guide ·
Chinese guide

Changes

• Switching jail modes affects new bans only. Existing shared and per-port bans
  retain their original scopes and expiry in both directions. Strike history
  keeps the recorded scope so later timer runs cannot broaden old per-port bans
  or discard shared history. Explicit manual scopes and whitelist exceptions
  are unchanged. Settings changes still require check/reload.
• An active guard is refreshed automatically during
  apt install, including the running SSH monitors. No manual reload is needed.
  Accepted policy choices, pending edits, saved ban scope/expiry, boot enablement
  and timer schedules are retained. Firewall rate meters reset.
• Fresh settings default to SSH_SLOW_MODE=enforce: 20 failures / 24 hours
  trigger a ban when local SSH protection is enabled. Existing off, observe
  or enforce choices are retained; older missing settings preserve observe.
  Thresholds, jail scope, ban durations and learning preferences are unchanged.
• Shared journal deduplication and classification of successful logins before learning.
  Learning remains opt-in and supports password, public key and PAM successes.
• Newest-first ~/.frp-ssh-guard/alerts.log, default 10MiB cap. Oldest complete
  records are discarded without archives. Offline homes use a bounded private spool.
• Suspected IPv4 /24 and IPv6 /64 clusters are reported, never automatically blocked.
• doctor checks monitoring and access. report 24h filters event timestamps and
  reports failures, thresholds, new bans and sampled packet drops separately.
• Authentication bans are recorded directly and reconciled with sampled kernel bans
  so one ban contributes one strike. Earlier strike history remains available.

Validation

Local regression tests cover fresh enforcement, observation mode, preserved explicit
choices, legacy missing settings and accepted snapshots. Disposable VM checks and
CI results are recorded in VALIDATION.md.

Install or upgrade

Download frp-ssh-guard_0.0.6.deb and SHA256SUMS from Assets:

sha256sum --ignore-missing -c SHA256SUMS
sudo apt install ./frp-ssh-guard_0.0.6.deb

For an already active installation, the updated guard takes effect automatically.
The download filename is unchanged; APT upgrades earlier v0.0.6 downloads automatically.
This maintainer-requested correction replaces the earlier v0.0.6 package and
checksum; download both files again. Older v0.0.4 and v0.0.5 releases are unchanged.

Fresh or disabled installations still require port selection and enable.
Native SSH protection and whitelist learning remain opt-in. An existing
observation-only installation stays observation-only after upgrading. To change
that policy, set SSH_SLOW_MODE=enforce and run check/reload once; package
installation itself requires no manual reload. Pending settings edits are not
applied by the upgrade. An active trial remains
temporary. Administrator service policy can defer refresh with a notice.
Refresh failures are reported to APT; failed firewall validation/application
retains previous protection. status, doctor and report 24h are optional checks.

Limits

New long-window coverage begins at activation; recent legacy short-window state
is imported. Packet sampling intervals may straddle report boundaries, and sudden
power loss can lose unsampled drops. Packet counts are not connection counts or
proof that no unauthorized login occurred. Observation tables are bounded and
reports disclose capacity loss. Subnet and new-source login alerts need review.

Learning trusts a source IP, not an identity across changing addresses. A successful
compromised account can teach trust. The guard does not change sshd authentication
configuration; Fail2ban and other firewalls remain independent.

See the validation record
for platforms and tests. Full Ubuntu FRP/systemd runtime and ARM/32-bit runtime
have not been verified. The v0.0.5 tag and package remain unchanged.

_{An X-project by XyberMind.}

v0.0.5

FRP-SSH-Guard v0.0.5

Protect FRP-forwarded SSH ports and optionally the server's SSH port 22, with
shared or per-port jails and upgrades that preserve your configuration.

English guide ·
Chinese guide ·
Examples ·
Migration instructions

What's new

• Optional native SSH protection: PROTECT_SERVER_SSH=on enables port-22
  connection limits and failed/invalid-user login detection. Default: off.
• Shared jails by default; JAIL_PER_PORT=on separates automatic bans by port.
• Settings and combined manual/automatic lists live in ~/.frp-ssh-guard/.
  Lists have comments, [all] and per-port sections, origin labels and expiry times.
  Manual block entries support forever or tier=1 through tier=5.
• Installation imports existing jails automatically, preserves their port scope
  and remaining lifetime, and adds missing settings without overwriting custom values.
• Trusted SSH login learning supports password, public key and PAM authentication.
  Configure LOGIN_USERS to enable it; successful logins refresh learned expiry.
• Upgrades preserve active jails and timer deadlines. Manual blocks can be permanent
  or timed, across all protected ports or selected ports.

Install or upgrade

Download frp-ssh-guard_0.0.5.deb and SHA256SUMS from Assets:

sha256sum --ignore-missing -c SHA256SUMS
sudo apt install ./frp-ssh-guard_0.0.5.deb
frp-ssh-guard --version
sudo frp-ssh-guard status

APT replaces the installed program files and keeps your settings. An internal
Debian revision lets it recognize newer builds; the release version is v0.0.5.
No manual uninstall or copying of jailed IPs is required.

Installation does not enable protection or adopt pending settings. Find the
settings path with frp-ssh-guard --help, then apply desired changes:

sudo frp-ssh-guard check && sudo frp-ssh-guard reload
sudo frp-ssh-guard status

Use enable instead of reload for first activation. An explicit reload also
starts the updated SSH monitors. List edits are watched while active; use
sudo frp-ssh-guard apply to apply them immediately with the accepted settings.
Saved entries retain their original expiry across reload and reboot.

Notes

• Whitelists override this guard only. Fail2ban and other firewall rules remain independent.
• Learning needs trusted LOGIN_USERS and local sshd journal records; forwarded
  SSH authentication outcomes are encrypted and unavailable to the guard.
• Kernel bans are sampled by the log timer, normally within 60 seconds. Unsampled
  entries can be lost on an abrupt restart. Legacy entries without a saved or live
  timeout receive the configured duration once during migration.
• The first upgrade from v0.0.4 can rebase a custom OnActiveSec deadline through
  that version's old removal hook. See the migration guide for older development packages.
• See the validation record
  for tested platforms and limitations. ARM/32-bit and full Ubuntu FRP/systemd
  runtime have not been verified.

The uploaded assets are the .deb and its checksum file. GitHub also provides
source ZIP and tar.gz downloads from the tag.

_{An X-project by XyberMind.}

v0.0.4

FRP-SSH-Guard limits excessive connection attempts to FRP-forwarded SSH ports using nftables. Install it on the public Linux host running frps, then select the forwarded SSH ports to protect.

Current public version: v0.0.4 (pre-release).

Download and install

Download frp-ssh-guard_0.0.4.deb and SHA256SUMS from the assets below. The package contains architecture-independent Bash/Python scripts for Debian/Ubuntu. CI validates x64 (amd64); ARM and 32-bit systems have not been verified.

sha256sum --ignore-missing -c SHA256SUMS
sudo apt install ./frp-ssh-guard_0.0.4.deb
sudoedit /etc/frp-ssh-guard/settings.conf
# Set PROTECTED_PORTS to your actual FRP-forwarded SSH TCP ports.
sudo frp-ssh-guard check
sudo frp-ssh-guard enable
sudo frp-ssh-guard status

Installation alone does not activate firewall rules. Later configuration changes take effect with sudo frp-ssh-guard reload after validation.

If replacing a package from before the public version-number correction, use sudo apt install --allow-downgrades ./frp-ssh-guard_0.0.4.deb to correct the version numbering while preserving settings. See the migration guide.

Source and documentation

The complete project is open source under the MIT license. GitHub automatically provides source ZIP and tar.gz downloads from the v0.0.4 tag; no duplicate source bundles are uploaded. SHA256SUMS covers the Debian package.

• English deployment guide
• 中文部署指南
• Changelog

Validation and status

CI validates the regression suite, real nftables rules in an isolated network namespace, reproducible package builds and checksums, and package installation/migration/removal/purge on Debian 12 and Ubuntu 24.04.

This remains a pre-release: full systemd reboot, timed-trial, learning, and live FRP traffic acceptance checks on disposable VMs are pending. See the validation procedure. The deployment figures in the README are operator-reported observations from one deployment, not guaranteed protection rates.

Passed validation CI.

Privacy reissue — 2026-10-25

The source history, release tag, and package have been rebuilt with invented deployment examples. Private deployment details must not appear in public code, templates, tests, documentation, or downloads. Local commit/push hooks, CI checks, and package scans now check future changes; private matching rules are kept outside the source tree.

Download both the package and its updated SHA256SUMS again; previous checksums no longer apply. Existing contributors should make a fresh clone instead of merging old history. This reissue does not change a deployed server’s selected ports or firewall settings.