Tutti i comandi
Questa pagina spiega cosa fa ogni comando, cosa legge o modifica e quale modalità scegliere. Usa caddy-analyze <comando> --help per vedere i flag esatti del binario installato. La sezione completa dei flag distingue opzioni persistenti, modalità solo root e opzioni proprie dei comandi.
Scegli il comando
| Obiettivo | Comando | Effetto |
|---|---|---|
| Riassumere uno o più log | caddy-analyze SOURCE... | Report in sola lettura |
| Cercare richieste sospette | caddy-analyze --detect SOURCE... | Report delle minacce |
| Seguire le nuove voci | tail o --follow | Flusso/report in sola lettura |
| Vedere le classifiche | top | Aggregazione in sola lettura |
| Confrontare due periodi | diff | Confronto in sola lettura |
| Salvare un periodo di riferimento | baseline save | Scrive JSON |
| Bloccare automaticamente gli attaccanti | guard | Può modificare il firewall |
| Bloccare o sbloccare manualmente | block / unban | Modifica il firewall |
| Gestire i feed di threat intelligence | blocklist | Scrive cache/config, non il firewall |
| Gestire le impostazioni predefinite | config | Scrive la configurazione |
| Proteggere gli IP fidati | whitelist | Scrive l'allowlist |
| Esportare le regole di detection | export-sigma | Scrive YAML o stdout |
| Installare una release | update | Sostituisce il binario |
Analisi: comando principale
caddy-analyze [flags] [source...]
caddy-analyze --detect --format json access.log
caddy-analyze --from 1h --5xx /var/log/caddy/*.logSenza sottocomando, il tool analizza log JSON di accesso Caddy ed eventi operativi, applica i filtri, calcola le metriche e stampa un report tabellare. Le sorgenti possono essere file o glob locali, - per stdin, docker://container, k8s://pod o journalctl://unit. Se non specifichi una sorgente viene usata quella predefinita configurata.
--detect attiva il motore di sicurezza a doppio passaggio e aggiunge al report IP sospetti, categorie, confidence ed evidenze. Non blocca nulla. Usa --format json per l'automazione, --format csv per i fogli di calcolo e --format html -o report.html per condividere il risultato. I filtri vengono combinati; per esempio --ip, --path, --slow e --5xx devono essere tutti soddisfatti.
# Analizzare stdin con output per macchine
cat access.log | caddy-analyze --detect --format json -
# Solo errori server lenti nelle ultime due ore
caddy-analyze --from 2h --5xx --slow 500ms access.log
# Inviare i documenti a Loki
caddy-analyze --format loki --remote-url https://logs.example/api/prom/push access.logtail
caddy-analyze tail [source...] [--detect]Trasmette le voci appena arrivano e colora stato, metodo, percorso, latenza e IP client. È la scelta interattiva per diagnosticare un servizio attivo. --detect evidenzia inline le richieste sospette e non modifica il firewall. I filtri si applicano anche qui.
caddy-analyze tail docker://caddy --detect --5xx
caddy-analyze tail --grep '/admin|wp-login' /var/log/caddy/access.logtop
caddy-analyze top [dimension] [source...] [flags]Calcola solo una classifica invece del report completo. Le dimensioni sono path, ip, ua, status, method, host, bandwidth, country, city e asn. La dimensione può essere posizionale o passata con --by; il default è path. Usa -t 0 per disabilitare la lista.
caddy-analyze top ip access.log -t 20
caddy-analyze top bandwidth access.log --from 24h
caddy-analyze top --by status --5xx access.log
caddy-analyze top country --geoip-db GeoLite2-Country.mmdb access.logdiff
caddy-analyze diff <baseline_log> <target_log> [flags]Confronta due file di log locali e mostra le variazioni di richieste al secondo, errori e latenza. Il primo file è il periodo di riferimento, il secondo quello da esaminare. Non crea un baseline salvato; usa --format json o --output per CI e controlli pianificati.
caddy-analyze diff ieri.log oggi.log
caddy-analyze diff prima.log dopo.log --format json -o regressione.jsonbaseline save
caddy-analyze baseline save <source...> -o baseline.json [--detect]Analizza una sorgente e salva uno snapshot JSON versionato delle metriche aggregate. È utile per conservare il riferimento di un deployment funzionante. --detect include le statistiche di detection. Salvare un baseline non blocca gli IP.
caddy-analyze baseline save access.log --from 7d -o baseline.json --detect
caddy-analyze --against baseline.json access.log --threshold 15guard
sudo caddy-analyze guard [source] [flags]Monitora continuamente una sorgente e blocca automaticamente gli IP che superano le soglie di richieste, autenticazione, 404 o detection. In base a --firewall-backend può modificare iptables, nftables, la catena Docker DOCKER-USER o una combinazione. I blocchi possono essere persistiti e ogni azione può essere registrata.
--never-block o --never-block-file prima di eseguire il comando su un host remoto. Prova prima --dry-run. La modalità normale richiede root; la simulazione non modifica firewall o stato.sudo caddy-analyze guard /var/log/caddy/access.log --dry-run
sudo caddy-analyze guard docker://caddy --never-block 203.0.113.10 \
--firewall-backend hybrid --state-file /var/lib/caddy-analyzer/blocked.json--country-block blocca subito i paesi indicati quando GeoIP è disponibile. I feed blocklist sono attivi di default e si disabilitano con --no-blocklist. Per tutte le soglie e i sink consulta la pagina dedicata guard.
block e unban
sudo caddy-analyze block <ip> [ip...]
sudo caddy-analyze unban <ip> [ip...] | --all | --listblock aggiunge uno o più indirizzi al firewall e, salvo disabilitazione, aggiorna il file di stato di guard. unban rimuove gli indirizzi scelti; --list mostra soltanto lo stato corrente e --all rimuove tutti i blocchi tracciati.
sudo caddy-analyze block 198.51.100.7
sudo caddy-analyze unban --list
sudo caddy-analyze unban 198.51.100.7blocklist
caddy-analyze blocklist refresh|list|config|init [flags]Scarica e analizza i feed di threat intelligence usati da guard. refresh aggiorna la cache, list mostra feed e conteggi, config stampa la configurazione effettiva e init salva le impostazioni. Queste operazioni non installano regole firewall.
caddy-analyze blocklist refresh
caddy-analyze blocklist list -f json
caddy-analyze blocklist --blocklist-config custom.json \
--no-default-blocklists initconfig
caddy-analyze config [show|set|reset|source] [--global]Imposta la sorgente predefinita usata quando il comando principale non riceve una sorgente posizionale. Senza --global salva in ./caddy-analyzer.json; con il flag salva in ~/.config/caddy-analyzer/config.json. show mostra la scelta attiva e reset rimuove il file selezionato.
caddy-analyze config /var/log/caddy/access.log
caddy-analyze config docker://caddy --global
caddy-analyze config show
caddy-analyze config resetwhitelist
sudo caddy-analyze whitelist [--add IP/CIDR] [--remove IP/CIDR]
caddy-analyze whitelist --list [--file PATH]Gestisce il file degli IP e CIDR che guard non deve mai bloccare. Il default è /etc/caddy-analyzer/whitelist.txt. --init lo crea con intestazione, --add e --remove accettano valori separati da virgole e --list stampa le voci. Passa lo stesso file a guard con --never-block-file.
export-sigma
caddy-analyze export-sigma [output-file]Esporta le categorie integrate di detection in YAML Sigma multi-documento. Senza file scrive su stdout, con un file salva l'intero set di regole. Le regole sono indipendenti dal vendor e includono i tag MITRE ATT&CK.
caddy-analyze export-sigma rules.yml
caddy-analyze export-sigma - | sigma checkupdate
caddy-analyze update [--check|--version TAG|--force]Controlla e installa una release verificata da GitHub. L'installazione è fail-closed: cosign deve validare il manifest firmato e l'hash dell'archivio deve corrispondere. --check non installa, --version fissa un tag, --force consente reinstallazione o downgrade e --install-dir sceglie la directory. Se la verifica fallisce il binario corrente resta intatto.
caddy-analyze update --check
sudo caddy-analyze update
caddy-analyze update --version v0.7.0 --install-dir ~/.local/bincompletion e versione
caddy-analyze --version
caddy-analyze completion bash > ~/.local/share/bash-completion/completions/caddy-analyze
caddy-analyze completion zsh
caddy-analyze completion fish--version stampa la versione installata. Il comando nascosto completion genera completamenti per bash, zsh o fish e richiede esattamente uno di questi nomi.
Combinazioni utili
# Indagare uno scan senza intraprendere azioni
caddy-analyze --detect --grep 'wp-login|\.env|/admin' access.log
# Creare un baseline confrontabile e cercare regressioni
caddy-analyze baseline save baseline.log -o baseline.json
caddy-analyze --against baseline.json current.log --threshold 20
# Simulare guard e poi attivare il blocco
sudo caddy-analyze guard access.log --dry-run --never-block-file whitelist.txt
sudo caddy-analyze guard access.log --never-block-file whitelist.txtFlag globali: riferimento completo
La maggior parte dei flag è persistente e viene ereditata dai sottocomandi. Le modalità solo root sono --follow, --interval, --watch, --detect root e --version; tail ha il proprio --detect locale. Un valore omesso lascia attivo il default. Le durate usano la sintassi Go, ad esempio 500ms, 5m o 1h.
| Flag | Default | Funzione |
|---|---|---|
--from | nessuno | Mantiene le voci successive a un istante RFC3339 o a un intervallo relativo come 5m, 1h, 2d. |
--to | nessuno | Mantiene le voci precedenti all'istante RFC3339 indicato. |
--status, -s | tutti | Seleziona uno o più codici HTTP, per esempio -s 200,404; si può ripetere. |
--2xx, --3xx, --4xx, --5xx | false | Scorciatoie per includere una classe di stato. |
--errors-only, -e | false | Limita ai soli errori server 5xx. |
--method, -m | nessuno | Filtra per metodo HTTP, senza distinzione tra maiuscole e minuscole. |
--path, -p | nessuno | Filtra il percorso con un glob, ad esempio /api/*. |
--host | nessuno | Filtra per sottostringa dell'host della richiesta. |
--ip / --exclude-ip | nessuno | Includono o escludono un IP o una rete CIDR. |
--country / --exclude-country | nessuno | Includono o escludono paesi con codice ISO o nome; richiedono GeoIP. |
--asn / --exclude-asn | nessuno | Includono o escludono numeri ASN; richiedono GeoIP. |
--slow | nessuno | Seleziona richieste più lente della durata indicata. |
--max-latency | nessuno | Seleziona richieste non più lente della durata indicata. |
--min-size / --max-size | nessuno | Limitano la dimensione della risposta; accettano byte e suffissi kb, mb, gb. |
--grep | nessuno | Cerca un pattern su URI, User-Agent e IP; usa regex valide e ripiega sulla sottostringa se il pattern non è regex. |
--no-bots / --bots-only | false | Escludono o includono soltanto bot e crawler classificati. |
--level | tutti | Filtra gli eventi operativi per error, warn, info o debug; ripetibile. |
--ops-only | false | Mostra solo eventi operativi non HTTP. |
--top, -t | 10 | Numero di elementi nelle classifiche; 0 disabilita le classifiche. |
--format, -f | table | Output table, json, csv, html, elasticsearch, opensearch o loki secondo il comando. |
--output, -o | stdout | Scrive l'output in un file invece che su stdout. |
--compact, -c | false | Riduce il layout dei report tabellari. |
--defang | false | Trasforma i punti degli IP in [.] per condividere gli indicatori senza renderli cliccabili. |
--workers | CPU disponibili | Numero di parser paralleli; 0 seleziona automaticamente. La riduzione dei risultati resta ordinata. |
--max-cardinality | 100000 | Limita le chiavi distinte per contatore per contenere la memoria; 0 significa illimitato. |
--trust-forwarded | false | Usa l'ultimo hop pubblico di X-Forwarded-For/X-Real-IP; attivalo solo dietro proxy fidati. |
--geoip-db | auto | Indica il file mmdb DB-IP o MaxMind. Se vuoto tenta l'auto-discovery. |
--no-auto-download | false | Impedisce il download automatico del database DB-IP al primo uso GeoIP. |
--geo-cache-ttl | 24h | Durata degli elementi nella cache GeoIP; 0 disabilita la cache. |
--geo-cache-size | 50000 | Numero massimo di lookup GeoIP in cache; 0 disabilita la cache. |
--ua-rotation | 10 | Numero di User-Agent distinti dallo stesso IP prima dell'euristica di rotazione/scanner. |
--custom-patterns | nessuno | Carica uno o più file JSON di regole custom validati dal motore. |
--against | nessuno | Confronta l'analisi corrente con un baseline JSON e restituisce errore se supera la soglia. |
--threshold | 20% | Soglia percentuale usata dal confronto con baseline. |
--namespace, -n | nessuno | Namespace Kubernetes per sorgenti k8s://. |
--follow, -F | false | Segue i nuovi log e produce report periodici; modalità root. |
--interval, -i | nessuno | Imposta la durata delle finestre aggregate in modalità follow. |
--watch, -w | false | Apre la dashboard TUI live; richiede un terminale. |
--detect, -d | false | Attiva la detection delle minacce nel report root. |
--remote-url | nessuno | Endpoint HTTP per output Elasticsearch/OpenSearch bulk o Loki; obbligatorio per quei formati. |
--remote-index | caddy-analyzer | Indice Elasticsearch/OpenSearch. |
--remote-user, --remote-password | nessuno | Credenziali Basic HTTP per l'endpoint remoto. |
--remote-token | nessuno | Bearer token HTTP; non usare insieme alle credenziali Basic salvo necessità dell'endpoint. |
--remote-batch-size | 100 | Documenti per richiesta remota. |
--remote-retries | 3 | Nuovi tentativi dopo il primo invio. |
--remote-backoff | 250ms | Attesa iniziale tra tentativi remoti. |
--remote-timeout | 10s | Timeout di ogni richiesta remota. |
Flag propri dei sottocomandi
tail
tail --detect abilita l'evidenziazione inline delle richieste sospette. Tutti i filtri globali restano disponibili, ma tail non produce un report aggregato e non blocca IP.
top
top --by DIMENSION è l'alternativa al parametro posizionale. Le dimensioni valide sono path, ip, ua, status, method, host, bandwidth, country, city e asn. country, city e asn richiedono un database GeoIP compatibile.
baseline save
baseline save --detect include le statistiche di sicurezza nel JSON. --output è necessario per conservare il file e il baseline deve essere generato con gli stessi filtri che userai nel confronto.
blocklist
| Flag | Uso |
|---|---|
--cache-dir | Directory in cui salvare i file dei feed scaricati. |
--no-default-blocklists | Disabilita gli otto feed predefiniti; utile con una configurazione solo custom. |
--blocklist-config FILE | Aggiunge file JSON con sorgenti name, url e, se necessario, format; ripetibile. |
--blocklist-remove NAME | Rimuove sorgenti nominate dalla configurazione; accetta valori separati da virgole. |
--format table|json | Formato di list e config. |
Le azioni sono: refresh scarica e aggiorna la cache; list mostra stato, età, errori e conteggi; config stampa la configurazione; init salva le impostazioni correnti per i comandi successivi. Nessuna azione modifica il firewall.
guard
| Flag | Default | Uso |
|---|---|---|
--limit, -l | 100 | Richieste HTTP per IP nella finestra prima del blocco; 0 disabilita. |
--window, -w | 1m | Finestra scorrevole, calcolata con bucket per secondo. |
--duration, -d | 10m | Durata del blocco; 0 significa permanente. |
--auth-limit | 10 | Numero di risposte 401/403 prima del blocco; 0 disabilita. |
--notfound-limit | 50 | Numero di 404 prima del blocco; 0 disabilita. |
--detect-confidence | 8 | Confidence minima 1-10 per il blocco da pattern; 0 disabilita solo questo percorso. |
--firewall-backend | auto | Backend auto, iptables, docker, nftables o hybrid. |
--dry-run | false | Valuta e registra i blocchi possibili senza modificare firewall o state file. |
--country-block | nessuno | Blocca immediatamente i paesi ISO indicati tramite GeoIP. |
--no-blocklist | false | Disabilita il controllo degli otto feed. |
--blocklist-refresh | 6h | Intervallo di refresh dei feed; minimo 1h, 0 disabilita. |
--cache-dir | cache utente | Directory dei feed cache. |
--never-block | nessuno | IP/CIDR da proteggere sempre; ripetibile. |
--never-block-file | nessuno | File con un IP/CIDR per riga e commenti #. |
--state-file | /var/lib/caddy-analyzer/blocked.json | Persistenza e recupero dei blocchi dopo un riavvio; vuoto disabilita. |
--iptables-timeout | 10s | Timeout di ogni invocazione firewall. |
--subnet-limit | 0 | Blocca una rete /24 o /64 quando le richieste distribuite superano la soglia. |
--rps-anomaly | 0 | Segnala un picco RPS rispetto alla baseline EWMA; è un alert audit, non un blocco. |
--cred-stuffing-limit | 0 | Segnala IP distinti che falliscono lo stesso percorso; è un alert audit. |
--audit-log | JSONL in /var/log | File locale degli eventi; vuoto disabilita. |
--audit-syslog | disabilitato | Destinazione UDP syslog, ad esempio 127.0.0.1:514. |
--webhook-url / --audit-webhook | disabilitato | Invia notifiche a webhook generico, Slack, Discord o PagerDuty. |
--webhook-provider | generic | Provider del webhook. |
--pagerduty-routing-key | nessuno | Routing key richiesta dal provider PagerDuty; non viene scritta nei log. |
--audit-timeout / --audit-retries | 5s / 2 | Timeout per sink e retry dopo il primo invio; massimo 5 retry. |
--audit-rate-limit | 0 | Intervallo minimo tra notifiche dello stesso IP; 0 disabilita. |
block e unban
Entrambi condividono i flag di audit: --audit-log, --audit-syslog, --webhook-url/--audit-webhook, --webhook-provider, --pagerduty-routing-key, --audit-timeout, --audit-retries e --audit-rate-limit. --state-file sincronizza i blocchi manuali con guard. In aggiunta, unban --list elenca gli IP attivi e unban --all li rimuove tutti; non usare entrambi insieme.
config
--global, -g seleziona il file globale invece di quello locale. Le forme brevi sono config SOURCE o config set SOURCE; config show mostra la configurazione attiva, config reset rimuove il file e config source gestisce la sorgente predefinita.
whitelist
--file sceglie il file, --init lo crea con intestazione, --add inserisce IP/CIDR, --remove li elimina e --list, -l stampa il contenuto. Il file deve poi essere passato a guard con --never-block-file.
update
--check controlla soltanto, --version TAG installa una release precisa, --force consente reinstallazione o downgrade e --install-dir DIR sostituisce il binario in una directory scelta. La verifica cosign e SHA256 è obbligatoria e un errore lascia intatta l'installazione.
export-sigma
Accetta al massimo un file di output. Il valore - o l'assenza del parametro scrive su stdout; un percorso scrive YAML Sigma multi-documento. I flag globali di analisi non cambiano l'insieme delle regole esportate.
help e --help
caddy-analyze help COMANDO mostra l'help di un comando senza eseguirlo; --help è disponibile su ogni comando e sottocomando. L'help generato dal binario è la fonte definitiva per verificare flag e default della versione in uso.