1. 项目概述为什么需要NginxModSecurity WAF在今天的网络环境中Web应用防火墙WAF早已不是大型企业的专属它已经成为任何对外提供服务的网站或应用必须考虑的基础安全组件。你可能已经熟练使用Nginx来处理反向代理、负载均衡和静态资源服务但面对层出不穷的SQL注入、跨站脚本XSS、路径遍历等攻击仅靠Nginx自身的ngx_http_limit_req_module限流或简单的location过滤是远远不够的。这时一个成熟的WAF方案就显得至关重要。ModSecurity是一个开源的、跨平台的Web应用防火墙引擎它最初是Apache的一个模块后来发展出了支持Nginx的版本——ModSecurity 3.0。与商业WAF相比它的优势在于完全免费、规则高度可定制并且拥有一个活跃的社区OWASP ModSecurity核心规则集。将ModSecurity 3.0与Nginx集成相当于为你的Nginx服务器装上了一套“智能免疫系统”能够实时解析HTTP/HTTPS流量根据预定义的安全规则对请求和响应进行深度检测与拦截。我选择这个组合是因为它在资源开销、防护能力和可控性之间取得了很好的平衡。对于中小型项目或个人开发者自建WAF不仅能有效提升应用安全水位更是深入了解HTTP协议和安全攻防的绝佳实践。接下来我将带你从零开始完成Nginx与ModSecurity 3.0.x的整合、编译、配置到核心规则调优的全过程分享其中每一步的实操细节和我踩过的坑。2. 环境准备与依赖安装在开始编译安装之前一个干净、稳定的基础环境是成功的首要条件。我强烈建议在一台全新的测试服务器或虚拟机上进行首次尝试避免与现有环境冲突。2.1 系统环境与工具链确认本次实战以主流的CentOS 7.x或Rocky Linux 8/9为例其他基于RPM或APT的发行版步骤类似但包名可能不同。首先更新系统并安装必要的开发工具和依赖库。# 对于CentOS 7 / Rocky Linux 8 sudo yum groupinstall -y Development Tools sudo yum install -y epel-release sudo yum install -y wget git pcre-devel openssl-devel libxml2-devel geoip-devel yajl-devel curl-devel lmdb-devel ssdeep-devel libmaxminddb-devel gcc-c flex bison # 对于Ubuntu 20.04/22.04 sudo apt update sudo apt install -y build-essential git libpcre3-dev libssl-dev zlib1g-dev libxml2-dev libgeoip-dev libyajl-dev libcurl4-openssl-dev liblmdb-dev libfuzzy-dev libmaxminddb-dev autoconf automake libtool这里安装的依赖包每一个都有其作用pcre-develPerl兼容正则表达式库Nginx和ModSecurity规则匹配的核心。openssl-devel提供HTTPS支持。libxml2-devel用于解析XML格式的请求体如SOAP API。yajl-develJSON解析库现代API防护必备。libmaxminddb-devel用于集成GeoIP地理位置数据库实现基于地区的访问控制。ssdeep-devel/libfuzzy-dev模糊哈希库用于恶意文件检测。注意libmaxminddb-devel和ssdeep-devel不是强制依赖但如果你计划使用GeoIP功能或文件上传检查强烈建议安装。否则后续编译ModSecurity时可能需要禁用相关功能。2.2 获取Nginx与ModSecurity源码我们不使用系统包管理器安装Nginx因为需要动态加载ModSecurity模块。去Nginx官网下载最新的稳定版如1.24.x和ModSecurity 3.0.x的源码。# 创建一个工作目录 mkdir ~/nginx-waf cd ~/nginx-waf # 下载Nginx源码 wget http://nginx.org/download/nginx-1.24.0.tar.gz tar -xzvf nginx-1.24.0.tar.gz # 下载ModSecurity 3源码 git clone --depth 1 -b v3/master https://github.com/SpiderLabs/ModSecurity cd ModSecurity # 初始化并更新子模块特别是重要的libinjection库 git submodule init git submodule update这里有一个关键点务必使用git submodule update。ModSecurity依赖libinjection等子模块进行高效的SQLi/XSS令牌化分析如果子模块没拉取编译会失败或功能不全。我曾在一次内网部署中因为网络问题导致子模块缺失排查了许久才发现规则引擎对某些简单攻击无效。3. 编译与集成让Nginx“学会”安全检测这是整个流程中最核心也最容易出错的一步。我们的目标是将ModSecurity编译成一个Nginx的动态模块ngx_http_modsecurity_module.so这样可以在不重新编译Nginx主体的情况下加载或卸载WAF功能灵活性更高。3.1 编译ModSecurity连接库首先我们需要将ModSecurity编译成一个独立的连接库libmodsecurity.so。cd ~/nginx-waf/ModSecurity ./build.sh ./configure --prefix/usr/local/modsecurity --with-yajl --with-ssdeep --with-lmdb --with-libcurl make sudo make installconfigure参数说明--prefix指定安装目录方便管理。--with-yajl启用JSON支持。--with-ssdeep启用模糊哈希用于文件上传检查。--with-lmdb使用LMDB作为持久化存储后端性能优于磁盘文件。--with-libcurl允许ModSecurity向外部服务发起请求如主动验证挑战。执行make时如果报错缺少libinjection回头检查子模块是否更新成功。编译完成后库文件会安装在/usr/local/modsecurity/lib/下头文件在/usr/local/modsecurity/include/。3.2 编译支持ModSecurity的Nginx动态模块现在进入Nginx源码目录将其编译为支持动态模块加载的版本并加入我们刚编译好的ModSecurity库。cd ~/nginx-waf/nginx-1.24.0 ./configure --prefix/usr/local/nginx \ --with-compat \ --with-file-aio \ --with-threads \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_realip_module \ --with-http_gunzip_module \ --with-http_gzip_static_module \ --add-dynamic-module../ModSecurity/nginx/modsecurity make modules关键参数解析--with-compat开启动态模块兼容模式这是使用load_module指令加载.so文件的前提。--add-dynamic-module指向ModSecurity源码中的nginx/modsecurity目录这是Nginx模块的集成代码。我们只运行make modules而不是make make install因为目标只是生成模块文件避免覆盖系统中可能已存在的Nginx。编译过程会去链接/usr/local/modsecurity/lib下的库。如果遇到链接错误提示找不到-lmodsecurity可能需要手动设置库路径export LD_LIBRARY_PATH/usr/local/modsecurity/lib:$LD_LIBRARY_PATH # 或者将其永久添加到 /etc/ld.so.conf.d/ 并运行 ldconfig sudo sh -c echo /usr/local/modsecurity/lib /etc/ld.so.conf.d/modsecurity.conf sudo ldconfig编译成功后在objs/目录下会生成ngx_http_modsecurity_module.so文件。将其复制到Nginx的标准模块目录sudo cp objs/ngx_http_modsecurity_module.so /usr/local/nginx/modules/3.3 加载模块与基础配置现在编辑Nginx的主配置文件nginx.conf在顶层events块之前加载动态模块。# /usr/local/nginx/conf/nginx.conf load_module modules/ngx_http_modsecurity_module.so; user nginx; worker_processes auto; ...接下来在http块内启用ModSecurity并指定主配置文件路径。http { ... modsecurity on; modsecurity_rules_file /usr/local/nginx/conf/modsecurity.conf; server { listen 80; server_name your_domain.com; ... } }创建ModSecurity的主配置文件/usr/local/nginx/conf/modsecurity.conf写入最基础的配置# modsecurity.conf - 基础配置 SecRuleEngine DetectionOnly SecAuditEngine RelevantOnly SecAuditLog /var/log/nginx/modsec_audit.log SecDebugLog /var/log/nginx/modsec_debug.log SecDebugLogLevel 0 SecAuditLogType Serial SecAuditLogParts ABCDEFGHIJKZ SecArgumentSeparator SecCookieFormat 0 SecUnicodeMapFile unicode.mapping 20127 SecStatusEngine On配置项解读SecRuleEngine On|DetectionOnly|Off这是最重要的开关。初次部署务必设为DetectionOnly仅检测避免误拦截正常流量。观察一段时间后再改为On拦截。SecAuditEngine审计日志引擎。RelevantOnly表示只记录触发规则的请求节省磁盘空间。SecAuditLogParts定义审计日志记录的内容。ABCDEFGHIJKZ是一个常用组合包含了请求头、响应头、请求体、响应体等完整信息便于事后分析。SecArgumentSeparator 定义查询参数分隔符默认为与标准一致。SecUnicodeMapFile指定Unicode映射文件用于处理非ASCII字符的攻击编码需要从ModSecurity源码中复制。复制必要的支持文件sudo cp ~/nginx-waf/ModSecurity/unicode.mapping /usr/local/nginx/conf/ sudo mkdir -p /var/log/nginx/ sudo chown nginx:nginx /var/log/nginx/至此Nginx与ModSecurity的集成已经完成。执行sudo /usr/local/nginx/sbin/nginx -t测试配置无误后启动或重载Nginx。4. 规则配置从OWASP CRS到自定义策略引擎搭好了但没有规则的WAF就像没有子弹的枪。OWASP ModSecurity核心规则集CRS是我们最好的起点。4.1 部署OWASP核心规则集CRSCRS提供了一套开箱即用的、针对常见Web攻击的防护规则。我们去GitHub下载最新版本。cd /usr/local/nginx/conf sudo git clone https://github.com/coreruleset/coreruleset.git cd coreruleset # 使用最新的稳定版本标签例如 v3.3.5 sudo git checkout v3.3.5现在修改ModSecurity主配置文件modsecurity.conf引入CRS。# modsecurity.conf - 引入CRS Include coreruleset/crs-setup.conf.example Include coreruleset/rules/*.conf重要步骤重命名并配置CRS设置文件cd /usr/local/nginx/conf/coreruleset sudo cp crs-setup.conf.example crs-setup.conf编辑crs-setup.conf这是CRS的“控制中心”。有几个关键参数必须调整# 在 crs-setup.conf 中 # 1. 将防护模式从“自学习”改为“传统”检测模式。新手建议用传统模式。 SecDefaultAction phase:1,log,auditlog,pass SecDefaultAction phase:2,log,auditlog,pass # 2. 设置Paranoia Level偏执等级。PL1是默认值误报率低但可能漏报。生产环境可逐步提高到PL2或PL3但需配合白名单。 # 修改每个规则文件中的ACTION行过于繁琐可以通过在modsecurity.conf最前面覆盖变量来全局设置 SecAction \ id:900000,\ phase:1,\ nolog,\ pass,\ t:none,\ setvar:tx.paranoia_level1 # 3. 设置异常评分阈值。当请求的异常分数超过该阈值时请求会被拦截。 SecAction \ id:900001,\ phase:1,\ nolog,\ pass,\ t:none,\ setvar:tx.inbound_anomaly_score_threshold5,\ setvar:tx.outbound_anomaly_score_threshold44.2 理解规则结构与评分机制CRS采用“异常评分”模式而非“一票否决”。每条规则被触发时会根据威胁严重性增加一个分数如SQL注入加5分可疑User-Agent加2分。当一个请求在阶段1请求头和阶段2请求体的总分分别超过tx.inbound_anomaly_score_threshold和tx.outbound_anomaly_score_threshold时才会被最终拦截。这种模式大大减少了误报因为单次可疑行为如一个奇怪的参数名不会直接封杀请求只有累积到足够威胁时才行动。你可以在审计日志中看到每条触发的规则及其贡献的分数。4.3 编写自定义规则与白名单CRS虽好但难免会误伤自家应用。这时就需要自定义规则和白名单。永远不要直接修改CRS规则文件而应在modsecurity.conf中Include语句之后添加自己的配置文件如custom_rules.conf。场景一误报排除白名单假设你的登录接口/api/login的username参数允许包含单引号可能是合法用户名而CRS规则942100SQL注入检测误报了。# custom_rules.conf # 方法1通过规则ID禁用不推荐可能影响其他地方的防护 # SecRuleRemoveById 942100 # 方法2针对特定路径和参数添加白名单推荐 SecRule REQUEST_URI beginsWith /api/login \ id:1000,\ phase:1,\ nolog,\ pass,\ ctl:ruleRemoveTargetById942100;ARGS:username这条规则的意思是对于以/api/login开头的请求在阶段1静默地nolog放行pass并控制ctl规则ID 942100使其移除RemoveTarget对参数ARGS:username的检查。场景二添加自定义防护规则假设你想阻止来自某个特定User-Agent的爬虫。SecRule REQUEST_HEADERS:User-Agent pm EvilBot/1.0 BadCrawler/2.0 \ id:2000,\ phase:1,\ log,\ deny,\ status:403,\ msg:Blocked malicious bot,\ tag:custom_bot_blockpm是部分匹配操作符。deny动作直接拒绝请求返回状态码403。msg和tag便于在日志中识别。场景三限制特定接口的访问频率虽然Nginx有限流模块但用ModSecurity实现可以结合更复杂的条件如POST请求体内容。# 使用ModSecurity的“持久化存储”功能实现计数 SecRule REQUEST_URI streq /api/submit \ id:3000,\ phase:1,\ log,\ pass,\ setvar:TX.rate_counter/api/submit-%{REMOTE_ADDR},\ setvar:TX.rate_timewindow60,\ setvar:TX.rate_limit10 SecAction \ id:3001,\ phase:1,\ log,\ pass,\ initcol:ip%{TX.rate_counter},\ setvar:ip.rate_counter1 SecRule IP:RATE_COUNTER gt %{TX.rate_limit} \ id:3002,\ phase:1,\ log,\ deny,\ status:429,\ msg:Rate limit exceeded,\ tag:custom_rate_limit这个例子略显复杂它演示了如何利用ModSecurity的initcol在内存或LMDB中为每个IP-接口组合创建一个计数器并在1分钟内限制访问次数。对于简单的频率限制使用Nginx的limit_req模块性能更优。5. 实战调优与运维监控配置上线后真正的挑战才开始如何让WAF既安全又不影响业务5.1 日志分析与误报处理ModSecurity的审计日志modsec_audit.log是JSON格式如果配置了SecAuditLogFormat JSON信息量巨大但不易读。我推荐使用jq工具进行命令行分析或者将日志接入ELKElasticsearch, Logstash, Kibana栈进行可视化。快速定位拦截请求sudo tail -f /var/log/nginx/modsec_audit.log | grep -A 5 -B 5 action:{block统计触发最多的规则IDsudo cat /var/log/nginx/modsec_audit.log | jq -r .transaction.messages[].details.ruleId | sort | uniq -c | sort -rn | head -20当你发现某条规则例如942100频繁误报时回到第4.3节为你的应用添加精确的白名单。处理误报的原则是范围尽可能小。不要全局禁用一条规则而是针对特定的URL、参数或IP进行豁免。5.2 性能调优要点WAF会带来性能开销主要来自正则表达式匹配和请求体解析。以下调优手段能有效降低影响调整SecRequestBodyLimit和SecResponseBodyLimit默认请求体限制是128MB对于纯API服务可以降低到10-20MB。对于不检查响应体的场景可以将SecResponseBodyLimit设为0。SecRequestBodyLimit 10485760 # 10MB SecResponseBodyLimit 0禁用不必要的规则文件CRS的rules/目录下有很多针对特定应用如WordPress, Drupal的规则。如果你的服务器上没有这些应用可以注释掉对应的Include行。# Include coreruleset/rules/REQUEST-913-SCANNER-DETECTION.conf # Include coreruleset/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf使用SecRuleEngine DetectionOnly进行性能基线测试在流量高峰时段开启检测模式运行24小时监控Nginx的请求延迟$request_time和服务器负载与关闭ModSecurity时进行对比量化性能影响。合理设置SecAuditLogParts如果不需要审计日志中的响应体K部分可以将其移除能显著减少日志体积和I/O压力。ABCEFHIZ是一个常用的精简组合。5.3 高可用与自动化部署考量在生产环境中WAF节点不应是单点。可以考虑以下架构独立WAF集群使用NginxModSecurity构建独立的WAF代理层置于负载均衡器如HAProxy之后业务Nginx之前。这样可以对WAF节点进行滚动更新和扩缩容。配置版本化管理将modsecurity.conf、crs-setup.conf、custom_rules.conf等配置文件纳入Git版本控制。任何规则变更都经过测试环境验证后再推送至生产。自动化规则更新为CRS目录设置一个定时任务如每周拉取最新的规则更新。但务必在测试环境充分验证后再同步到生产环境因为新规则可能引入新的误报。# 示例 crontab 0 2 * * 6 cd /usr/local/nginx/conf/coreruleset git pull origin v3.3/master nginx -t systemctl reload nginx6. 常见问题与故障排查实录在这一部分我分享几个自己踩过并且帮别人解决过的典型问题。6.1 编译与启动问题问题1nginx -t报错load_module指令未知。原因Nginx二进制文件不是在--with-compat模式下编译的或者动态模块路径错误。解决确认编译时使用了--with-compat参数并且load_module指令指向正确的.so文件绝对路径。使用nginx -V查看编译参数。问题2Nginx启动失败错误日志显示modsecurity: module is not specified...原因ModSecurity连接库libmodsecurity.so未被系统找到。解决确保/usr/local/modsecurity/lib已添加到动态链接库路径中见3.2节并执行sudo ldconfig。也可以将库文件直接复制到系统库目录sudo cp /usr/local/modsecurity/lib/libmodsecurity.so /usr/lib64/。6.2 规则运行与拦截问题问题3规则似乎不生效攻击请求没有被拦截或记录。排查步骤检查SecRuleEngine是否为On或DetectionOnly。检查modsecurity_rules_file路径是否正确Nginx进程是否有读取权限。在modsecurity.conf中开启调试日志SecDebugLogLevel 3并观察modsec_debug.log。注意调试日志量极大仅在排查时临时开启。使用一个简单的测试规则验证引擎是否工作SecRule ARGS:testparam contains attack id:999999,phase:1,log,deny,status:403,msg:Test rule fired然后访问http://yoursite.com/?testparamattack看是否被拦截。问题4误报太多正常用户被拦截。解决流程降级运行先将SecRuleEngine设为DetectionOnly让规则只记录不拦截。分析日志找到被误报的规则ID、触发该规则的请求详情URL、参数。添加白名单使用ctl:ruleRemoveTargetById或SecRuleRemoveById谨慎创建精确的白名单规则。调整偏执等级如果误报普遍且广泛考虑在crs-setup.conf中降低tx.paranoia_level从2或3降为1。迭代优化将白名单规则加入custom_rules.conf反复测试。6.3 性能与稳定性问题问题5启用WAF后服务器负载明显升高或上传大文件超时。原因请求体解析和检查消耗资源。默认配置会检查所有请求体。优化如5.2节所述调整SecRequestBodyLimit和SecRequestBodyNoFilesLimit。对于已知安全的文件上传路径可以禁用请求体检查location /upload/ { modsecurity off; # 或者仅关闭请求体解析 # SecRuleEngine Off # 但更精细的控制是使用 location 级别的规则移除 }考虑升级硬件或对静态资源、媒体文件等路径完全关闭ModSecurity。问题6审计日志文件增长过快磁盘被占满。解决设置日志轮转。使用logrotate工具创建配置文件/etc/logrotate.d/modsecurity/var/log/nginx/modsec_audit.log { daily rotate 30 compress delaycompress missingok notifempty create 640 nginx nginx sharedscripts postrotate /bin/kill -USR1 cat /run/nginx.pid 2/dev/null 2/dev/null || true endscript }调整SecAuditLogParts移除不必要部分如响应体K。考虑使用SecAuditLogType Concurrent并将日志写入独立的磁盘或分区。最后我想强调的是部署WAF不是一个“一劳永逸”的操作而是一个持续运营的过程。你需要定期查看日志分析攻击趋势根据业务变化调整规则和白名单。一开始可能会觉得麻烦但当你第一次在日志里看到它成功拦截了一次真实的SQL注入尝试时你会觉得这一切都是值得的。这套方案为我管理的多个项目挡住了无数自动化扫描和试探性攻击它就像一位不知疲倦的哨兵而你需要做的就是了解它的脾气并把它安排在正确的位置上。
1. 项目概述为什么需要NginxModSecurity WAF在今天的网络环境中Web应用防火墙WAF早已不是大型企业的专属它已经成为任何对外提供服务的网站或应用必须考虑的基础安全组件。你可能已经熟练使用Nginx来处理反向代理、负载均衡和静态资源服务但面对层出不穷的SQL注入、跨站脚本XSS、路径遍历等攻击仅靠Nginx自身的ngx_http_limit_req_module限流或简单的location过滤是远远不够的。这时一个成熟的WAF方案就显得至关重要。ModSecurity是一个开源的、跨平台的Web应用防火墙引擎它最初是Apache的一个模块后来发展出了支持Nginx的版本——ModSecurity 3.0。与商业WAF相比它的优势在于完全免费、规则高度可定制并且拥有一个活跃的社区OWASP ModSecurity核心规则集。将ModSecurity 3.0与Nginx集成相当于为你的Nginx服务器装上了一套“智能免疫系统”能够实时解析HTTP/HTTPS流量根据预定义的安全规则对请求和响应进行深度检测与拦截。我选择这个组合是因为它在资源开销、防护能力和可控性之间取得了很好的平衡。对于中小型项目或个人开发者自建WAF不仅能有效提升应用安全水位更是深入了解HTTP协议和安全攻防的绝佳实践。接下来我将带你从零开始完成Nginx与ModSecurity 3.0.x的整合、编译、配置到核心规则调优的全过程分享其中每一步的实操细节和我踩过的坑。2. 环境准备与依赖安装在开始编译安装之前一个干净、稳定的基础环境是成功的首要条件。我强烈建议在一台全新的测试服务器或虚拟机上进行首次尝试避免与现有环境冲突。2.1 系统环境与工具链确认本次实战以主流的CentOS 7.x或Rocky Linux 8/9为例其他基于RPM或APT的发行版步骤类似但包名可能不同。首先更新系统并安装必要的开发工具和依赖库。# 对于CentOS 7 / Rocky Linux 8 sudo yum groupinstall -y Development Tools sudo yum install -y epel-release sudo yum install -y wget git pcre-devel openssl-devel libxml2-devel geoip-devel yajl-devel curl-devel lmdb-devel ssdeep-devel libmaxminddb-devel gcc-c flex bison # 对于Ubuntu 20.04/22.04 sudo apt update sudo apt install -y build-essential git libpcre3-dev libssl-dev zlib1g-dev libxml2-dev libgeoip-dev libyajl-dev libcurl4-openssl-dev liblmdb-dev libfuzzy-dev libmaxminddb-dev autoconf automake libtool这里安装的依赖包每一个都有其作用pcre-develPerl兼容正则表达式库Nginx和ModSecurity规则匹配的核心。openssl-devel提供HTTPS支持。libxml2-devel用于解析XML格式的请求体如SOAP API。yajl-develJSON解析库现代API防护必备。libmaxminddb-devel用于集成GeoIP地理位置数据库实现基于地区的访问控制。ssdeep-devel/libfuzzy-dev模糊哈希库用于恶意文件检测。注意libmaxminddb-devel和ssdeep-devel不是强制依赖但如果你计划使用GeoIP功能或文件上传检查强烈建议安装。否则后续编译ModSecurity时可能需要禁用相关功能。2.2 获取Nginx与ModSecurity源码我们不使用系统包管理器安装Nginx因为需要动态加载ModSecurity模块。去Nginx官网下载最新的稳定版如1.24.x和ModSecurity 3.0.x的源码。# 创建一个工作目录 mkdir ~/nginx-waf cd ~/nginx-waf # 下载Nginx源码 wget http://nginx.org/download/nginx-1.24.0.tar.gz tar -xzvf nginx-1.24.0.tar.gz # 下载ModSecurity 3源码 git clone --depth 1 -b v3/master https://github.com/SpiderLabs/ModSecurity cd ModSecurity # 初始化并更新子模块特别是重要的libinjection库 git submodule init git submodule update这里有一个关键点务必使用git submodule update。ModSecurity依赖libinjection等子模块进行高效的SQLi/XSS令牌化分析如果子模块没拉取编译会失败或功能不全。我曾在一次内网部署中因为网络问题导致子模块缺失排查了许久才发现规则引擎对某些简单攻击无效。3. 编译与集成让Nginx“学会”安全检测这是整个流程中最核心也最容易出错的一步。我们的目标是将ModSecurity编译成一个Nginx的动态模块ngx_http_modsecurity_module.so这样可以在不重新编译Nginx主体的情况下加载或卸载WAF功能灵活性更高。3.1 编译ModSecurity连接库首先我们需要将ModSecurity编译成一个独立的连接库libmodsecurity.so。cd ~/nginx-waf/ModSecurity ./build.sh ./configure --prefix/usr/local/modsecurity --with-yajl --with-ssdeep --with-lmdb --with-libcurl make sudo make installconfigure参数说明--prefix指定安装目录方便管理。--with-yajl启用JSON支持。--with-ssdeep启用模糊哈希用于文件上传检查。--with-lmdb使用LMDB作为持久化存储后端性能优于磁盘文件。--with-libcurl允许ModSecurity向外部服务发起请求如主动验证挑战。执行make时如果报错缺少libinjection回头检查子模块是否更新成功。编译完成后库文件会安装在/usr/local/modsecurity/lib/下头文件在/usr/local/modsecurity/include/。3.2 编译支持ModSecurity的Nginx动态模块现在进入Nginx源码目录将其编译为支持动态模块加载的版本并加入我们刚编译好的ModSecurity库。cd ~/nginx-waf/nginx-1.24.0 ./configure --prefix/usr/local/nginx \ --with-compat \ --with-file-aio \ --with-threads \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_realip_module \ --with-http_gunzip_module \ --with-http_gzip_static_module \ --add-dynamic-module../ModSecurity/nginx/modsecurity make modules关键参数解析--with-compat开启动态模块兼容模式这是使用load_module指令加载.so文件的前提。--add-dynamic-module指向ModSecurity源码中的nginx/modsecurity目录这是Nginx模块的集成代码。我们只运行make modules而不是make make install因为目标只是生成模块文件避免覆盖系统中可能已存在的Nginx。编译过程会去链接/usr/local/modsecurity/lib下的库。如果遇到链接错误提示找不到-lmodsecurity可能需要手动设置库路径export LD_LIBRARY_PATH/usr/local/modsecurity/lib:$LD_LIBRARY_PATH # 或者将其永久添加到 /etc/ld.so.conf.d/ 并运行 ldconfig sudo sh -c echo /usr/local/modsecurity/lib /etc/ld.so.conf.d/modsecurity.conf sudo ldconfig编译成功后在objs/目录下会生成ngx_http_modsecurity_module.so文件。将其复制到Nginx的标准模块目录sudo cp objs/ngx_http_modsecurity_module.so /usr/local/nginx/modules/3.3 加载模块与基础配置现在编辑Nginx的主配置文件nginx.conf在顶层events块之前加载动态模块。# /usr/local/nginx/conf/nginx.conf load_module modules/ngx_http_modsecurity_module.so; user nginx; worker_processes auto; ...接下来在http块内启用ModSecurity并指定主配置文件路径。http { ... modsecurity on; modsecurity_rules_file /usr/local/nginx/conf/modsecurity.conf; server { listen 80; server_name your_domain.com; ... } }创建ModSecurity的主配置文件/usr/local/nginx/conf/modsecurity.conf写入最基础的配置# modsecurity.conf - 基础配置 SecRuleEngine DetectionOnly SecAuditEngine RelevantOnly SecAuditLog /var/log/nginx/modsec_audit.log SecDebugLog /var/log/nginx/modsec_debug.log SecDebugLogLevel 0 SecAuditLogType Serial SecAuditLogParts ABCDEFGHIJKZ SecArgumentSeparator SecCookieFormat 0 SecUnicodeMapFile unicode.mapping 20127 SecStatusEngine On配置项解读SecRuleEngine On|DetectionOnly|Off这是最重要的开关。初次部署务必设为DetectionOnly仅检测避免误拦截正常流量。观察一段时间后再改为On拦截。SecAuditEngine审计日志引擎。RelevantOnly表示只记录触发规则的请求节省磁盘空间。SecAuditLogParts定义审计日志记录的内容。ABCDEFGHIJKZ是一个常用组合包含了请求头、响应头、请求体、响应体等完整信息便于事后分析。SecArgumentSeparator 定义查询参数分隔符默认为与标准一致。SecUnicodeMapFile指定Unicode映射文件用于处理非ASCII字符的攻击编码需要从ModSecurity源码中复制。复制必要的支持文件sudo cp ~/nginx-waf/ModSecurity/unicode.mapping /usr/local/nginx/conf/ sudo mkdir -p /var/log/nginx/ sudo chown nginx:nginx /var/log/nginx/至此Nginx与ModSecurity的集成已经完成。执行sudo /usr/local/nginx/sbin/nginx -t测试配置无误后启动或重载Nginx。4. 规则配置从OWASP CRS到自定义策略引擎搭好了但没有规则的WAF就像没有子弹的枪。OWASP ModSecurity核心规则集CRS是我们最好的起点。4.1 部署OWASP核心规则集CRSCRS提供了一套开箱即用的、针对常见Web攻击的防护规则。我们去GitHub下载最新版本。cd /usr/local/nginx/conf sudo git clone https://github.com/coreruleset/coreruleset.git cd coreruleset # 使用最新的稳定版本标签例如 v3.3.5 sudo git checkout v3.3.5现在修改ModSecurity主配置文件modsecurity.conf引入CRS。# modsecurity.conf - 引入CRS Include coreruleset/crs-setup.conf.example Include coreruleset/rules/*.conf重要步骤重命名并配置CRS设置文件cd /usr/local/nginx/conf/coreruleset sudo cp crs-setup.conf.example crs-setup.conf编辑crs-setup.conf这是CRS的“控制中心”。有几个关键参数必须调整# 在 crs-setup.conf 中 # 1. 将防护模式从“自学习”改为“传统”检测模式。新手建议用传统模式。 SecDefaultAction phase:1,log,auditlog,pass SecDefaultAction phase:2,log,auditlog,pass # 2. 设置Paranoia Level偏执等级。PL1是默认值误报率低但可能漏报。生产环境可逐步提高到PL2或PL3但需配合白名单。 # 修改每个规则文件中的ACTION行过于繁琐可以通过在modsecurity.conf最前面覆盖变量来全局设置 SecAction \ id:900000,\ phase:1,\ nolog,\ pass,\ t:none,\ setvar:tx.paranoia_level1 # 3. 设置异常评分阈值。当请求的异常分数超过该阈值时请求会被拦截。 SecAction \ id:900001,\ phase:1,\ nolog,\ pass,\ t:none,\ setvar:tx.inbound_anomaly_score_threshold5,\ setvar:tx.outbound_anomaly_score_threshold44.2 理解规则结构与评分机制CRS采用“异常评分”模式而非“一票否决”。每条规则被触发时会根据威胁严重性增加一个分数如SQL注入加5分可疑User-Agent加2分。当一个请求在阶段1请求头和阶段2请求体的总分分别超过tx.inbound_anomaly_score_threshold和tx.outbound_anomaly_score_threshold时才会被最终拦截。这种模式大大减少了误报因为单次可疑行为如一个奇怪的参数名不会直接封杀请求只有累积到足够威胁时才行动。你可以在审计日志中看到每条触发的规则及其贡献的分数。4.3 编写自定义规则与白名单CRS虽好但难免会误伤自家应用。这时就需要自定义规则和白名单。永远不要直接修改CRS规则文件而应在modsecurity.conf中Include语句之后添加自己的配置文件如custom_rules.conf。场景一误报排除白名单假设你的登录接口/api/login的username参数允许包含单引号可能是合法用户名而CRS规则942100SQL注入检测误报了。# custom_rules.conf # 方法1通过规则ID禁用不推荐可能影响其他地方的防护 # SecRuleRemoveById 942100 # 方法2针对特定路径和参数添加白名单推荐 SecRule REQUEST_URI beginsWith /api/login \ id:1000,\ phase:1,\ nolog,\ pass,\ ctl:ruleRemoveTargetById942100;ARGS:username这条规则的意思是对于以/api/login开头的请求在阶段1静默地nolog放行pass并控制ctl规则ID 942100使其移除RemoveTarget对参数ARGS:username的检查。场景二添加自定义防护规则假设你想阻止来自某个特定User-Agent的爬虫。SecRule REQUEST_HEADERS:User-Agent pm EvilBot/1.0 BadCrawler/2.0 \ id:2000,\ phase:1,\ log,\ deny,\ status:403,\ msg:Blocked malicious bot,\ tag:custom_bot_blockpm是部分匹配操作符。deny动作直接拒绝请求返回状态码403。msg和tag便于在日志中识别。场景三限制特定接口的访问频率虽然Nginx有限流模块但用ModSecurity实现可以结合更复杂的条件如POST请求体内容。# 使用ModSecurity的“持久化存储”功能实现计数 SecRule REQUEST_URI streq /api/submit \ id:3000,\ phase:1,\ log,\ pass,\ setvar:TX.rate_counter/api/submit-%{REMOTE_ADDR},\ setvar:TX.rate_timewindow60,\ setvar:TX.rate_limit10 SecAction \ id:3001,\ phase:1,\ log,\ pass,\ initcol:ip%{TX.rate_counter},\ setvar:ip.rate_counter1 SecRule IP:RATE_COUNTER gt %{TX.rate_limit} \ id:3002,\ phase:1,\ log,\ deny,\ status:429,\ msg:Rate limit exceeded,\ tag:custom_rate_limit这个例子略显复杂它演示了如何利用ModSecurity的initcol在内存或LMDB中为每个IP-接口组合创建一个计数器并在1分钟内限制访问次数。对于简单的频率限制使用Nginx的limit_req模块性能更优。5. 实战调优与运维监控配置上线后真正的挑战才开始如何让WAF既安全又不影响业务5.1 日志分析与误报处理ModSecurity的审计日志modsec_audit.log是JSON格式如果配置了SecAuditLogFormat JSON信息量巨大但不易读。我推荐使用jq工具进行命令行分析或者将日志接入ELKElasticsearch, Logstash, Kibana栈进行可视化。快速定位拦截请求sudo tail -f /var/log/nginx/modsec_audit.log | grep -A 5 -B 5 action:{block统计触发最多的规则IDsudo cat /var/log/nginx/modsec_audit.log | jq -r .transaction.messages[].details.ruleId | sort | uniq -c | sort -rn | head -20当你发现某条规则例如942100频繁误报时回到第4.3节为你的应用添加精确的白名单。处理误报的原则是范围尽可能小。不要全局禁用一条规则而是针对特定的URL、参数或IP进行豁免。5.2 性能调优要点WAF会带来性能开销主要来自正则表达式匹配和请求体解析。以下调优手段能有效降低影响调整SecRequestBodyLimit和SecResponseBodyLimit默认请求体限制是128MB对于纯API服务可以降低到10-20MB。对于不检查响应体的场景可以将SecResponseBodyLimit设为0。SecRequestBodyLimit 10485760 # 10MB SecResponseBodyLimit 0禁用不必要的规则文件CRS的rules/目录下有很多针对特定应用如WordPress, Drupal的规则。如果你的服务器上没有这些应用可以注释掉对应的Include行。# Include coreruleset/rules/REQUEST-913-SCANNER-DETECTION.conf # Include coreruleset/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf使用SecRuleEngine DetectionOnly进行性能基线测试在流量高峰时段开启检测模式运行24小时监控Nginx的请求延迟$request_time和服务器负载与关闭ModSecurity时进行对比量化性能影响。合理设置SecAuditLogParts如果不需要审计日志中的响应体K部分可以将其移除能显著减少日志体积和I/O压力。ABCEFHIZ是一个常用的精简组合。5.3 高可用与自动化部署考量在生产环境中WAF节点不应是单点。可以考虑以下架构独立WAF集群使用NginxModSecurity构建独立的WAF代理层置于负载均衡器如HAProxy之后业务Nginx之前。这样可以对WAF节点进行滚动更新和扩缩容。配置版本化管理将modsecurity.conf、crs-setup.conf、custom_rules.conf等配置文件纳入Git版本控制。任何规则变更都经过测试环境验证后再推送至生产。自动化规则更新为CRS目录设置一个定时任务如每周拉取最新的规则更新。但务必在测试环境充分验证后再同步到生产环境因为新规则可能引入新的误报。# 示例 crontab 0 2 * * 6 cd /usr/local/nginx/conf/coreruleset git pull origin v3.3/master nginx -t systemctl reload nginx6. 常见问题与故障排查实录在这一部分我分享几个自己踩过并且帮别人解决过的典型问题。6.1 编译与启动问题问题1nginx -t报错load_module指令未知。原因Nginx二进制文件不是在--with-compat模式下编译的或者动态模块路径错误。解决确认编译时使用了--with-compat参数并且load_module指令指向正确的.so文件绝对路径。使用nginx -V查看编译参数。问题2Nginx启动失败错误日志显示modsecurity: module is not specified...原因ModSecurity连接库libmodsecurity.so未被系统找到。解决确保/usr/local/modsecurity/lib已添加到动态链接库路径中见3.2节并执行sudo ldconfig。也可以将库文件直接复制到系统库目录sudo cp /usr/local/modsecurity/lib/libmodsecurity.so /usr/lib64/。6.2 规则运行与拦截问题问题3规则似乎不生效攻击请求没有被拦截或记录。排查步骤检查SecRuleEngine是否为On或DetectionOnly。检查modsecurity_rules_file路径是否正确Nginx进程是否有读取权限。在modsecurity.conf中开启调试日志SecDebugLogLevel 3并观察modsec_debug.log。注意调试日志量极大仅在排查时临时开启。使用一个简单的测试规则验证引擎是否工作SecRule ARGS:testparam contains attack id:999999,phase:1,log,deny,status:403,msg:Test rule fired然后访问http://yoursite.com/?testparamattack看是否被拦截。问题4误报太多正常用户被拦截。解决流程降级运行先将SecRuleEngine设为DetectionOnly让规则只记录不拦截。分析日志找到被误报的规则ID、触发该规则的请求详情URL、参数。添加白名单使用ctl:ruleRemoveTargetById或SecRuleRemoveById谨慎创建精确的白名单规则。调整偏执等级如果误报普遍且广泛考虑在crs-setup.conf中降低tx.paranoia_level从2或3降为1。迭代优化将白名单规则加入custom_rules.conf反复测试。6.3 性能与稳定性问题问题5启用WAF后服务器负载明显升高或上传大文件超时。原因请求体解析和检查消耗资源。默认配置会检查所有请求体。优化如5.2节所述调整SecRequestBodyLimit和SecRequestBodyNoFilesLimit。对于已知安全的文件上传路径可以禁用请求体检查location /upload/ { modsecurity off; # 或者仅关闭请求体解析 # SecRuleEngine Off # 但更精细的控制是使用 location 级别的规则移除 }考虑升级硬件或对静态资源、媒体文件等路径完全关闭ModSecurity。问题6审计日志文件增长过快磁盘被占满。解决设置日志轮转。使用logrotate工具创建配置文件/etc/logrotate.d/modsecurity/var/log/nginx/modsec_audit.log { daily rotate 30 compress delaycompress missingok notifempty create 640 nginx nginx sharedscripts postrotate /bin/kill -USR1 cat /run/nginx.pid 2/dev/null 2/dev/null || true endscript }调整SecAuditLogParts移除不必要部分如响应体K。考虑使用SecAuditLogType Concurrent并将日志写入独立的磁盘或分区。最后我想强调的是部署WAF不是一个“一劳永逸”的操作而是一个持续运营的过程。你需要定期查看日志分析攻击趋势根据业务变化调整规则和白名单。一开始可能会觉得麻烦但当你第一次在日志里看到它成功拦截了一次真实的SQL注入尝试时你会觉得这一切都是值得的。这套方案为我管理的多个项目挡住了无数自动化扫描和试探性攻击它就像一位不知疲倦的哨兵而你需要做的就是了解它的脾气并把它安排在正确的位置上。
