Nginx WAF 与 ModSecurity 实战：OWASP CRS 规则调优与误报治理

接入层的安全防护可以分成两层：一层是 Nginx 原生的限流、黑名单、请求过滤，成本低但只能拦「明显特征」；另一层是 WAF，它按规则集对请求的 URI、参数、请求体、响应体做深度匹配，能识别 SQL 注入、XSS、路径穿越、命令注入等应用层攻击。ModSecurity 是 Nginx 生态中最成熟的开源 WAF 引擎，配合 OWASP CRS 规则集可以覆盖大部分常见攻击模式。本文按「部署 → 观察 → 调优 → 运营」的顺序，讲清楚 WAF 落地中真正困难的环节——误报治理与性能平衡。

一句话总结： WAF 的价值不在于装上规则集，而在于用观察模式收集真实流量、持续削减误报，直到拦截模式可以安全开启。

1. WAF 在接入层的定位

一句话总结： WAF 是纵深防御中的应用层签名检测，它弥补 Nginx 原生过滤的语义盲区，但无法替代代码层修复与最小权限原则。

Nginx 原生能力擅长处理「协议层异常」：非法方法、超长请求头、畸形 URI、超量连接。但面对 ' OR 1=1--、<script>alert(1)</script>、../../etc/passwd 这类语法完全合法、语义才危险的请求，原生模块无能为力——这些请求的 URI 与请求体在 HTTP 层面毫无异常，只有结合参数语境才能判定为攻击。

WAF 的定位就在这里：它在请求到达业务代码之前，用规则集对参数值做正则与语义匹配，命中攻击特征就拦截或记录。典型的检测维度包括：

- 请求 URI 与查询串中的注入特征
- POST 表单与 JSON 请求体中的脚本标签、SQL 关键字
- Cookie 与自定义头中的畸形编码
- 响应体中泄露的数据库错误信息
- 文件上传的 MIME 与扩展名校验

但要清楚 WAF 的边界。它是基于签名的黑名单机制，对未知攻击、逻辑漏洞、业务级越权几乎无效；攻击者只要做编码变形或分块绕过，就可能逃过规则。因此 WAF 的正确期待是「拦住自动化扫描器与已知攻击模式，降低整体攻击成功率」，而不是「保证不被入侵」。它必须与代码层的参数化查询、输出转义、最小权限一起使用，形成纵深防御。

# 典型的接入层防御分层
# 第 1 层：网络层安全组 / 云防火墙
# 第 2 层：Nginx 限流、Host 白名单、敏感路径拒绝
# 第 3 层：WAF（ModSecurity + CRS）签名检测   <-- 本文主题
# 第 4 层：应用层的参数化查询与鉴权

2. 编译与加载 ModSecurity 模块

一句话总结： Nginx 官方包不含 ModSecurity，需要用 –add-dynamic-module 编译，或用 libmodsecurity3 配合连接器动态加载。

ModSecurity 与 Nginx 的集成有两条路线。第一条是编译进 Nginx：下载 ModSecurity-nginx 连接器，在编译 Nginx 时通过 --add-dynamic-module 加入。第二条是用发行版提供的动态模块：先安装 libmodsecurity3，再装 nginx-module-modsecurity，最后在 nginx.conf 里 load_module。生产环境推荐第二条，便于随包升级。

# Debian/Ubuntu 路线：安装引擎与连接器模块
apt-get install -y libmodsecurity3 nginx-module-modsecurity

# 确认模块文件位置
ls -l /usr/lib/nginx/modules/ngx_http_modsecurity_module.so

# 在 nginx.conf 顶部加载模块（必须在 events 之前）
load_module modules/ngx_http_modsecurity_module.so;

events {
    worker_connections 10240;
}

http {
    # 全局开启引擎，on=拦截，DetectionOnly=只记录
    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec/main.conf;
}

从源码编译的路线适合需要定制引擎版本的场景：

