L'app fa del suo meglio per non bloccarti fuori dal server, ma la usi a tuo rischio. E nota che è distribuita sotto licenza AGPL, quindi se la usi commercialmente, assicurati di rispettare la lettera della licenza.

Installazione

Da crates.io:``` cargo install stop-bots

Un binario Linux x86_64 precompilato è disponibile nelle release su GitHub.

Dipendenze

Richiede Rust 1.88 o versione successiva per la compilazione. In pratica solo Linux: invoca systemctl, nginx -t e nft/iptables, quindi anche se compila altrove non sarà di grande utilità lì.

Utilizzo

Esegui il binario senza argomenti per avviare la TUI, stop-bots web per le stesse schermate in un browser (vedi L'interfaccia web), oppure consulta stop-bots --help per l'elenco completo dei sottocomandi CLI. La TUI e la CLI possono essere usate insieme. Configura tutto nella TUI e poi usa la CLI in un crontab per mantenere le regole aggiornate.

Puoi uscire dall'app, o tornare indietro da un popup/sottomenu, con 'q' o Escape.

Tema

Puoi passare tra il tema scuro e quello chiaro con 't'. L'app proverà a rilevare automaticamente il tema, ma per alcune combinazioni di terminale e multiplexer non ci sono informazioni sufficienti per fare la scelta corretta.

Schermate

1–4 (o d/b/s/p) saltano direttamente a una schermata; Left/Right, o i loro alias vim h/l, le scorrono in sequenza; ? attiva/disattiva un riferimento completo delle combinazioni di tasti in qualsiasi momento, e : apre una command palette che elenca ogni azione per nome. Tab / Shift+Tab si spostano sempre tra i pannelli della schermata corrente, mai tra le schermate.

La Dashboard possiede tutto ciò che finisce nello script del firewall; Site settings possiede tutto ciò che finisce nella configurazione NGINX. Questa suddivisione decide dove risiede ogni impostazione.

• Dashboard (la schermata predefinita): valori predefiniti delle categorie a livello di sistema (Scanners / Search Bots / AI Bots — Allowed o Blocked); geo-blocking a livello di host (blocca o consenti specifici paesi); un pannello "Automatic blocking" con un interruttore on/off per ogni rilevatore e ogni blocklist di terze parti; un pannello "Firewall script" (quante regole scriverebbe un render, se lo script su disco è obsoleto, e le site e le bot list da cui è generato); un pannello "Scheduled" che mostra i job del cron interno e quando sono stati eseguiti l'ultima volta (con uno spinner accanto a qualsiasi job attualmente in esecuzione in background); e un Log di ciò che l'app ha fatto l'ultima volta. Una striscia di stato sotto le schede mostra i controlli di integrità dell'host su ogni schermata. Up/Down scorrono tra le tre liste; m cambia la modalità geo. Premi F per generare le regole del firewall correnti in uno script — il popup ha anche un interruttore "apply after writing" (Space) per applicarlo effettivamente immediatamente, invece di applicarlo manualmente dopo. Altri tre tasti agiscono sull'intero host: u scarica tutte le liste, a applica entrambi i piani (NGINX, poi il firewall), e w mette questa console dietro NGINX — gli stessi tre che il browser ha come pulsanti e un pannello.
• Bot settings: elenca ogni sorgente di bot-list conosciuta (con un'azione per aggiornarla) e ogni singolo bot, ricercabile per nome, con un override per bot (Allowed / Blocked / segui il valore predefinito della categoria).
• Site settings: un pannello "NGINX settings" (Tab per metterlo a fuoco) che contiene le scelte a livello di host che modellano la configurazione generata — cosa riceve una richiesta bloccata (vedi sotto), se servire un robots.txt generato, e il rate limiting — sopra ogni sito NGINX scoperto su disco, ciascuno con uno stato live "up to date / stale / not found" e azioni per applicare la policy corrente a un sito o a tutti. Modificare una di queste impostazioni porta ogni sito applicato a STALE, che è il tuo segnale per riapplicare. Aprire un sito ti permette di sovrascrivere la sua policy di categoria/bot, attivare una qualsiasi delle sei regole sulla forma delle richieste, e elencare i percorsi esenti dal blocco.
• Dynamic Protection: una vista live e azionabile di ciò che sta attualmente colpendo il server — "Top IPs attempting SSH connection" e "Top User Agents", ciascuno classificato per conteggio e taggato NOT BLOCKED/BLOCKED (mostrato in rosso). Tab/Shift+Tab cambiano a quale dei due pannelli si applicano Up/Down; f cicla un filtro condiviso (all / not blocked only / blocked only); Enter blocca la riga NOT BLOCKED selezionata, o la sblocca se è già BLOCKED. i ispeziona l'indirizzo selezionato: quali dei feed di reputazione lo elencano, se è all'interno di un range di crawler pubblicato (che è ciò che separa un vero Googlebot da uno user agent che si limita a dichiararlo), a quale paese appartiene, e quali account ha tentato di usare per il login. Tutto da liste che questo host ha già scaricato — non c'è reverse DNS o lookup whois qui, perché un record PTR è scritto da chi detiene l'indirizzo e sarebbe testo fornito dall'attaccante che si legge come autorevole.
• Help: il riferimento completo delle combinazioni di tasti.

Bot settings, dove risiede ogni sorgente di lista e ogni singolo bot:

Site settings, dove le scelte NGINX a livello di host si trovano sopra ogni sito trovato su disco:

Dynamic Protection, la vista live di ciò che sta colpendo il server in questo momento:

Da cosa protegge effettivamente

Usando la configurazione NGINX

• Bot conosciuti, per categoria (scanner / motore di ricerca / crawler AI), provenienti da ArcJet's Well-Known Bots, ai.robots.txt e la lista NGINX Ultimate Bad Bot Blocker . Bloccare una categoria inietta una regola if ($http_user_agent ...) nella configurazione NGINX di ogni sito (apply-blocks / a/A di Site settings).

• Troppe richieste, tramite il rate limiting di NGINX stesso. A differenza di tutto il resto qui questo è applicato da NGINX al momento della richiesta anziché analizzando un log in seguito. Disattivato per impostazione predefinita: un limite tarato per il sito sbagliato allontana visitatori reali.

• Con cortesia, prima — un robots.txt generato opzionale che elenca ogni bot che stai bloccando, per i crawler che lo rispettano, più il percorso honeypot qui sotto. Disattivato per impostazione predefinita, perché sostituisce qualunque cosa il tuo sito serva oggi su /robots.txt.

• Tranne dove dici diversamente — esenzioni di percorso per sito, così puoi bloccare i crawler AI ovunque tranne /blog.

• Richieste che non sembrano provenire da un browser, per sito. Sei regole indipendenti, ciascuna con il proprio interruttore e ciascuna disattivata per impostazione predefinita — un interruttore per regola così che se qualcosa tuo smette di funzionare, puoi capire quale regola lo ha causato:

  Due salvaguardie si applicano a tutte, e sono applicate anziché lasciate a te:

  • Le due regole dipendenti da TLS sono scritte solo nei blocchi server HTTPS. I browser non fanno HTTP/2 senza TLS, quindi su un blocco listen 80 semplice ogni richiesta è HTTP/1.1 — incluso il redirect che un browser effettua verso HTTPS. I tuoi blocchi sulla porta 80 e sulla porta 443 di solito condividono un server_name, quindi l'impostazione raggiunge entrambi; solo quello TLS riceve quelle regole. Le regole sulla forma degli header funzionano su HTTP semplice e sono scritte su entrambi.
  • /.well-known/ è sempre esente non appena una qualsiasi regola è attiva. È lì che Let's Encrypt recupera la sua challenge HTTP-01, su HTTP/1.1 senza Accept e spesso senza User-Agent — senza l'esenzione il tuo certificato smette di rinnovarsi settimane dopo.

Cosa riceve effettivamente una richiesta bloccata

Una scelta a livello di host, in Site settings. Questi non sono codici di stato intercambiabili — ciascuno dice qualcosa di diverso, e la differenza conta soprattutto per i client che non intendevi intercettare:

Il tarpit è l'opzione più gentile per un falso positivo — un client intercettato per errore viene rallentato, non rifiutato — e la più gravosa in termini di costo per un bot, la cui connessione resta inattiva. Due cose da sapere prima di sceglierlo: occupa anche una delle tue connessioni worker per tutta la durata, quindi un diluvio di client in tarpit compete con i visitatori reali per worker_connections; e quanto duri effettivamente dipende da come NGINX sceglie di scrivere un piccolo corpo di errore, cosa annotata in TODO.md come da verificare contro un server reale.

Dai tuoi log, automaticamente

Ciascuno di questi è un interruttore indipendente nel pannello "Automatic blocking" della Dashboard, e ciascuno aggiunge un blocco firewall temporaneo che scade da solo e viene riaggiunto se il comportamento continua.

Funzionano su un timer interno che rilegge i tuoi log di accesso SSH e NGINX ogni minuto — ma solo mentre la TUI o l'interfaccia web è in esecuzione. Una delle due mantiene lo stesso programma, nello stesso database, quindi lasciare attiva l'interfaccia web è sufficiente; nulla viene rilevato quando nessuna delle due è in esecuzione. Per un server senza alcun processo stop-bots, vedi Unattended, from cron qui sotto.

• Scanner SSH e web: IP con una serie di login SSH falliti, o molti percorsi distinti che hanno restituito 404. Mai un IP con un login SSH riuscito recente, o uno all'interno del range IP pubblicato di un crawler conosciuto.
• Crawler falsificati: qualsiasi cosa dichiari di essere Googlebot, Bingbot o GPTBot da un indirizzo che l'operatore di quel crawler non pubblica. Il travestimento comune più economico che esista, e le liste CIDR pubblicate lo risolvono. Inerte finché quelle liste non sono state effettivamente recuperate.
• Sondaggio di segreti esposti: una singola richiesta per /.env, /.git/config, /wp-config.php e simili è conclusiva di per sé, quindi questo non richiede soglia. La lista integrata omette deliberatamente percorsi che sono legittimi da qualche parte — /wp-login.php, /wp-admin/, /xmlrpc.php, /phpmyadmin — poiché bloccare il tuo stesso amministratore sarebbe peggio che mancare uno scanner che il rilevatore 404 intercetta comunque. Aggiungi i tuoi con set-probe-paths.
• Honeypot: un percorso pubblicato solo come Disallow: nel robots.txt generato e linkato da nessuna parte. Raggiungerlo significa ignorare robots.txt, cosa che nulla di legittimo fa per caso — il segnale più forte qui, e il blocco più lungo. Richiede che la generazione di robots.txt sia attivata per funzionare.

Altri tre esaminano come un client si comporta anziché cosa chiede. Tutti e tre sono disattivati per impostazione predefinita, perché ciascuno ha un falso positivo che non può escludere da solo — e tutti e tre esentano i crawler dei motori di ricerca verificati, che altrimenti corrisponderebbero a ognuno di essi:

• Non recupera asset: molte pagine distinte e nemmeno un foglio di stile, script o immagine. I browser caricano ciò che accompagna una pagina. Non intercetta un client API (conta i percorsi distinti, e un client API ne visita pochi) né un visitatore di ritorno ben memorizzato nella cache (un 304 conta come asset recuperato). Non può aiutarti su un sito che non serve alcun asset — una pura API JSON.
• User agent rotante: diverse identità da un solo indirizzo. Notevolmente indebolito dal NAT: un gateway di operatore, campus o ufficio presenta molti browser reali su un solo IP, e senza l'analisi dei timestamp non c'è modo di distinguerlo da uno scraper che cicla gli agent.
• Crawling senza referer: molte pagine profonde distinte, mai un Referer. Indebolito da Referrer-Policy: no-referrer e dagli strumenti per la privacy; la soglia di percorsi distinti è ciò che lo rende utilizzabile.

Per indirizzo

• Interi paesi, tramite le liste CIDR aggregate di IPdeny — blocca paesi specifici, o passa alla modalità allow-list e blocca tutto il resto.
• Indirizzi noti come malevoli, tramite liste di terze parti: FireHOL livello 1, nodi di uscita Tor e blocklist.de. Tutti disattivati per impostazione predefinita.
• Interi provider di hosting: AWS, Google Cloud e DigitalOcean pubblicano il loro spazio di indirizzi, e i visitatori residenziali non navigano da lì. Questi sono strumenti poco raffinati ed etichettati come tali — bloccano ogni visitatore ospitato lì, inclusi endpoint VPN, uscite aziendali e client API, non solo i bot. Disattivati per impostazione predefinita, con un avviso quando ne attivi uno.
• Indirizzi vicini, opzionalmente: quando diversi indirizzi in un unico IPv4 /24 vengono segnalati nello stesso passaggio, blocca il /24. Disattivato per impostazione predefinita — bloccare 256 indirizzi perché tre si sono comportati male è un danno collaterale per design. (IPv6 è diverso e non richiede interruttore: un rilevamento blocca sempre il /64, perché un /64 è una LAN, la stessa cosa che rappresenta un singolo indirizzo IPv4. Bloccare il singolo indirizzo che un attaccante IPv6 ha usato per caso non fermerebbe nulla — ne hanno altri 2^64.)
• Qualsiasi altra cosa, manualmente — aggiungi direttamente una regola di allow o block per IP/CIDR, o usa la schermata Dynamic Protection per bloccare permanentemente uno specifico IP o user agent che hai individuato prima che superi una soglia automatica.

Sta effettivamente funzionando?

Tutto quanto sopra è generato. Se qualcosa di esso sia in vigore è una domanda separata, e stop-bots status è quello che risponde:``` stop-bots status

