Utilizzo

Da “mostra tutto” a “mostra solo ciò che conta”. Tutti gli esempi sono da copiare e incollare con testdata/sample.log: sostituiscilo con la tua sorgente (consulta Sorgenti log).

Nessun filtro — report aggregato

caddy-analyze testdata/sample.log

Mostra periodo, RPS, barre 2xx/3xx/4xx/5xx, byte, P50/P95/P99, umano/bot, percorsi/IP/UA/metodi/host principali, paesi/ASN (con GeoIP) e conteggi operativi.

Filtri per voce → modalità elenco

Quando è attivo un filtro a livello di voce e il formato è table senza -o, lo strumento passa a un elenco colorato (non aggregato). Forza il report con -f json/csv/html o -o.

caddy-analyze --5xx testdata/sample.log
caddy-analyze --country IT -t 25 testdata/sample.log
caddy-analyze --grep "wp-" --no-bots testdata/sample.log

Formati di output

caddy-analyze -f table testdata/sample.log              # default
caddy-analyze -f json -o report.json --detect testdata/sample.log
caddy-analyze -f csv -o report.csv testdata/sample.log
caddy-analyze -f html -o report.html --detect testdata/sample.log && open report.html
caddy-analyze --defang -f json testdata/sample.log      # 203.0.113.1 → 203[.]0[.]113[.]1

--defang riscrive IP/URL per una condivisione sicura (anche hxxp).

Exporter remoti

I formati remoti inviano un report aggregato per ogni report generato. Elasticsearch e OpenSearch usano la Bulk API; Loki riceve lo stesso report come una singola log line. In --follow e --interval ogni finestra viene inviata sincronicamente.

caddy-analyze -f elasticsearch --remote-url http://localhost:9200 --remote-index caddy-analysis testdata/sample.log
caddy-analyze -f opensearch --remote-url https://search.example/_bulk --remote-token "$TOKEN" testdata/sample.log
caddy-analyze -f loki --remote-url http://localhost:3100 testdata/sample.log

Usa --remote-user/--remote-password per Basic o --remote-token per Bearer. Retry e timeout sono configurabili con --remote-retries, --remote-backoff e --remote-timeout.

Pattern personalizzati

Carica uno o più file JSON validati senza ricompilare il binario:

caddy-analyze --detect --custom-patterns rules.json --custom-patterns local.json testdata/sample.log

[{"type":"internal_admin","pattern":"/internal/admin","description":"Internal admin probe","confidence":8,"source":"uri","mitre":"T1595.002"}]

source può essere uri, header, user_agent o all. JSON, regex, tipo o confidence non validi bloccano l'elaborazione prima della lettura dei log.

Top — ispettore classificato

caddy-analyze top ip testdata/sample.log
caddy-analyze top path -t 20 --5xx testdata/sample.log
caddy-analyze top country --country IT testdata/sample.log
caddy-analyze top asn testdata/sample.log
caddy-analyze top -b bandwidth -f csv -o top.csv testdata/sample.log

Dimensioni: path, ip, ua, status, method, host, bandwidth, country, city, asn. Paese/asn richiedono GeoIP; City scarica automaticamente il database GeoLite2 City, salvo usare --no-auto-download (consulta Configurazione → ottimizzazione).

Diff — confronta due log

caddy-analyze diff testdata/sample.log testdata/large.log
caddy-analyze diff old.log new.log -f json -o diff.json

Mostra delta RPS, picco di 5xx, regressione della latenza, nuovi percorsi di errore (primi 10).

Baseline e controlli di regressione

caddy-analyze baseline save --output baseline.json testdata/sample.log
caddy-analyze --against baseline.json --threshold 20 testdata/sample.log

La baseline è uno snapshot JSON versionato. Il confronto stampa le differenze e restituisce un exit code non-zero quando errori, latenza, errori operativi o nuovi percorsi superano la soglia. È quindi adatto ai gate CI/CD. La soglia predefinita è 20 percento.

Deployment container

Il demo locale hardened è in docker-compose.yml. Il chart Helm è in deploy/helm/caddy-analyzer: esegue il processo come non-root con filesystem in sola lettura e non monta il socket Docker di default. Abilitalo solo dopo aver valutato le implicazioni di sicurezza.

docker compose up --build
helm lint deploy/helm/caddy-analyzer
helm template caddy-analyzer deploy/helm/caddy-analyzer

Live — follow / interval / watch

caddy-analyze --follow /var/log/caddy/access.log        # stream
caddy-analyze --interval 10s /var/log/caddy/access.log  # report every 10s
caddy-analyze --watch /var/log/caddy/access.log         # 8-tab TUI (see TUI & Reports)
caddy-analyze tail docker://caddy --detect              # tail with inline detect

Rilevamento

caddy-analyze --detect testdata/sample.log -f table
caddy-analyze --detect -f html -o sec.html testdata/sample.log

26 categorie, doppio passaggio (raw + senza escape), tag MITRE. Consulta Categorie e Dettagli sul rilevamento.

↑