# 源码编译动态模块
git clone --depth 1 https://github.com/SpiderLabs/ModSecurity-nginx.git
./configure --with-compat --add-dynamic-module=../ModSecurity-nginx
make modules
cp objs/ngx_http_modsecurity_module.so /usr/lib/nginx/modules/

注意 --with-compat 参数：它生成与官方二进制兼容的模块 ABI，否则动态模块会因为编译选项不一致而拒绝加载。加载失败时 Nginx 会在启动阶段报 module is not binary compatible，而不是运行时报错，因此每次升级 Nginx 都要重新验证模块能否加载。

main.conf 是规则入口文件，负责按顺序 Include 各个规则文件：

# /etc/nginx/modsec/main.conf
# 先加载引擎自身配置
Include /etc/nginx/modsec/modsecurity.conf

# 再加载 CRS 规则集
Include /etc/nginx/modsec/coreruleset/crs-setup.conf
Include /etc/nginx/modsec/coreruleset/rules/*.conf

2.1 引擎基础配置

一句话总结： modsecurity.conf 决定引擎开关、请求体检查上限与临时文件策略，其中请求体上限直接影响检出率与内存开销。

modsecurity.conf 中的关键参数不多，但每一项都影响检出能力：

# /etc/nginx/modsec/modsecurity.conf
SecRuleEngine On                 # On=拦截, DetectionOnly=只记录, Off=关闭
SecRequestBodyAccess On          # 必须开启，否则 POST 体不检查
SecRequestBodyLimit 13107200     # 请求体检查上限 12.5MB
SecRequestBodyNoFilesLimit 131072 # 不含文件的表单上限
SecRequestBodyInMemoryLimit 131072
SecResponseBodyAccess On         # 响应体检查（泄露检测用，开销较大）
SecResponseBodyMimeType text/plain text/html text/xml application/json
SecTmpDir /var/lib/modsecurity/tmp
SecDataDir /var/lib/modsecurity/data
SecAuditEngine RelevantOnly
SecAuditLog /var/log/nginx/modsec_audit.log

两个高频踩坑点：一是 SecRequestBodyAccess 默认是 Off，不开的话 POST 请求体完全不检查，SQL 注入从表单进来会直接漏过；二是 SecResponseBodyAccess On 会缓冲整个响应体做检查，对静态大文件是灾难，因此必须用 SecResponseBodyMimeType 限定只检查文本类响应。生产环境通常建议先关掉响应体检查，用应用层日志来做泄露检测，避免 WAF 成为吞吐瓶颈。

3. OWASP CRS 规则集部署

一句话总结： CRS 用 paranoia level 与 anomaly scoring 两个旋钮控制严格度，默认 PL1 加阈值 5 是误报与检出率最平衡的起点。

OWASP CRS（Core Rule Set）是一套开源规则集，覆盖 SQL 注入、XSS、RCE、LFI、协议异常、扫描器特征等类别。它不使用「一条规则一票否决」，而是异常评分制（anomaly scoring）：每条规则命中后累加分数，请求结束时总分超过阈值才拦截。这种设计让单条规则的误报不会直接导致拦截。

# 安装 CRS
git clone --depth 1 https://github.com/coreruleset/coreruleset.git \
    /etc/nginx/modsec/coreruleset
cd /etc/nginx/modsec/coreruleset
cp crs-setup.conf.example crs-setup.conf

crs-setup.conf 中的两个核心参数是偏执等级与拦截阈值：

# 偏执等级：1 最宽松（误报最少），4 最严格（误报最多）
SecAction "id:900000,phase:1,nolog,pass,t:none,setvar:tx.paranoia_level=1"

# 入站异常分数阈值：达到 5 分才拦截
SecAction "id:900110,phase:1,nolog,pass,t:none,\
    setvar:tx.inbound_anomaly_score_threshold=5,\
    setvar:tx.outbound_anomaly_score_threshold=4"

# 执行阶段：在请求结束、响应结束两个时点做评分判定
SecAction "id:900120,phase:1,nolog,pass,t:none,\
    setvar:tx.executing_paranoia_level=1"

偏执等级的经验值是：新上线一律从 PL1 开始，观察一到两周，统计误报集中在哪些规则 ID 上，再决定是否升到 PL2。PL2 会启用更多严格的规则（比如对特殊字符、编码变形的额外检测），检出率提升明显但误报也会成倍增长，只有在有专人维护误报的情况下才值得开启。

# 查看当前生效的规则总数
grep -c "^SecRule" /etc/nginx/modsec/coreruleset/rules/*.conf | tail -1

CRS 的规则按文件名分类，REQUEST-9xx 是方法、协议与编码校验，REQUEST-93x 是应用层攻击（注入、XSS），RESPONSE-95x 是响应泄露检测。排错时先看命中规则的 ID，再回到对应文件里查看规则的匹配逻辑，比盲猜高效得多。

4. 规则调优与误报治理

一句话总结： 误报治理的标准流程是「定位规则 ID → 评估业务语境 → 用排除规则精确放行」，而不是整体降级或关闭引擎。

WAF 落地的最大阻力从来不是安装，而是误报。一个包含富文本编辑器、代码分享、JSON API 的业务系统，几乎必然会触发 CRS 的 XSS 与注入规则。常见的误报来源有三类：业务本身就在传输「看起来像攻击」的内容（比如博客正文里有 <script> 示例）、参数名或格式触发规则（比如 select 作为查询参数名）、以及编码差异导致规则误判。

治理的第一步是定位规则 ID。在审计日志里可以看到每次拦截的规则编号：

# 从审计日志提取被拦截的规则 ID 与对应请求
grep -o 'id "[0-9]*"' /var/log/nginx/modsec_audit.log | sort | uniq -c | sort -rn | head -20

拿到高频规则 ID 后，有两种处理方式。精确排除适合「某条规则在本站某个路径下不适用」的场景：

# 在 location 中针对特定路径关闭特定规则
location /api/content/ {
    modsecurity_rules '
        SecRuleRemoveById 942100
        SecRuleRemoveById 941110
    ';
    proxy_pass http://content_backend;
}

排除变量适合「规则本身没问题，但某个参数不该被检查」的场景。比如博客的 content 字段允许 HTML，就应该把该参数从 ARGS 检查中剔除，而不是关闭整条规则：

# 只对指定参数取消检查，保留规则对其他参数的效力
SecRuleUpdateTargetById 942100 "!ARGS:content"
SecRuleUpdateTargetById 941110 "!ARGS:html_body"

4.1 建立误报治理的闭环

一句话总结： 误报治理需要把「收集样本 → 分类定级 → 规则调整 → 回归验证」做成固定流程，并沉淀成可评审的排除清单。

误报治理不是一次性动作。建议的流程是：每天从审计日志导出被拦截的请求样本，按「真攻击 / 误报 / 待定」三分类；对误报记录规则 ID、URL、参数，形成排除清单；排除规则以代码形式提交到配置仓库，经过评审后发布；发布后再用同一批样本回归，确认拦截消失且没有放开真攻击。

# 统计某条规则近 7 天的命中量与命中路径分布
grep 'id "942100"' /var/log/nginx/modsec_audit.log \
    | grep -o 'uri: [^ ]*' | sort | uniq -c | sort -rn | head

排除清单要有「有效期」概念。业务改版后，原本误报的参数可能不再存在，旧排除规则就成了「永久敞开的后门」。建议每季度复审一次排除清单，逐条确认是否仍然必要。排除规则越少，WAF 的实际防护面越大。

另一个技巧是用更精确的规则替代宽泛的规则。CRS 的某些规则在 PL1 就非常宽松（例如对单引号的检测），如果业务确实需要传单引号，可以关闭宽泛规则，然后自己写一条更精确的规则来覆盖真正的攻击特征：

# 用自定义规则替代宽泛规则：只拦截明显的 SQL 注入组合
SecRule ARGS "@rx (?i)(union\s+select|or\s+1\s*=\s*1|sleep\s*\()" \
    "id:1000001,phase:2,deny,status:403,msg:'custom sqli'"

5. DetectionOnly 观察模式与灰度

一句话总结： 任何规则变更都必须先在 DetectionOnly 下跑够一个业务周期，确认误报比例可接受后再切到拦截模式。

DetectionOnly 是 ModSecurity 最实用的一个开关：引擎照常匹配规则、照常记分、照常写日志，但不做任何拦截动作。它让 WAF 可以「影子运行」，在不影响任何真实流量的前提下评估规则质量。

# 阶段一：全局影子模式，观察 1~2 周
modsecurity on;
modsecurity_rules '
    SecRuleEngine DetectionOnly
';

观察期要采集三个指标：命中率（有多少比例请求触发规则）、拦截率（如果开启拦截会有多少请求被 403）、误报率（被触发请求中真正是攻击的比例）。如果「若开启拦截」的比例超过 0.5%，说明规则过于激进或排除不足，此时直接切拦截会造成大量客诉。

灰度的第二步是按路径分批开启拦截。核心交易路径先保持影子模式，低风险路径先开拦截：

# 阶段二：按路径灰度，低风险路径先拦截
location /blog/ {
    modsecurity_rules 'SecRuleEngine On';
    proxy_pass http://blog_backend;
}

location /api/pay/ {
    # 支付路径继续影子模式，直到误报清零
    modsecurity_rules 'SecRuleEngine DetectionOnly';
    proxy_pass http://pay_backend;
}

灰度期要准备快速回退通道。WAF 拦截误伤的后果往往比漏检严重（用户无法下单 vs 潜在风险），因此必须能在分钟级把某个路径切回 DetectionOnly。最稳妥的做法是把 SecRuleEngine 的值做成可通过配置管理下发的变量，并保留一个无需重新编译的 reload 流程：

# 紧急回退：把全局切回影子模式并 reload
sed -i 's/^SecRuleEngine On/SecRuleEngine DetectionOnly/' \
    /etc/nginx/modsec/modsecurity.conf
nginx -t && nginx -s reload

6. 日志、告警与审计

一句话总结： WAF 日志分 debug、audit、error 三类，生产上主要依赖 audit 日志做取证，配合 error 日志做告警，两者都要做轮转与脱敏。

ModSecurity 会产生三类日志。debug 日志（SecDebugLog）记录每条规则的匹配过程，用于排查「为什么没拦住」或「为什么拦了」，但开销极大，只能临时开启；audit 日志（SecAuditLog）记录完整请求上下文，是取证与调优的主要数据源；error 日志由 Nginx 承接 ModSecurity 的拦截事件，格式统一便于聚合告警。

# 审计日志按「相关性」记录：只记录被拦截或高分请求
SecAuditEngine RelevantOnly
SecAuditLogRelevantStatus "^(?:5|4(?!04))"
SecAuditLogParts ABIJDEFHZ
SecAuditLogType Serial
SecAuditLog /var/log/nginx/modsec_audit.log

SecAuditLogParts 控制审计日志包含哪些片段：A 审计元数据、B 请求头、C 请求体、E 中间响应、H 审计尾部、Z 最终边界。请求体（C）包含用户提交的原始数据，可能含密码与个人信息，必须做脱敏或限制保留时长。合规要求高的场景建议去掉 C 片段，或者把审计日志写入有访问控制的独立存储。

# 从审计日志提取攻击事件并推送告警
tail -F /var/log/nginx/modsec_audit.log \
  | grep -E 'ModSecurity: (Warning|Access denied)' \
  | while read -r line; do
      echo "[WAF] $line" | mail -s "WAF Alert" secops@example.com
    done

告警要避免「狼来了」。被拦截的请求里绝大多数是自动化扫描器，真正需要人介入的是高频、集中、针对特定接口的攻击。建议按来源 IP 聚合，只对「同一 IP 短时间多次触发」或「特定高危规则（RCE、LFI）触发」告警，其余进入日志归档。同时把 WAF 拦截事件与 Nginx 访问日志关联，便于复盘完整的攻击链路。

审计日志的轮转不能靠 logrotate 直接切割，因为 ModSecurity 持有文件句柄。正确做法是配合 Nginx reload 或使用 SecAuditLogStorageDir 的并发目录模式：

# logrotate 配置：切割后触发 reload 让 ModSecurity 重开文件
/var/log/nginx/modsec_audit.log {
    daily
    rotate 30
    compress
    postrotate
        /usr/sbin/nginx -s reload
    endscript
}

7. 性能开销控制

一句话总结： WAF 的开销主要来自正则匹配与请求体缓冲，通过减少规则数、限制检查范围、关闭响应体检查可以把开销压到 5% 以内。

ModSecurity 对性能的影响取决于三个因素：规则数量、请求体大小、以及是否检查响应体。CRS 全量规则约 600 余条，每条都要对 URI、参数、请求体做正则匹配，一条 10KB 的 POST 请求可能触发上千次匹配。实测中，PL1 全量 CRS 对纯转发型 Nginx 的吞吐影响大约在 10%~30% 之间，如果叠加响应体检查则可能翻倍。

降低开销的第一招是缩小检查范围。对静态资源、健康检查、监控探针这类路径完全不需要 WAF：

# 静态资源与探针路径关闭 WAF
location /static/ {
    modsecurity off;
    root /srv/web/static;
}

location = /healthz {
    modsecurity off;
    return 200 "ok\n";
}

location = /metrics {
    modsecurity off;
    allow 10.0.0.0/8;
    deny all;
}

第二招是精简规则集。CRS 中有一部分规则针对的协议特性在特定架构下不会出现（例如不支持文件上传的纯 JSON API 就不需要文件上传规则），可以通过 SecRuleRemoveById 批量关闭。但要注意：删规则是在牺牲检出率换性能，必须基于真实的攻击面评估，不能为了压测数字好看而随意删减。

# 关闭不适用的大类规则（示例：无文件上传能力的纯 API）
SecRuleRemoveById 913100 913110 913120   # 扫描器特征
SecRuleRemoveById 920270 920271 920272   # 部分协议校验

第三招是调整请求体检查上限。SecRequestBodyLimit 决定超过多大就跳过检查。设得过大，攻击者可以用超大请求体拖慢 WAF；设得过小，大表单会漏检。合理做法是设为业务最大表单的 1.2 倍，并在超限时记录日志：

# 超过上限时记录而非直接放行（便于发现异常大请求）
SecRequestBodyLimit 5242880
SecRequestBodyLimitAction Reject

最后是容量规划。开启 WAF 后 worker 的 CPU 占用会上升，建议用 wrk 或 ab 做带 WAF 与不带 WAF 的对比压测，测出真实的 P99 变化。如果 P99 恶化明显，优先检查是不是响应体检查在作祟，其次看是否有超大请求体导致大量正则回溯（正则回溯是 WAF 卡顿的常见原因，可以通过 SecDebugLog 定位慢规则）。

8. 总结

WAF 是一项需要长期运营的能力，装上规则集只是起点，真正的价值来自持续观察、持续调优的过程。判断一个 WAF 是否「好用」，不看它拦了多少请求，而看它误报多少、漏报多少、以及团队能否在一周内把一条新误报处理干净。WAF 挡住的是应用层攻击，而访问速度的优化同样在接入层完成，接下来看看如何用边缘缓存把内容分发到离用户最近的地方。

延伸阅读

• Nginx 安全加固清单
• Nginx 限流与安全防护
• Nginx Lua 扩展与 OpenResty 实践
• Nginx 日志分析与性能调优
• Nginx API 网关模式