Un controllo che non è riuscito a essere eseguito — nft list richiede i privilegi di root — riporta UNKNOWN, mai OK. Un controllo di integrità che dice che va tutto bene perché non ha potuto guardare è peggio di nessun controllo, perché viene creduto.

Lo stesso report è sulla Dashboard sia nella console che nella TUI, acquisito ogni ora dal cron interno anziché a ogni render: nft list su un grande ruleset è megabyte di testo.

Non succede nulla senza di te

Ogni decisione sul firewall di cui sopra è generata, mai applicata automaticamente: render-firewall (o il tasto f della Dashboard) scrive uno script iptables o nftables che puoi rivedere e applicare da solo, e rifiuta di scriverne uno che bloccherebbe una sessione SSH attualmente connessa.

Tre cose possono applicarlo per te, e tutte e tre richiedono che tu lo chieda: il popup di render della TUI ("apply after writing") o il suo tasto a, il pannello firewall della console web ("run it after writing") o il suo pulsante "Apply everything", e batch --apply da un crontab che hai scritto — vedi Unattended, from cron. Nessuno di essi è un effetto collaterale di qualcosa di automatico: il cron interno genera lo script e non lo esegue mai.

Lo stesso vale sul lato NGINX: cambiare un'impostazione cambia solo ciò che sarebbe scritto. Site settings mostra ogni sito come STALE finché non applichi.

