caddy-analyzer

Official Documentation & User Manual — Caddy v2 access log analysis with a 26-category evasion-resistant threat engine and real-time iptables firewall guard.

Get started View on GitHub

Gopher created with gopherize.me · Artwork by Ashley McNamara, inspired by Renee French

caddy-analyze — access.log ● LIVE

click & type — ↑↓ history · Ctrl+L clear · try detect, top, guard

1. Overview

caddy-analyzer is a single-binary log analysis tool and security inspector written in Go. It parses Caddy v2 structured JSON access logs from files, standard input, Docker containers, Kubernetes pods, or systemd journalctl — producing terminal summaries, live streaming views, threat detection reports, and standalone HTML outputs.

attack categories

~70K

lines/sec parse

~7K

lines/sec detect

external deps

2. Documentation sections

01 · INSTALL

Installation Guide Linux, macOS, Windows PowerShell, Go toolchain, Docker, systemd, binary releases.

→ open

02 · INPUTS

Log Sources Guide Files, globs, stdin pipes, docker://, k8s://, journalctl://.

→ open

03 · CLI

Subcommands Reference Complete reference for tail, top, diff, config, guard, block, unban.

→ open

04 · SECURITY

Threat Engine & Firewall Guard 26 categories (SQLi, XSS, Log4j, RCE, JWT, Beaconing…) with MITRE tags, Sigma export, IOC defanging, iptables auto-blocking.

→ open

05 · UI

TUI Dashboard & HTML Reports 6-tab interactive terminal interface (--watch) and standalone dark-mode HTML web reports (-f html).

→ open

3. Why caddy-analyzer?

Dual-pass detection

URL-unescaped + raw URI matching catches multibyte and double-encoded bypass attempts.

Evasion-resistant

Marker triage, case-fold elimination, and literal fast paths keep benign traffic cheap.

Real-time firewall

Guard daemon auto-blocks malicious IPs via iptables with sliding-window limits.

MITRE-tagged

Every detection mapped to ATT&CK technique IDs, exportable as Sigma rules for SIEM.

4. How it works

Request flow: client → Caddy → structured logs → caddy-analyzer → 26-category threat engine → TUI, HTML report, or live iptables firewall action.

5. Demo

6. Quickstart & auto-configuration

To avoid typing your log file or Docker container path every time, caddy-analyze offers persistent default configuration and zero-config auto-discovery.

1. Set persistent default log source recommended

Configure your log source once, and all future commands will read from it automatically:

# Set local default log path (saved to ./caddy-analyzer.json)
caddy-analyze config /var/log/caddy/access.log

# Or set global default log path for all directories
caddy-analyze config docker://my-caddy --global

Once configured, you never need to type the log path again:

caddy-analyze
caddy-analyze --detect
caddy-analyze top ip
caddy-analyze --watch

2. Zero-config auto-discovery

If no configuration file is set and no path argument is passed, caddy-analyze automatically scans for local log files in ./access.log, ./caddy.log, ./caddy-access.log, /var/log/caddy/access.log, or /var/log/caddy/caddy.log.

Quick command reference

# Run terminal analysis on default configured log
caddy-analyze

# Enable threat detection engine
caddy-analyze --detect

# Filter by IP or CIDR subnet (shows color-coded log listing)
caddy-analyze --ip 10.0.0.0/8

# Filter errors excluding bots
caddy-analyze --5xx --no-bots

# Stream colorized logs in real time from Docker
caddy-analyze tail docker://my-caddy

# Tail with filters
caddy-analyze tail --ip 192.168.1.100 --no-bots

# Inspect top client IP addresses
caddy-analyze top ip

# Compare baseline log vs current log
caddy-analyze diff baseline.log current.log

# Check or reset default log source configuration
caddy-analyze config show
caddy-analyze config reset

7. Performance

Benchmarks on synthetic Caddy v2 JSON logs (10% attack traffic, single core):

Benchmark results on synthetic Caddy v2 JSON logs (10% attack traffic, single core)
Log size	`--detect`	Parse only	RAM
1.5K lines (real)	0.6s	<0.1s	21 MB
10K lines	1.5s	0.2s	25 MB
100K lines	14.3s	1.4s	53 MB
1M lines	2m29s	~14s	138 MB

Throughput: ~7,000 lines/sec with --detect, ~70,000 lines/sec parse-only. Memory scales linearly and is bounded by LRU IP eviction (100K cap) and per-IP path caps (1K). The detection engine uses per-source marker triage, case-fold elimination, and a literal fast path to minimize regex evaluations on benign traffic.

8. Progress bar & real-time detection

When analyzing files on a TTY, a determinate progress bar is shown: [████████░░░░] 5000/10000 (50%). Active on caddy-analyze (offline mode), top, and diff (per-file with filename label). Auto-disabled when stderr is redirected to a pipe or file. For non-file sources (stdin, docker://, k8s://, journalctl://) an indeterminate spinner is shown instead. Pre-scan overhead is <3%.

The tail subcommand accepts --detect (-d) to run the detection engine on each streamed entry. Suspicious entries have their IP colored by severity (red critical/high, amber medium, olive low) and the attack type appended after a dim → arrow. Clean entries are unchanged — zero visual noise.

caddy-analyze tail --detect docker://my-caddy
caddy-analyze tail -d --defang /var/log/caddy/access.log