Caddy 集成 Coraza WAF 是近两年替代「Nginx + ModSecurity」最轻的一条路径:Coraza 是 OWASP CRS 规则集的 Go 实现,继承 ModSecurity 的 SecLang 语法,编译进 Caddy 后单二进制即可跑完 TLS 终止、反向代理和应用层攻击检测,不需要 Apache、不需要 lua、不需要规则引擎插件。
本文给出从 xcaddy 编译、Caddyfile 挂载 CRS、误报排除到规则热更新的完整流程,所有配置可直接复制执行。
适用场景
- 新项目单机部署,希望用单二进制完成 HTTPS 与 WAF,不想为 ModSecurity 维护 Nginx 编译链
- 边缘节点、IoT 网关、内网服务前置防护,资源受限(Coraza 常驻内存明显低于 ModSecurity + Apache)
- 已有 Caddy 反向代理,需要在不改架构的前提下补上 SQL 注入、XSS、命令注入、路径遍历检测
- 想把 WAF 规则纳入 Git 管理,跟随 CRS 上游版本灰度升级
前置条件
- Linux(CentOS Stream 9 / Ubuntu 22.04 均可),root 或 sudo
- Go 1.22 及以上(Coraza v3 要求 Go 1.21+,xcaddy 编译建议不低于 1.22)
- 域名已解析到本机,80/443 可达(Caddy 自动申请证书)
git、curl,以及一个后端服务(示例为监听 127.0.0.1:8080 的应用)- 注意:Coraza 是规则型 WAF,不能替代 CC 限频与 DDoS 清洗,这两项由 Caddy 的 rate_limit 模块或前置 CDN 承担
原理说明
Coraza 把 ModSecurity 的 SecRule 表达式引擎用 Go 重写,规则文件仍是 CRS 官方的 *.conf,字段名、变量名、阶段(phase 1~5)语义保持一致。这意味着现成的 CRS 规则、现成的排除语法 SecRuleRemoveById 都能直接复用。
coraza-caddy 以 HTTP handler 的形式插入 Caddy 的处理链。请求进入时先经 WAF handler 检查请求行、请求头、请求体,命中阻断规则直接返回 403;未命中的请求再交给 reverse_proxy。因为 Caddy 的 handler 顺序由 order 决定,自定义指令必须显式声明 order coraza_waf first,否则 WAF 会排在反向代理之后,等于只检查了响应、漏掉全部请求。
- 检测阶段:phase:1 请求头、phase:2 请求体、phase:3 响应头、phase:4 响应体、phase:5 日志
- 规则来源:CRS 主规则集 rules/REQUEST-9xx-*.conf,含协议校验、SQLi、XSS、LFI/RFI、RCE、PHP 注入等
- 动作:
SecRuleEngine On阻断、DetectionOnly仅记录,灰度期必须先用后者
CRS 默认使用异常评分而非逐条阻断:单条规则命中只累加分数(CRITICAL 5 分、ERROR 4 分、WARNING 3 分),累计达到阈值才在阶段结束时阻断。这解释了为什么有些明显异常的请求仍返回 200——它只命中了一条 WARNING 规则。阈值在 crs-setup.conf 里通过 tx.inbound_anomaly_score_threshold 调整,默认 5,收紧到 3 会明显增加误报,放宽到 10 则等于放行低危探测。
与 ModSecurity 相比,Coraza 少了一层容器:ModSecurity 依赖 Apache/Nginx 的请求生命周期钩子,Coraza 直接作为 Caddy 的 handler 在 Go 运行时内完成检测,省掉进程间数据拷贝,代价是没有开箱即用的 WAF 控制台,日志分析要自己接。选型时这点要提前确认:需要可视化规则管理与报表,Coraza 不合适;需要轻量、可版本化、能随镜像一起发布的规则引擎,它很合适。
操作步骤
1. 安装 Go 与 xcaddy
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' > /etc/profile.d/go.sh
source /etc/profile.d/go.sh
go version
export GOPATH=/root/go
export PATH=$PATH:$GOPATH/bin
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
xcaddy version
2. 编译带 Coraza 的 Caddy
版本号与官方 release 对齐即可,关键是 –with github.com/corazawaf/coraza-caddy/v2 这一行不能漏,否则编出来的还是原版 Caddy,Caddyfile 里的 coraza_waf 会直接报「unrecognized directive」:
mkdir -p /root/build && cd /root/build
xcaddy build v2.8.4 --with github.com/corazawaf/coraza-caddy/v2
./caddy list-modules | grep -i coraza
期望输出包含 http.handlers.coraza_waf。确认后覆盖系统二进制并建软链:
install -m 0755 ./caddy /usr/local/bin/caddy
ln -sf /usr/local/bin/caddy /usr/bin/caddy
which caddy && caddy version
3. 部署 OWASP CRS 规则集
git clone --depth 1 https://github.com/coreruleset/coreruleset.git /etc/caddy/crs
cd /etc/caddy/crs
cp crs-setup.conf.example crs-setup.conf
ls rules/ | head -20
grep -n "SecDefaultAction" crs-setup.conf | head -5
crs-setup.conf 决定默认处置动作。SecDefaultAction 建议保持 deny 加 status:403,不要改成 pass 图省事——那等于把所有规则降级成日志。规则目录只 Include 一份 rules/*.conf 就够,后续升级只需 git pull。
4. 编写 Caddyfile
注意 admin localhost:2019:管理接口不能 admin off,否则后面的 caddy reload 会失败;把它绑到回环地址既保留热重载又不对公网暴露。规则内容用反引号包裹的 directives 块传入,按 SecLang 原样解析:
{
order coraza_waf first
admin localhost:2019
email ops@example.com
}
example.com {
encode zstd gzip
coraza_waf {
directives `
SecRuleEngine DetectionOnly
SecRequestBodyAccess On
SecRequestBodyLimit 13107200
SecRequestBodyInMemoryLimit 131072
SecResponseBodyAccess Off
SecAuditEngine RelevantOnly
SecAuditLogRelevantStatus "^(?:5|4(?!04))"
SecAuditLogParts ABIJDEFHZ
SecAuditLogType Serial
SecAuditLog /var/log/caddy/coraza_audit.log
Include /etc/caddy/crs/crs-setup.conf
Include /etc/caddy/crs/rules/*.conf
`
}
request_body {
max_size 20MB
}
reverse_proxy 127.0.0.1:8080 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Proto {scheme}
}
log {
output file /var/log/caddy/access.log
format json
}
}
灰度期用 SecRuleEngine DetectionOnly,跑满 24 小时把审计日志里的规则 ID 排一遍,确认没有正常业务被打中,再改成 On。直接上 On 是新手最常见的翻车方式——后台富文本编辑器几乎一定会触发 XSS 规则。
若 Caddy 前面还有 CDN 或负载均衡,必须补上真实 IP 传递,否则 WAF 记录的 REMOTE_ADDR 全是上一跳地址,审计日志失去溯源价值:
{
servers {
trusted_proxies static 10.0.0.0/8 172.16.0.0/12
client_ip_headers X-Forwarded-For X-Real-IP
}
}
5. systemd 托管与日志目录
useradd -r -s /sbin/nologin caddy 2>/dev/null || true
mkdir -p /var/log/caddy /var/lib/caddy
chown -R caddy:caddy /var/log/caddy /var/lib/caddy
caddy fmt --overwrite /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile
cat > /etc/systemd/system/caddy.service <<'EOF'
[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target
[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
TimeoutStopSec=5s
LimitNOFILE=1048576
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now caddy
systemctl status caddy --no-pager
6. 误报精准排除
排除粒度从细到粗:先按参数排除,再按规则排除,最后才考虑关整个规则文件。把下面几行追加到 directives 块末尾(顺序必须在 Include 之后才生效):
SecRuleRemoveTargetById 942100 "ARGS:content"
SecRuleRemoveTargetById 942100 "ARGS:post_content"
SecRuleUpdateTargetById 942200 "!ARGS:html"
SecRuleRemoveById 942110
SecRuleRemoveTargetById 只让某条规则不看某个参数,风险最小;SecRuleRemoveById 直接删规则,影响面最大。每次排除都要在注释里写清业务原因和日期,否则半年后没人敢动这套规则。
排除项建议成对记录:改了哪条规则的哪个目标、对应哪个业务路径、生效日期、复核人。规则文件纳入 Git 后,每次排除就是一次 commit,回滚与追责都有据可查。
7. 规则热更新与灰度
CRS 升级不需要重编译 Caddy,改完规则文件 reload 即可生效:
cd /etc/caddy/crs
git pull --ff-only
grep -c "^SecRule" rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf
caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfile --force
journalctl -u caddy -n 30 --no-pager
配置验证
# 1) 模块存在
caddy list-modules | grep -i coraza
# 2) 配置语法
caddy validate --config /etc/caddy/Caddyfile
# 3) SQL 注入应被拦(期望 403)
curl -s -o /dev/null -w '%{http_code}\n' \
"https://example.com/?id=1%20union%20select%201,2,3"
# 4) 扫描器 UA 应被拦(期望 403)
curl -s -o /dev/null -w '%{http_code}\n' -A "sqlmap/1.8" https://example.com/
# 5) 路径遍历应被拦(期望 403)
curl -s -o /dev/null -w '%{http_code}\n' \
"https://example.com/download?file=../../etc/passwd"
# 6) 正常页面必须 200
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/
# 7) 审计日志要能看到命中的 rule id
tail -n 5 /var/log/caddy/coraza_audit.log
第 3~5 条在 DetectionOnly 阶段返回 200 但日志有记录是正常的;切到 On 之后必须变成 403 且审计日志出现 id "942100" 一类的命中记录。第 6 条是回归基线,任何 403 都要先看是不是规则误伤。
常见问题
Caddyfile 报 unrecognized directive: coraza_waf
用了发行版仓库里的 caddy 二进制,而不是 xcaddy 编译产物。执行 which caddy 与 caddy list-modules | grep coraza 确认;若模块列表为空,说明 PATH 里优先命中了 /usr/bin/caddy 或 /usr/sbin/caddy,用软链覆盖后重启服务。
后台编辑器保存文章被 403,正文里带 HTML 标签就失败
XSS 规则把富文本参数当成了攻击载荷。先切 DetectionOnly 复现,从审计日志取 rule id(常见 941100/941110/942100),再用 SecRuleRemoveTargetById 只对该参数放行,不要整体关掉 SecRequestBodyAccess——那样请求体不再检测,SQLi 与 RCE 规则同时失效。
文件上传被 413 或直接 403
两处限制要同时放开:Caddy 的 request_body { max_size 20MB },以及 Coraza 的 SecRequestBodyLimit。仅改前者仍会在 WAF 阶段被 SecRequestBodyLimit 拒绝(默认 13MB 左右)。上传接口还建议单独加一条排除:SecRuleRemoveTargetById 920340 "ARGS:file"。
开启后 4xx/5xx 变多、P95 延迟上升
CRS 全量规则在 phase:2 会解码并遍历请求体,大 POST 场景开销明显。三种收敛手段:只 Include 需要的规则文件(去掉 RESPONSE-95x 与 REQUEST-92x 中不用的类别);把 SecResponseBodyAccess 保持 Off;把静态资源路径在 Caddy 里用 @static path /static/* 直接 file_server,不经过 WAF handler。
总结
Coraza 的价值不在「又一个 WAF」,而在把规则引擎从 Apache/Nginx 的模块依赖里解耦出来:一个二进制、一份 CRS、一条 reload 命令,规则可以像代码一样进 Git 灰度。代价是它只管规则匹配,不管限频、不管 CC、不管 DDoS,这些仍需 Caddy 的 rate_limit 模块或前置 CDN 补位。
落地顺序建议:DetectionOnly 观察一周 → 按 rule id 精准排除 → 切 On → 纳入监控(审计日志条数、403 比例、rule 命中 TOP10)。WAF 规则的有效性只能靠日志验证,不靠感觉。