Disattivare un rilevatore non rimuove mai i blocchi che ha già aggiunto — quelli scadono da soli. "Stop detecting" e "undo what was detected" sono deliberatamente separati; il secondo è la schermata Dynamic Protection o remove-firewall-rule.

C'è anche un semplice conteggio degli access log, indipendente dal blocco: record-access-stats / list-access-stats contano quanto spesso ciascun user agent compare nelle richieste riuscite (non di errore), così puoi vedere chi sta effettivamente visitando oltre a chi viene bloccato.

Unattended, from cron

stop-bots batch è un'unica passata su tutto ciò che la TUI fa manualmente: aggiorna ogni lista, analizza i log, scrive le regole di blocco NGINX e lo script del firewall.```

One full pass a night. Refreshes the lists, scans the logs, applies both.

0 4 * * * root /usr/local/bin/stop-bots batch --apply --ssh-log /var/log/auth.log

And detection every ten minutes, without re-downloading lists that change weekly.

*/10 * * * * root /usr/local/bin/stop-bots batch --apply --no-fetch --ssh-log /var/log/auth.log

Si associa a 127.0.0.1:8787 — raggiungibile solo da quella macchina — e stampa una password generata una sola volta, al primo avvio. Raggiungilo dal tuo laptop tramite un tunnel SSH:``` ssh -L 8787:127.0.0.1:8787 your-server

Scrive /etc/systemd/system/stop-bots-web.service, crea /var/lib/stop-bots (0700 — contiene l'hash della password della console) e /etc/stop-bots, genera una password se non ne esiste una, e abilita e avvia l'unità.

--dry-run stampa l'intero piano e non modifica nulla. Questo è l'unico comando nel progetto che avvia un demone, quindi inizia da lì. --prefix <dir> scrive lo stesso albero in un posto che puoi leggere senza root. Se l'unità esiste già e l'hai modificata, l' installer si ferma e lo segnala invece di sostituire la tua modifica; --force se lo intendevi davvero.

Il servizio viene eseguito come root, perché la console riscrive /etc/nginx, scrive lo script del firewall, ed esegue nginx -t e systemctl reload nginx. Non esiste una separazione non privilegiata che lasci intatto il set di funzionalità. L'unità porta con sé l'hardening che sopravvive a quel requisito e un commento che dice quale hardening è stato omesso e perché.

L'indirizzo di bind, la allowlist degli host e il prefisso del percorso sono deliberatamente non nell'unità — il server in esecuzione li rilegge dal database, quindi metterli in ExecStart darebbe loro due fonti di verità. Modificali con stop-bots web --save ... e riavvia.

Una cosa cambia una volta che questo viene eseguito come root: il job giornaliero RenderFirewall del cron interno può ora scrivere /etc/stop-bots/firewall.nft, cosa che non poteva fare quando eseguivi la console a mano come te stesso. Nulla applica quello script — eseguirlo è ancora compito tuo.

Viene verificato solo Debian, perché è quello che è stato testato; l'unità è molto probabilmente corretta su qualsiasi distribuzione systemd, ma il percorso del log SSH che assume è quello di Debian.

Esporlo

Il binding di qualsiasi cosa che non sia loopback richiede un secondo flag deliberato, perché questa console può riscrivere il firewall e la configurazione NGINX dell'host su cui viene eseguita:``` stop-bots web --bind 0.0.0.0:8787 --expose --allowed-hosts admin.example.com --save

