KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #ai-agents #dsh-plugin #codex #developer-tools #claude-code #windows #desktop-app #typescript #rust #ai-agent #cli

portscan-protection

★ 88 Open GitHub ↗

This script helps to avoid portscanning on Linux systems.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Portscan Protection (Linux)

## Description
Hackers and unskilled script-users often scan servers for open ports. If they find one, such as your SSH port, they will attempt to crack it. This script helps protect Linux systems with built-in firewall protection (iptables or nftables) from portscan attacks by automatically blocking the IP address of any attacker who attempts to access ports too quickly.

*The installation is simple and quick*

## Features

- **Automatic portscan detection and blocking** - Blocks IPs that scan too many ports too quickly
- **Dual firewall support** - Works with both iptables/ipset and nftables (auto-detected)
- **Systemd & Cron support** - Uses systemd if available, falls back to cron
- **Custom SSH port support** - Protects your custom SSH port from being blocked
- **Whitelist support** - Never block specific IP addresses
- **Blacklist support** - Always block specific IP addresses or CIDR ranges (e.g. known attacker IPs or entire subnets), auto-reapplies when the list changes, scales to tens of thousands of entries
- **Auto-update** - Automatically updates itself (can be easily toggled on/off)
- **Easy reinstall** - Reinstall with a single command

## Installation

1. **Install required packages:**
- Ubuntu/Debian (iptables):
    - >*sudo apt update && sudo apt install curl iptables ipset -y*
- Ubuntu/Debian (nftables):
    - >*sudo apt update && sudo apt install curl nftables -y*
- RedHat/CentOS (iptables):
   - >*sudo yum install curl iptables ipset -y*
- RedHat/CentOS (nftables):
   - >*sudo yum install curl nftables -y*

2. **Install Portscan Protection directly from GitHub:**
>*curl -s https://raw.githubusercontent.com/Feriman22/portscan-protection/master/portscan-protection.sh | sudo bash /dev/stdin -i*

If you run it without argument, you have several options:

**Before installation:**
1. Install
2. Verify
3. Quit

**After installation:**
1. Verify
2. Edit Whitelist
3. Edit Blacklist
4. Set SSH Port
5. Toggle Auto-Update
6. Update from GitHub
7. Reinstall
8. Uninstall
9. Quit

### Menu Options Explained

The `Install` process copies the script to the */usr/local/sbin* folder and then creates either a systemd service (if systemd is available) or a cron rule in the file called *portscan-protection* in the */etc/cron.d* folder. It is executed once by itself to enable the firewall rules, and every startup, so your server is protected at all times.

The `Uninstall` process removes the script from the */usr/local/sbin* folder, removes the systemd service or crontab entry, removes the configuration file, removes the whitelist and blacklist files, and deletes all firewall rules.
**WARNING!** After this step, you can no longer run the script from the */usr/local/sbin* folder!

The `Reinstall` process performs a complete uninstall followed by a fresh install. Useful for fixing issues. Your whitelist, blacklist, and SSH port setting are automatically backed up before the uninstall step and restored afterward, so they survive a reinstall.

The `Edit Whitelist` option allows adding IPv4 addresses to the whitelist. Add one IP per line to this file. These IP addresses will never be blocked. Note: Only IPv4 addresses are supported.

The `Edit Blacklist` option allows adding IPv4 addresses or CIDR ranges to the blacklist. Add one entry per line to this file - either a single IP (e.g. `203.0.113.5`) or a CIDR range (e.g. `203.0.113.0/24`). These will always be blocked (e.g. known botnet/attacker IPs, or an entire malicious subnet). The rules are automatically re-applied whenever the file changes - immediately if edited through this menu option, or within the auto-update check cycle if edited directly. Duplicate and invalid entries are ignored automatically, and a `/0` entry (which would match all addresses) is always rejected as a safety guard. Note: Only IPv4 is supported. If the whitelist and blacklist ever contain the same IP, the whitelist always takes priority.

The `Set SSH Port` option allows you to specify a custom SSH port. This ensures your SSH port won't be blocked even if you're using a non-standard port.

The `Toggle Auto-Update` option enables or disables the automatic update feature. Settings are saved to a configuration file.

