Threat Engine & Security Inspector

1. Running Threat Detection (--detect)

Enable the security detection engine using the --detect / -d flag:

caddy-analyze --detect /var/log/caddy/access.log

Per-IP Suspicious Request Details

The security report shows the actual suspicious requests per offending IP, including detection type, description, HTTP method, and path:

  - 192.168.1.100     15 malicious requests
        [sql_injection] SQL injection attempt GET /search?id=1' OR '1'='1
        [scanner] Scanner / automated tool detected GET /admin

This information is available in all output formats (table, JSON, CSV, HTML).

2. URL Unescaping & Evasion Prevention

Before evaluating detection rules, caddy-analyze automatically unescapes URL percent-encodings (e.g., converting %2e%2e%2f to ../ and %3Cscript%3E to <script>) to prevent attackers from bypassing security rules using URL encoding tricks. Additionally, a second pass matches against the raw (non-unescaped) URI to catch multibyte-encoded traversal sequences (%c0%ae%c0%ae%c0%af, %252e%252e%252f) and internal host probe attempts that would be lost after unescaping.

Memory Bounding

The detection engine bounds memory usage on huge logs via two mechanisms:

• LRU IP eviction — at most 100,000 distinct client IPs are tracked (configurable via Detector.SetIPCap). When the cap is reached, the least recently used IP is evicted. Actively-used IPs are never dropped, preserving detection accuracy for real attackers.
• Per-IP path cap — at most 1,000 distinct paths per IP are tracked for beaconing/object-enumeration detection, preventing an attacker with many endpoints from exhausting memory.

3. Threat Rule Specification (26 Categories)

Every detection carries a confidence score (1–10) based on pattern specificity, and MITRE ATT&CK technique IDs for SOC mapping. The engine ships 171 signature patterns across the 26 categories below. The patterns listed under each card are representative examples — each card also shows the real number of signatures it contains (e.g. SQL injection matches 19 distinct rule families, from UNION SELECT and comment-bypass to time-based blind and out-of-band exfiltration).

4. Real-time Firewall Guard Daemon (guard)

The guard subcommand monitors log streams and automatically adds offending IPs to Linux iptables DROP rules when attack thresholds are exceeded:

sudo caddy-analyze guard --limit 50 --window 1m docker://my-caddy

Audit Logging

Use --audit-log <path> to record every block and unblock action as a JSON-lines file. Each entry includes timestamp, action, IP, reason, ban duration, and the user who ran the command. The file is created with 0600 permissions. Available on guard, block, and unban subcommands.

sudo caddy-analyze guard --audit-log /var/log/caddy-analyzer/audit.jsonl docker://my-caddy
# Example entry:
{"ts":"2025-01-15T14:29:01Z","action":"block","ip":"203.0.113.5","reason":"12 malicious request(s)","duration":"24h0m0s","user":"root"}
# Other reasons you may see: " auth failures", " not found", " requests",
# " requests from  (distributed scan)", "cred_stuffing", "threat_intel:  score= (...)"

State Persistence

Use --state-file <path> to persist blocked-IP state across guard restarts. When the guard daemon restarts, it reloads previously blocked IPs, cleans up expired bans, and resumes enforcement. Without this flag, all bans are lost on restart. The block and unban commands also accept --state-file to sync manual blocks/unbans with the guard's persisted state.

sudo caddy-analyze guard --state-file /var/lib/caddy-analyzer/blocked.json docker://my-caddy
sudo caddy-analyze block --state-file /var/lib/caddy-analyzer/blocked.json 203.0.113.5
sudo caddy-analyze unban --state-file /var/lib/caddy-analyzer/blocked.json 203.0.113.5

IP Allowlist (Never Block)

Use --never-block to specify IPs/CIDRs that should never be banned, protecting trusted gateways, proxies, or health-check IPs from false-positive blocks. Use --never-block-file to load a larger allowlist from a file (one IP/CIDR per line, # comments supported). The two flags can be combined — entries are merged.

sudo caddy-analyze guard \
  --never-block 10.0.0.0/8,192.168.1.1 \
  --never-block-file /etc/caddy-analyzer/allowlist.txt \
  docker://my-caddy

Pattern-Detection Blocking

Besides rate and status thresholds, guard also blocks IPs whose requests match security patterns (SQLi, XSS, RCE, etc.). Use --detect-confidence <1-10> to set the minimum confidence score required to trigger a block (default 8); detections below the threshold are reported in the audit log but not blocked. Pass 0 to disable pattern-based blocking entirely:

sudo caddy-analyze guard --detect-confidence 8 docker://my-caddy
# Block only very high-signal attacks (UNION SELECT, ${jndi:...})...
sudo caddy-analyze guard --detect-confidence 9 docker://my-caddy
# Disable pattern-based blocking (rate/status thresholds only)...
sudo caddy-analyze guard --detect-confidence 0 docker://my-caddy

Confidence Scoring

Every detection is assigned a confidence score from 1 (low) to 10 (high) based on the specificity and reliability of the matched pattern. High-confidence patterns (e.g. UNION SELECT, ${jndi:ldap://) score 9–10, while broad or ambiguous patterns (e.g. onerror= which can appear in legitimate payloads) score 3–5. This allows downstream consumers to filter noise and prioritize high-signal detections.

5. MITRE ATT&CK Tags

Every detection carries MITRE ATT&CK technique IDs (e.g. T1190 for Exploit Public-Facing Application, T1595 for Active Scanning). This lets SOC analysts build ATT&CK Navigator coverage layers from caddy-analyzer output and map detections to adversary techniques. Tags are included in JSON output and Sigma rules.

6. Sigma Rule Export

Export 23 detection categories as Sigma YAML rules for SIEM import (Splunk, Elastic, Sigma-compatible SIEMs). Rules include MITRE ATT&CK tags, deterministic UUIDs, and dynamically-constructed detection conditions. Validate with sigma check.

caddy-analyze export-sigma                    # stdout
caddy-analyze export-sigma rules.yml          # file
caddy-analyze export-sigma - | sigma check    # pipe to validator

7. IOC Defanging (--defang)

Use --defang to defang IPs and URLs in all output formats for safe sharing of reports containing IOCs. IPs are defanged (192.168.1.1 → 192[.]168[.]1[.]1) and URL schemes are defanged (http:// → hxxp://, https:// → hxxps://). Works across all commands: report, detect, top, tail, diff, and log listing mode.

caddy-analyze --detect --defang access.log
caddy-analyze top ip --defang access.log
caddy-analyze tail --defang access.log