Dietro TLS, imposta anche web:secure_cookie. Senza di esso un browser invierà il cookie di sessione anche a un URL http:// per lo stesso host.

web:trust_forwarded_for è più importante di quanto sembri. Senza di esso ogni richiesta dietro un proxy arriva da 127.0.0.1, quindi la console non può distinguere un client da un altro — il che significa che una raffica di tentativi di login condivide lo stesso bucket di throttle che usi tu, e la guardia che impedisce di bloccare il tuo stesso indirizzo non ha nulla con cui confrontarsi. Con esso, entrambi funzionano per-client.

Dietro NGINX: un sottodominio, o un prefisso di percorso

La console può configurarlo per te, e anche la TUI (w sulla Dashboard). Entrambe scrivono la configurazione NGINX, registrano il prefisso di percorso e aggiungono il nome host alla allowlist — le tre cose che devono concordare, perché un prefisso mancante fa uscire ogni link dal blocco location e un nome host mancante rende ogni richiesta un 403. Entrambe validano con nginx -t prima che la configurazione possa avere effetto, la annullano se fallisce, e registrano il nuovo indirizzo solo una volta validato.

Due modalità, e path è quella predefinita per un motivo: aggiunge un blocco location a un sito che hai già, quindi la console eredita il certificato di quel sito. Un sottodominio ne richiede uno proprio, e finché certbot --nginx -d <host> non è stato eseguito, il modulo password e il cookie di sessione di questa console attraversano la rete in chiaro.

