Stop Bots

A TUI and a CLI that help you configure your server to stop bad bots without hiding behind a CDN. It is a fancy UI for your existing web server (nginx or Apache) and your firewall (nftables or iptables). For those of us that don't want to hide behind Cloudflare and give one company the keys to all kingdoms.

It protects you in two ways:

• Preventative - It downloads known bot lists and IP ranges and blocks them. I particularly recommend using Geo-blocking. For private servers, you can use an allowlist and block more than 90% of all attacks.
• Responsive - It monitors access logs and detects attackers and kicks them out. Note that this means a few packets will reach your server before they are detected, but at least it will stop them from escalating.

It tries to keep you from doing something self-destructive. You will always see what changes first before you apply it, and you can use the --dry-run flag for extra safety. But I suspect eventually you will want to enable auto-apply, for convenience. Because of this, the app also tries not to lock you out. IP addresses with successful SSH logins are never blocked, webserver configs are always tested before application and it tries to recognize apps running behind HTTP proxies and adapts the dynamic detection rules to the apps.

Big red button: sudo stop-bots uninstall all

The rest of this readme was written by the AI. Feel free to ask your own AI to summarize it, I won't mind.

What happens to my server

Installing starts nothing, and nothing is written until you apply. On the first apply, with the settings a new database starts with:

• Blocked by user agent: the Scanner and AI crawler categories. Search engines are allowed.
• Watching the logs: six detectors are on: SSH scanners, web scanners, forged crawlers, probes for secrets, injection attempts and login brute force. The rest are off (see From your logs).
• Blocked by address: nothing yet. Countries, reputation feeds and hosting providers are all off until you turn them on, so the firewall starts with only what the detectors find.

And this is what gets written where:

What	Where
The blocking rule	inside each site's server block, between # BEGIN stop-bots and # END stop-bots
Files the rule needs, when a setting needs one (robots.txt, rate limiting)	/etc/stop-bots/nginx/ and NGINX's conf.d (for Apache, /etc/stop-bots/apache/ and conf-enabled)
The firewall script	/etc/stop-bots/firewall.next.nft (or .next.sh for iptables), copied to firewall.nft once applied; it only touches its own inet stop_bots table
Settings, blocks and why each exists	/var/lib/stop-bots/db.sqlite3

Here is sudo stop-bots batch --dry-run --diff on a fresh database and a one-site NGINX, trimmed (the real user-agent pattern is a few hundred names long):

Dry run: nothing is downloaded, scanned, written, applied or recorded. Against the database as it is, `batch` would:
NGINX: 1 file(s) would change:
  /etc/nginx/sites-enabled/example.com
Firewall (nftables): 0 rule(s), 0 kernel entries; no applied script at /etc/stop-bots/firewall.nft yet, so all of it is new
lockout check passed: the SSH log was read, and no connected client would be blocked
would write 0 rule(s) to /etc/stop-bots/firewall.next.nft; not applied — review it, then apply it (“Apply everything” or `stop-bots render-firewall --apply`)
--- /etc/nginx/sites-enabled/example.com
+++ /etc/nginx/sites-enabled/example.com
@@ -1,4 +1,10 @@
 server {
+    # BEGIN stop-bots (DO NOT EDIT)
+    if ($http_user_agent ~* "AgentReadinessScanner|AIScan|ArgusScanner|…|xAI-Grok|zmap-proxy-probe") {
+        return 403;
+    }
+    # END stop-bots
+
     listen 443 ssl;
     server_name example.com;
     root /var/www/example.com;
--- /etc/stop-bots/firewall.nft (does not exist)
+++ /etc/stop-bots/firewall.next.nft
@@ -0,0 +1,29 @@
+#!/usr/sbin/nft -f
+# Generated by stop-bots 0.2.0. Not executed automatically — review, then run
+# with: nft -f <this file>
…
+add table inet stop_bots
+delete table inet stop_bots
+add table inet stop_bots
+add chain inet stop_bots bot_block { type filter hook input priority -1; policy accept; }
…

Quick start

Install

On Debian or Ubuntu, from the APT repository:

curl -fsSL https://ivankovic.github.io/stop-bots/key.gpg \
  | sudo tee /usr/share/keyrings/stop-bots.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/stop-bots.gpg] \
https://ivankovic.github.io/stop-bots stable main" \
  | sudo tee /etc/apt/sources.list.d/stop-bots.list
sudo apt update && sudo apt install stop-bots

Or cargo install stop-bots with Rust 1.88 or newer, or a static binary for x86_64 or aarch64 Linux from the GitHub releases, each with a checksum and a build provenance attestation (verifying a download). Installing starts nothing.

It is tested on Debian and Ubuntu with systemd, and NGINX or Apache. It needs nft, or iptables-restore and ip6tables-restore, for the firewall. Caddy is not supported.

NGINX is the default. On an Apache host, say so once, and enable mod_rewrite, which the blocks are written in:

sudo stop-bots set-web-server apache
sudo a2enmod rewrite

Apache support is newer than NGINX's and has been tested on the Debian and Ubuntu layout (/etc/apache2). A few features are NGINX-only, rate limiting among them.

Try it without a server

From a clone of this repository, with Podman (or STOP_BOTS_CONTAINER_RUNTIME=docker) and a Rust toolchain:

make demo

That builds the binary and drops you into a shell in a throwaway Ubuntu container running NGINX, with a few bad requests already in its log and a list of things to try. The firewall rules it applies stay inside the container, and exit deletes it.

Run it

sudo stop-bots starts the TUI. It needs root, because it rewrites your web server's config and loads firewall rules. ? explains whatever is under the cursor, and ? again shows every key on every screen.

Run every command with sudo. Without root, stop-bots cannot open /var/lib/stop-bots/db.sqlite3 and falls back to a database of your own (it prints which), with none of your settings in it.

Or from the CLI, for scripts:

sudo stop-bots status
sudo stop-bots batch --dry-run --diff
sudo stop-bots batch --apply
sudo stop-bots install firewall
sudo stop-bots status

stop-bots --help lists every command.

Keep it running

Nothing re-runs on its own. Detection, list updates and the rest run on a schedule that only ticks while the TUI is open, or when cron runs it. On a server you don't sit in front of, let cron run it:

sudo stop-bots install cron --dry-run    # read the plan
sudo stop-bots install cron

That writes /etc/cron.d/stop-bots, which runs stop-bots tick every minute: the detectors each minute, the lists every week, the same jobs the TUI's Dashboard lists under Scheduled tasks. sudo stop-bots status says when they last ran.