The `Verify` process checks:
- The persistence method (systemd or cron)
- Whether the cron service is running (if using cron)
- The location and permissions of the script
- The configuration file settings
- Required commands (ipset/iptables or nft)
- Active firewall rules
- Whitelist validity
- Blacklist validity

The `Update from GitHub` process updates the installed script. You cannot update it before the installation!

## Daily use

Nothing to do! Just install the script and enjoy the protection! If you want to run the script again, just type `portscan-protection.sh` as root user.

### Arguments

If you want to use this script somewhere else (e.g. in an OS installer script), there are some arguments:

| Argument | Description |
| --- | --- |
| -i, --install | Install the script |
| -u, --uninstall | Uninstall the script without confirmation |
| -r, --reinstall | Reinstall the script (uninstall + install) |
| -v, --verify | Verify the installation |
| -up, --update | Update the script from GitHub |
| --toggle-autoupdate | Enable or disable auto-update feature |
| --set-sshport | Set custom SSH port |
| --cron | Run the script like the crontab/systemd does. It will only set firewall rules and auto-update the script if not disabled. No output. |

### Configuration File

After installation, a configuration file is created at `/usr/local/sbin/portscan-protection.conf` containing:

```bash
# Auto-update setting (YES or NO)
AUTOUPDATE="YES"

# Custom SSH port (default: 22)
SSHPORT="22"

# Firewall backend (iptables or nftables, leave empty for auto-detect)
FIREWALL_BACKEND=""
```

You can edit this file directly or use the menu options.

### Exit codes

| Exit code | What does it mean? |
| --- | --- |
| 0 | Everything was fine (no error) |
| 5 | Not enough permission. Run as root or with sudo |
| 6 | ipset command not found |
| 7 | iptables command not found |
| 8 | GitHub is not available |
| 9 | Answered *No* at Uninstall |
| 10 | Required commands not found (curl, iptables/ipset or nft) |
| 11 | nft command not found |
| 130 | Script canceled by *ctrl + c* |

## Firewall Backends

### iptables (Legacy)
The original backend using iptables and ipset. Still fully supported and will be used if nftables is not available.

**Required packages:** curl, iptables, ipset

### nftables (Modern)
The modern replacement for iptables. If both are available, the script auto-detects which one to use based on:
1. Existing rules (prefers the one already in use)
2. nftables if no existing rules found

**Required packages:** curl, nftables

You can force a specific backend by setting `FIREWALL_BACKEND` in the configuration file.

## Systemd vs Cron

The script automatically detects if systemd is available:

### Systemd (Preferred)
- Creates a service at `/etc/systemd/system/portscan-protection.service`
- Creates a timer at `/etc/systemd/system/portscan-protection.timer` for auto-updates
- Runs automatically at boot
- Old cron entries are automatically migrated

### Cron (Fallback)
- Creates an entry at `/etc/cron.d/portscan-protection`
- Runs 30 seconds after boot
- The `Verify` option checks if the cron service is running

## How to update

The script will automatically update itself after reboot (if auto-update is enabled).

**To disable auto-update:**
- Run the script and choose "Toggle Auto-Update" from the menu, or
- Run `/usr/local/sbin/portscan-protection.sh --toggle-autoupdate`, or
- Edit `/usr/local/sbin/portscan-protection.conf` and set `AUTOUPDATE="NO"`

**To manually update:**
Run the script and choose "Update from GitHub" or run:
`/usr/local/sbin/portscan-protection.sh --update`

## Backward Compatibility

This version is fully backward compatible with previous installations:
- Existing iptables rules are preserved
- Cron-based installations continue to work
- Systemd is only used for new installations or after reinstall
- Configuration file is created automatically on first run
- The new blacklist feature is fully optional and has no effect on existing installations until you use the `Edit Blacklist` menu option

## Roadmap

Planned/upcoming features:

- [x] **CIDR range support** for the blacklist (e.g. `203.0.113.0/24`) - block an entire IP range with a single entry, instead of listing individual IPs one by one - shipped, see changelog

## Changelog