Il resto di questa sezione è la stessa cosa fatta a mano, che vale la pena leggere una volta anche se usi il pannello — la trappola della barra finale qui sotto è l'errore che esiste per prevenire.

Un sottodominio è il deployment più semplice, e quello da scegliere se puoi:```nginx server { server_name stopbots.example.com; location / { proxy_pass http://127.0.0.1:8787; proxy_set_header Host $host; } }

Installazione da sorgente

Utilizzo

Utilizzo di base

Utilizzo avanzato

Riferimento API

Classe Cipher

Classe HashManager

Configurazione

Le opzioni di configurazione possono essere impostate tramite variabili d'ambiente:

• CRYPTO_KEY - Chiave di cifratura predefinita
• CRYPTO_ALGORITHM - Algoritmo da utilizzare (predefinito: aes-256)
• CRYPTO_LOG_LEVEL - Livello di logging (predefinito: INFO)

Licenza

Questo progetto è distribuito sotto la licenza MIT. Consultare il file LICENSE per i dettagli.``` stop-bots web --allowed-hosts stopbots.example.com --save

| -s | --server | SERVER | http://localhost:8080 | URL del server MCP | | -t | --token | TOKEN | - | Token di autenticazione | | -v | --verbose | - | false | Abilita logging dettagliato | | -h | --help | - | - | Mostra il messaggio di aiuto |

