guard

Segue una sorgente di log e blocca automaticamente gli IP che superano le soglie. Le esecuzioni normali modificano il firewall; usa --dry-run per eseguire il rilevamento senza modificare firewall o file di stato.

Sintassi

caddy-analyze guard [source] [flags]
# source: file, docker://name, k8s://pod -n ns, journalctl://unit, or via caddy-analyzer.json
# see Log Sources for syntax — this page covers guard flags only

Flag

Protezione automatica dall'auto-ban

Dalla v0.8.0, --protect-self=true protegge per default gli indirizzi delle interfacce e di uscita pubblica del server. Include le richieste dei processi che condividono lo stesso router/NAT casalingo. Il rilevamento avviene all'avvio, ogni 30 secondi e prima di ogni nuovo ban, così un cambio dell'IP WAN viene verificato prima del blocco. Un aggiornamento riuscito sostituisce gli indirizzi precedenti senza aggiungere voci al file whitelist.

La protezione ha precedenza sulle soglie di richieste/auth/404, sui pattern, sui feed blocklist, sulle regole geografiche e sui ban di subnet che contengono un IP del server. Le regole già tracciate che coprono un indirizzo protetto vengono rimosse dal firewall e dallo stato salvato. Le rimozioni fallite rimangono tracciate per riprovare. Il dry-run segnala would_unblock senza modificare firewall o stato.

Il rilevamento pubblico usa richieste HTTPS dirette e specifiche per famiglia a ipify, con icanhazip come alternativa. Ignora le impostazioni del proxy HTTP. Ogni richiesta ha un timeout di 4 secondi e il rilevamento un limite complessivo di 10 secondi. Un errore in una famiglia richiesta, incluso IPv6 configurato senza connettività Internet, fa fallire il controllo. Le verifiche prima del ban sono sincrone e aggiungono latenza.

Se il rilevamento fallisce all'avvio, guard non parte; durante l'esecuzione conserva gli IP protetti noti e sospende i nuovi ban fino al recupero. Entrambi gli errori indicano di riavviare con --protect-self=false. Consulta Risoluzione dei problemi → protezione IP del server.

Su una VPS remota l'IP casalingo/mobile dell'amministratore è normalmente diverso da quello del server: aggiungilo separatamente con --never-block o whitelist. Le sorgenti dietro lo stesso NAT ricevono la stessa esenzione pubblica; l'IPv6 distinto di un altro dispositivo non è protetto automaticamente. Esegui guard sulla stessa rete/via di uscita dei processi da proteggere. Questa funzione non modifica Fail2Ban e non impedisce i comandi manuali espliciti block.

Esempio minimo

modifica il firewall — gli IP del server sono protetti automaticamente. Per l'amministrazione remota autorizza anche l'IP del client.

# Sostituisci con l'IP pubblico della postazione amministratore, non della VPS
ADMIN_IP=203.0.113.10
sudo caddy-analyze guard --never-block "$ADMIN_IP" --limit 50 --window 1m /var/log/caddy/access.log

Server con IP fisso o rete limitata

modifica il firewall — disabilita il rilevamento del server e conserva gli indirizzi fidati espliciti. Salta i controlli delle interfacce e dell'IP pubblico, non la whitelist esplicita.

sudo caddy-analyze guard /var/log/caddy/access.log \
  --protect-self=false --never-block 203.0.113.10

Esempio avanzato

modifica il firewall — backend ibrido + paese + stato persistente. Per un'anteprima sicura della stessa logica aggiungi --dry-run: il terminale mostra i blocchi previsti e il sink audit riceve eventi would_block.

# hybrid = INPUT + DOCKER-USER; blocks survive restart; full audit
sudo caddy-analyze guard docker://caddy \
  --firewall-backend hybrid \
  --country-block CN,RU,IR \
  --never-block 10.0.0.0/8,192.168.1.50 \
  --never-block-file /etc/caddy-analyzer/whitelist.txt \
  --audit-log /var/log/caddy-analyzer-audit.jsonl \
  --state-file /var/lib/caddy-analyzer/blocked.json \
  --blocklist-refresh 6h \
  --detect-confidence 8
# verify what was blocked:
sudo caddy-analyze unban --list
cat /var/log/caddy-analyzer-audit.jsonl | tail