Threat Engine
26 categories, dual-pass evasion resistance, MITRE-tagged. This page is the honest overview — what is detected, what is not, and where to read the details.
What it does NOT do — limits and false positives
Credibility comes from declaring limits. Read this before trusting a report.
| Limit | Why | What to do |
|---|---|---|
| Pattern-based, not semantic | Looks for known payload substrings, does not execute code | Review grouped IPs — do not auto-block on low confidence |
| Confidence filter | Default --detect-confidence 8 in guard; some hits are 5–6 | Raise to 9 for noisier apps; 0 disables only pattern-based blocks, not guard itself |
| Legitimate paths can look malicious | ?url=https://…, ?code={{var}}, __proto__ in docs | Use --never-block / whitelist and check -f html before blocking |
| Behavioral heuristics need state | ua_rotation, object_enumeration, beaconing need ≥10 samples per IP/path | Run on ≥1h of traffic; single-request logs will not fire them |
| Not a WAF | Offline/log-time detection, not inline request blocking | Use guard to block after detection; do not expect pre-request deny |
| GeoIP/blocklist are best-effort | DB-IP lite + 9 feeds, 7d cache, network required for refresh | Pin --geoip-db and check blocklist list age |
guard example that modifies firewall is marked modifies firewall. On a remote host, always --never-block YOUR_IP. When in doubt, use read-only commands (blocklist list, --detect -f html) first.Self-ban protection and false positives
Guard's default --protect-self=true exempts discovered server interface/public egress IPs, including dynamic addresses and covering subnet bans. It does not classify every periodic request as safe or automatically trust other users. Shared-NAT sources arriving with the protected public address share the exemption. Explicit administrator IPs still belong in --never-block/whitelist; Fail2Ban and manual block commands are separate.
Discovery needs direct HTTPS. Failure stops startup or suspends new bans, with an error explaining --protect-self=false. Disable it and use explicit whitelist entries for restricted networks. See guard for refresh, saved-ban cleanup and scope.
What it does
- Dual-pass engine — every URI is checked raw and URL-unescaped (split
?+PathUnescape/QueryUnescape+ manual%fallback) to catch%2e%2eand double-encode bypass. Guard runs the sameDetectorper window. - 26 categories — from
sql_injectiontobeaconing, each tagged with verified MITRE ATT&CK IDs. - Grouped by IP — suspicious report shows top IPs with confidence, URI, and techniques.
- Exportable — 23 pattern categories as Sigma rules; 3 behavioral (
ua_rotation,object_enumeration,beaconing) are stateful and not exported.
Where to go next
Quick check
caddy-analyze --detect testdata/sample.log
# should list 26 categories firing (68 lines, all TEST-NET)
caddy-analyze --detect -f html -o report.html testdata/large.log && open report.html
caddy-analyze tail docker://caddy --detect # live, severity-colored