>10-08-2026
- **Fix:** `Reinstall` no longer wipes your whitelist, blacklist, and SSH port/config settings - they're now automatically backed up before the uninstall step and restored afterward, then firewall rules are re-applied. Previously this was only documented as a risk to be aware of; now it just works safely.
- **Fix:** blacklist protection could silently fail to re-apply after a reboot if the blacklist file itself hadn't changed since the last run - the sync logic now also verifies the live ipset/nftables state before deciding there's nothing to do, so it self-heals after a reboot instead of relying on the blacklist file changing to trigger a re-apply

>09-08-2026
- **NEW:** Blacklist now supports CIDR ranges (e.g. `203.0.113.0/24`) alongside single IPs - handy for blocking an entire cloud provider block or botnet subnet in one entry
- **Performance:** blacklist enforcement rewritten to scale to tens of thousands of entries - iptables backend now uses a single `ipset` (atomically swapped on update) instead of one firewall rule per entry; nftables backend now applies changes in a single batched transaction instead of one command per entry
- Fixed a validation bug where the blacklist parser could silently fail on systems where `/usr/bin/awk` is `mawk` (the Debian/Ubuntu default) rather than `gawk`
- A `/0` entry (which would match all IPv4 addresses) is now always rejected as a safety guard, in addition to the existing loopback/any-address protections

>05-08-2026
- **NEW:** Blacklist support - permanently block known malicious IPs, one per line, with automatic re-apply whenever the file changes (via the `Edit Blacklist` menu option, or the auto-update check cycle for out-of-band edits)
- Blacklist entries are validated, de-duplicated, and invalid/unreadable input is safely ignored
- `Verify` now also reports blacklist validity
- Clarified that `Reinstall` wipes the whitelist, blacklist, and SSH port setting

>16-02-2026
- Improve code comments

>01-01-2026
- **NEW:** Systemd support (auto-detected, with fallback to cron)
- **NEW:** nftables support (auto-detected)
- **NEW:** Custom SSH port support
- **NEW:** Reinstall function
- **NEW:** Easy toggle for auto-update (menu option and --toggle-autoupdate argument)
- **NEW:** Configuration file for persistent settings
- **NEW:** Verify checks if cron service is running
- Migration from cron to systemd on reinstall
- Improved firewall backend detection
- Added exit code 11 for missing nft command

>26-06-2023
- Use *command -v* instead of *which*
- Code simplification
- Small bugfixes

>14-03-2023
- Fix bug [#9](https://github.com/Feriman22/portscan-protection/issues/9)

>16-08-2022
- Bugfix: iptables flush has been removed
- Using _printf_ instead of _echo -e_
- Small text modifications

>05-04-2021
- Whitelist editor improved
- Installer not copied twice on the server thanks to direct install from GitHub
- cURL, iptables and ipset command verification (Exit code 10)
- Small text modifications

>04-04-2021
- Whitelist function
- Use cURL instead of wget
- Smarter way to update
- Different menus before and after install
- Shorter code (combine similar *if* structures in one *for* cycle)
- Replace original installer with symlink to avoid confusing
- Small bugfixes

>01-02-2021
- Bugfix: ipset and iptable commands are not found on CentOS systems
- Bugfix: Crontab syntax was wrong
- Bugfix: Run update process only if new version available

>28-04-2020
- Error codes have been added

>26-04-2020
- More efficient update process

>15-04-2020
- Update option added
- Auto-update function added
- Check for an update at the startup of the script
- Remove ipset and iptable rules at uninstalling
- Arguments added (-i, --install, -u, --uninstall, -v, --verify, -up, --update, --cron)
- Activate/remove ipset and iptable rules with variables
- The test condition for install has been improved
- Small typos fixed

>14-04-2020
- Copy the script in /usr/local/sbin directory instead of /root
- Use variables for menu selection instead of touch temp files
- Insert cron entry in /etc/cron.d folder instead of the main cron file
- Code review & cleanup
- Small bugs fixed

>13-04-2020
- Initial release

## Supporters

Thanks to the following people for supporting this project:

- **Aldas** - $200 via PayPal, sponsoring development of the Blacklist feature

## Do not forget

If you found my work helpful, I would greatly appreciate it if you could make a **[donation through PayPal](https://paypal.me/BajzaFerenc)** to support my efforts in improving and fixing bugs or creating more awesome scripts. Thank you!

portscan-protection

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README