Esempi

Sviluppo

Configurazione

Struttura del progetto

Aggiunta di nuovi strumenti

Per aggiungere un nuovo strumento, crea un nuovo file nella directory src/tools/:

Risoluzione dei problemi

Problemi comuni

Il server non si avvia

• Verifica che la porta non sia già in uso
• Controlla che tutte le dipendenze siano installate
• Esamina i log per messaggi di errore

Errori di connessione

• Verifica che l'URL del server sia corretto
• Controlla che il token di autenticazione sia valido
• Assicurati che il firewall consenta la connessione

Gli strumenti non funzionano

• Verifica che gli strumenti siano registrati correttamente
• Controlla la validità dello schema di input
• Esamina i log per errori di esecuzione

Logging

Abilita il logging dettagliato per eseguire il debug dei problemi:

I log vengono scritti su stderr e possono essere reindirizzati a un file:

Contribuire

I contributi sono benvenuti! Segui questi passaggi:

1. Fai il fork del repository
2. Crea un branch per la funzionalità (git checkout -b feature/amazing-feature)
3. Esegui il commit delle modifiche (git commit -m 'Add amazing feature')
4. Esegui il push sul branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

Linee guida per i contributi

• Scrivi test per le nuove funzionalità
• Aggiorna la documentazione secondo necessità
• Segui lo stile del codice esistente
• Assicurati che tutti i test passino prima di inviare

Licenza

Questo progetto è rilasciato sotto la Licenza MIT - consulta il file LICENSE per i dettagli.

Ringraziamenti

• Model Context Protocol per le specifiche
• Tutti i contributori che hanno reso possibile questo progetto

Supporto

• Documentazione: https://docs.example.com
• Issue: https://github.com/your-org/mcp-server/issues
• Discussioni: https://github.com/your-org/mcp-server/discussions```nginx location /stop-bots/ { proxy_pass http://127.0.0.1:8787; # NO trailing slash proxy_set_header Host $host; }

Il comando viene suddiviso in parole ed eseguito direttamente. Non passa mai attraverso una shell, quindi ;, | e $VAR sono caratteri ordinari anziché sintassi.

Contribuire

Come è strutturato il codice, come viene testato e le regole secondo cui è scritto sono in CONTRIBUTING.md. Il processo di rilascio è in RELEASING.md.

Contatti

Puoi contattarmi all'indirizzo [email protected].

Licenza

Copyright (C) 2026 Marko Ivankovic

Questo programma è software libero: puoi ridistribuirlo e/o modificarlo secondo i termini della GNU Affero General Public License come pubblicata dalla Free Software Foundation, versione 3 della Licenza, o (a tua scelta) qualsiasi versione successiva.

Consulta il file LICENSE per il testo completo della Licenza.

Non puoi usare software AGPL?

Una licenza alternativa NON è disponibile.