1. 项目概述为什么需要NAXSI在Web应用的世界里Nginx无疑是那个站在流量入口的“门神”它高效、稳定负责分发请求、负载均衡。但如果你认为只要部署了Nginx你的网站就安全了那可能就有点过于乐观了。Nginx本身是一个高性能的HTTP和反向代理服务器它的核心职责是“服务”而不是“防御”。面对SQL注入、跨站脚本XSS、本地文件包含LFI等层出不穷的Web攻击一个没有“免疫系统”的Nginx就像一座不设防的城池。这就是NAXSI登场的时候。NAXSI全称“Nginx Anti XSS SQL Injection”是一个开源的、第三方的Nginx模块专门设计用来充当Web应用防火墙WAF。它不像ModSecurity那样庞大复杂需要依赖大量的规则集。NAXSI的核心哲学是“白名单”和“学习模式”。它默认拦截一切看起来可疑的输入然后由管理员通过分析日志将合法的请求行为逐步添加到白名单中。这种“默认拒绝例外允许”的策略虽然初期配置需要一些精力但一旦稳定其安全性和性能开销都相当出色。对于追求轻量、高效、且希望深度掌控安全策略的运维和开发人员来说NAXSI是一个极具吸引力的选择。今天我们就来手把手完成一份NAXSI的完整配置指南用5个核心步骤为你的Nginx穿上坚固的铠甲。2. NAXSI核心原理与架构设计2.1 白名单与评分机制NAXSI的防御逻辑理解NAXSI首先要抛弃传统黑名单WAF的思维。黑名单是“我知道什么是坏的我阻止它”。而NAXSI采用的是“我不知道什么是好的所以我先阻止一切然后你告诉我什么是好的”。NAXSI的实现基于一套评分系统。它对每个HTTP请求的各个部分如URL、参数、请求头、请求体进行扫描寻找可能代表攻击的“特征”Libinjection库用于检测SQLi和XSS。每匹配到一个特征就增加相应的分数。这个分数被称为“异常分数”。NAXSI为请求的不同部分设置了独立的分数阈值例如$URL、$ARGSGET参数、$BODYPOST参数等。同时还有一个总分的阈值$TX。它的工作流程是这样的初始化拦截默认情况下任何包含可疑特征的请求都会被拦截因为其分数会超过阈值。学习模式这是关键。在初始部署阶段我们会将NAXSI置于“学习模式”。在此模式下NAXSI不会真正拦截请求而是会将所有触发规则的请求详情包括分数、匹配的规则ID、具体的恶意负载记录到错误日志中。分析日志与生成白名单管理员分析学习阶段产生的日志识别出哪些是业务正常运行所必需的“误报”。例如一个搜索功能用户输入script作为关键词这会被NAXSI标记为XSS攻击。但在你的业务里这可能是合法的比如一个代码分享网站。这时你就需要为这个特定的参数如qscript创建一条白名单规则。应用白名单将生成的白名单规则写入NAXSI的配置文件。白名单规则非常精确可以指定到具体的URL、参数名、参数值甚至参数值的特定部分。添加白名单后合法的请求即使触发了某些特征其异常分数也会被相应扣除从而低于拦截阈值得以放行。生产模式当白名单足够完善覆盖了所有正常业务流量后即可关闭学习模式进入生产拦截模式。此时任何未在白名单中定义的、携带攻击特征的请求都将被果断拒绝。这种模式的优点是误报率极低规则维护量小因为规则是你的业务独有的且性能损耗相对固定。缺点是初始配置阶段需要结合真实业务流量进行分析有一定学习成本。2.2 与Nginx的集成方式编译与动态模块NAXSI作为Nginx的模块有两种主要集成方式静态编译和动态加载。静态编译这是最传统、也是最稳定的方式。你需要下载与你的Nginx版本兼容的NAXSI源码在编译Nginx时通过--add-module参数指定NAXSI模块的路径。最终生成一个内置了NAXSI功能的Nginx二进制文件。这种方式性能最佳模块与Nginx结合最紧密但缺点是需要重新编译Nginx升级或更换模块比较麻烦。动态模块从Nginx 1.9.11开始支持动态加载模块。你可以单独编译NAXSI模块生成一个.so文件然后在Nginx的配置文件中使用load_module指令加载它。这种方式非常灵活无需重新编译主程序可以随时加载、卸载或更新模块非常适合使用包管理器安装的Nginx。目前这已成为主流的部署方式。注意选择动态模块时必须确保模块的编译环境如GCC版本、依赖库与当前运行的Nginx完全一致否则可能导致加载失败或运行时崩溃。通常使用系统包管理器如apt安装nginx后再用对应系统提供的工具如nginx-extras包或dh-nginx来编译动态模块是最稳妥的。在我们的指南中将主要基于动态模块的方式进行因为它更符合现代运维习惯。同时我也会给出静态编译的关键步骤供参考。3. 环境准备与NAXSI模块安装3.1 系统环境与Nginx基础假设我们在一台全新的Ubuntu 22.04 LTS服务器上操作。首先我们需要一个正常工作的Nginx。# 更新软件包列表并安装Nginx sudo apt update sudo apt install nginx -y # 验证Nginx安装及版本确保版本高于1.9.11以支持动态模块 nginx -v # 输出示例nginx version: nginx/1.18.0 (Ubuntu) # 启动Nginx并设置开机自启 sudo systemctl start nginx sudo systemctl enable nginx安装完成后通过浏览器访问服务器的IP地址应该能看到Nginx的默认欢迎页面。这证明了Nginx基础服务是正常的。记下Nginx的安装路径和配置文件路径通常配置文件在/etc/nginx/nginx.conf模块通常安装在/usr/lib/nginx/modules/。3.2 编译NAXSI动态模块我们将采用动态加载的方式。为此需要安装Nginx的编译环境和NAXSI源码。# 1. 安装编译所需的依赖 sudo apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev -y # 2. 安装用于构建动态模块的nginx包提供必要的头文件和构建系统 sudo apt install nginx-module-headers-more-filter nginx-common -y # 实际上我们需要的是nginx的源代码包来获取编译环境 sudo apt install nginx-dev -y # 如果系统没有nginx-dev可以安装nginx-full的源码或直接下载对应版本的nginx源码 # 更通用的方法是直接下载与已安装Nginx同版本的源码 NGINX_VERSION$(nginx -v 21 | awk -F/ {print $2}) apt source nginx$NGINX_VERSION # 这会下载并解压nginx源码包到当前目录 # 3. 下载NAXSI源码 cd /usr/src sudo git clone https://github.com/nbs-system/naxsi.git cd naxsi # 查看最新稳定版本例如我们使用 1.3版本 # git checkout 1.3接下来进行编译。关键是使用nginx -V命令查看当前运行Nginx的编译参数并在编译模块时使用完全相同的参数。# 获取当前Nginx的编译参数 nginx -V 21 | grep arguments # 输出很长包含 --prefix, --with-cc-opt 等我们需要这些信息。 # 进入NAXSI源码目录使用当前Nginx的配置进行编译 cd /usr/src/naxsi/naxsi_src # 假设你的nginx源码在 /usr/src/nginx-1.18.0 # 执行configure参数从上面 nginx -V 的输出里复制并加上 --add-dynamic-module sudo ./configure --with-compat --add-dynamic-module../naxsi_src $(nginx -V 21 | grep arguments | sed s/.*arguments: //) # --with-compat 选项对于动态模块的兼容性很重要。 # 编译模块不编译整个Nginx sudo make modules编译完成后在objs/目录下你会找到编译好的模块文件通常名为ngx_http_naxsi_module.so。将其复制到Nginx的标准模块目录。# 查找现有的模块目录 ls /usr/lib/nginx/modules/ # 或 /etc/nginx/modules/ # 复制编译好的模块 sudo cp objs/ngx_http_naxsi_module.so /usr/lib/nginx/modules/3.3 加载NAXSI模块与核心规则模块编译好后需要在Nginx的主配置文件中加载它并引入NAXSI的核心规则文件。编辑Nginx主配置文件/etc/nginx/nginx.conf在顶部events块之前添加加载指令# /etc/nginx/nginx.conf load_module modules/ngx_http_naxsi_module.so; user www-data; worker_processes auto; pid /run/nginx.pid; ...接下来需要NAXSI的核心规则文件naxsi_core.rules。这个文件包含了检测SQL注入、XSS等攻击的通用特征库。它通常在NAXSI源码的naxsi_config目录下。# 将核心规则文件复制到Nginx配置目录 sudo cp /usr/src/naxsi/naxsi_config/naxsi_core.rules /etc/nginx/现在基本的安装和加载就完成了。可以通过sudo nginx -t测试配置语法是否正确然后sudo systemctl reload nginx重新加载配置使模块生效。使用nginx -M命令可以查看已加载的模块确认naxsi_module在列表中。4. 五步配置实战从零搭建WAF4.1 第一步基础配置与学习模式启用首先我们为一个具体的站点例如/var/www/myapp配置NAXSI。假设我们的站点配置文件是/etc/nginx/sites-available/myapp。在server块中我们需要做以下几件事引入核心规则。定义NAXSI的开关和学习模式。设置拒绝请求时的处理方式DeniedUrl。# /etc/nginx/sites-available/myapp server { listen 80; server_name your_domain.com; root /var/www/myapp; index index.html index.htm; # 1. 引入NAXSI核心规则 include /etc/nginx/naxsi_core.rules; # 2. 启用NAXSI并设置学习模式 # SecRulesEnabled 全局开关ON启用。 # LearningMode ON开启学习模式只记录不拦截OFF关闭拦截。 # DeniedURL 请求被拒绝时重定向到的URL用于展示拦截页面。 # LibInjectionSql 启用LibInjection库进行SQLi检测更准确。 # LibInjectionXss 启用LibInjection库进行XSS检测。 location / { # 启用NAXSI规则检查 SecRulesEnabled; # 开启学习模式在生产环境前务必保持开启用于生成白名单。 LearningMode; # 定义被拒绝时访问的URL可以是一个简单的错误页面 DeniedURL /50x.html; # 启用增强检测引擎 LibInjectionSql; LibInjectionXss; # 检查模式0仅检测1检测并拦截与LearningMode冲突学习模式应设为0 SecRulesDisabled; # 在LearningMode下SecRulesDisabled应为0表示仅检测记录。 # 实际上LearningMode ON 会覆盖拦截行为所以这里设置不影响。 proxy_pass http://localhost:8080; # 假设后端是8080端口的应用 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 定义DeniedURL指向的错误页面位置 error_page 500 502 503 504 /50x.html; location /50x.html { root /usr/share/nginx/html; internal; # 标记为内部位置只能由Nginx内部重定向访问 } }实操心得DeniedURL最好设置一个独立的、简单的静态页面。不要把它指向后端应用因为如果拦截逻辑本身出现问题形成循环可能会导致Nginx崩溃。另外LearningMode是核心在初始阶段一定要打开并让业务流量跑一段时间至少覆盖所有主要功能点的测试这样才能收集到足够的日志来生成白名单。配置完成后执行sudo nginx -t sudo systemctl reload nginx。现在NAXSI已经在学习模式下运行了它会记录所有可疑请求但不会拦截。4.2 第二步分析日志与生成白名单学习模式运行一段时间后比如运行了完整的自动化测试套件或经过了一天的真实用户访问我们需要分析Nginx的错误日志来生成白名单。NAXSI的学习日志默认记录在Nginx的error_log中级别为notice。首先确保Nginx的错误日志级别包含notice通常默认是error需要调整。# 在nginx.conf的main上下文中修改 error_log /var/log/nginx/error.log notice;重载Nginx后触发一些“误报”。例如访问http://your_domain.com/search?qscriptalert(1)/script。然后查看错误日志sudo tail -f /var/log/nginx/error.log你会看到类似这样的条目2023-10-27 10:00:00 [notice] 12345#12345: *100 NAXSI_FMT: ip192.168.1.100serveryour_domain.comuri/searchlearning1total_processed48total_blocked0zone0ARGSid01302var_name0qcontent0scriptalert(1)/script, client: 192.168.1.100, server: your_domain.com, request: GET /search?qscriptalert(1)/script HTTP/1.1, host: your_domain.com关键字段解析learning1表示此条记录于学习模式。zone0ARGS触发规则的区域是参数ARGS。id01302触发的规则ID是1302对应XSS检测规则。var_name0q触发规则的变量名是q。content0...触发规则的具体内容。NAXSI提供了一个非常实用的Python脚本naxsi_sig位于源码的util目录下用于自动分析日志并生成白名单规则。cd /usr/src/naxsi/util # 分析错误日志生成白名单规则 sudo ./naxsi_sig -o /etc/nginx/naxsi_whitelist.rules -l /var/log/nginx/error.log -f这个命令会读取错误日志分析所有learning1的记录并将生成的候选白名单规则输出到/etc/nginx/naxsi_whitelist.rules文件中。-f参数表示“快速模式”它会为每个(zone, id, var_name)组合生成一条基础白名单。重要自动生成的规则是“候选”规则绝不能直接用于生产环境你必须人工审核每一条规则。规则格式如下BasicRule wl:1302 mz:$ARGS_VAR:q;这条规则的意思是白名单whitelist规则ID 1302作用于匹配区域match zone为$ARGS_VAR:q即名为q的URL参数的请求。这意味着对于参数q即使其值触发了规则1302XSS也予以放行。4.3 第三步精细化白名单规则编写与审核自动生成的规则往往过于宽泛。例如上面的规则wl:1302 “mz:$ARGS_VAR:q”;它允许参数q包含任何能触发1302规则的内容这可能会留下安全隐患。我们需要进行精细化调整。NAXSI的白名单规则语法非常强大主要涉及以下几个部分wl:ID1,ID2...: 白名单哪些规则ID。可以写多个如wl:1302,1301。mz:MATCH_ZONE: 规则匹配的区域。这是最关键的部分。$URL 整个URL。$ARGS_VAR:name 名为name的GET/POST参数。$BODY_VAR:name 名为name的POST参数。$HEADERS_VAR:name 名为name的请求头。$URL:pattern或$ARGS_VAR:name:pattern 可以与正则表达式结合进行更精确的匹配。s:SCORE 可选为此规则设置一个特定的分数而不是默认的规则分数较少用。精细化示例精确到URL路径我们只允许/search这个路径下的q参数触发1302规则。BasicRule wl:1302 mz:$URL:/search|$ARGS_VAR:q;使用正则表达式限制参数值如果我们知道q参数只能是数字可以进一步限制。BasicRule wl:1302 mz:$ARGS_VAR:q|^[0-9]$;注意正则表达式在NAXSI中性能开销较大应谨慎使用尤其避免复杂的回溯表达式。白名单多个规则如果某个合法请求同时触发了多个规则需要一起白名单。BasicRule wl:1302,1305,1399 mz:$BODY_VAR:content;全局白名单慎用有些规则可能误报率极高且不影响安全可以考虑全局白名单。例如规则1000可能检测某些无害的编码字符。BasicRule wl:1000;审核白名单规则时要反复问自己这条规则是否可能被攻击者滥用例如白名单一个用于搜索的q参数是常见的但白名单一个用于更新用户简介的bio参数包含script标签就非常危险。对于后一种情况应该考虑在后端应用层进行更严格的输入过滤和输出编码而不是在WAF层完全放行。将审核、修改后的安全白名单规则保存到/etc/nginx/naxsi_whitelist.rules文件中。4.4 第四步引入白名单并关闭学习模式白名单规则文件准备好后需要在站点的Nginx配置中引入它并关闭学习模式开启拦截。修改之前的站点配置文件server { listen 80; server_name your_domain.com; root /var/www/myapp; index index.html index.htm; include /etc/nginx/naxsi_core.rules; # 引入我们审核后的白名单规则 include /etc/nginx/naxsi_whitelist.rules; location / { SecRulesEnabled; # 关闭学习模式开启主动拦截 LearningMode Off; DeniedURL /50x.html; LibInjectionSql; LibInjectionXss; # 设置拦截模式。0只检测不拦截1检测并拦截。 SecRulesDisabled 0; # 现在设置为0但LearningMode Off且SecRulesEnabled时实际会拦截。 # 定义拦截阈值。当请求总分超过这个值时触发拦截。 # CheckRule $SQL 8 BLOCK; # CheckRule $RFI 8 BLOCK; # CheckRule $TRAVERSAL 5 BLOCK; # CheckRule $EVADE 5 BLOCK; # CheckRule $XSS 8 BLOCK; CheckRule $SQL 8 BLOCK; CheckRule $XSS 8 BLOCK; # 总异常分数阈值 CheckRule $TX 8 BLOCK; proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } error_page 500 502 503 504 /50x.html; location /50x.html { root /usr/share/nginx/html; internal; } }关键改动include /etc/nginx/naxsi_whitelist.rules; 引入白名单。LearningMode Off;至关重要关闭学习模式使NAXSI进入真正的防护状态。CheckRule指令 定义了各个攻击类别和总分的拦截阈值。当请求的异常分数达到这些阈值时请求将被BLOCK拦截并跳转到DeniedURL。阈值需要根据业务敏感度调整默认值如8是一个不错的起点。现在再次测试配置并重载Nginxsudo nginx -t sudo systemctl reload nginx4.5 第五步生产环境调优与监控配置上线后工作并未结束需要持续监控和调优。1. 日志监控 继续监控错误日志但此时关注的是learning0的拦截记录。这些是真正的攻击尝试。sudo grep -E \NAXSI_FMT.*learning0\ /var/log/nginx/error.log定期分析这些日志可以了解攻击趋势。如果发现大量针对某一特定漏洞如某个CVE的攻击而NAXSI核心规则库可能尚未覆盖你可能需要自定义规则。2. 自定义规则 NAXSI允许你编写自定义规则。在naxsi_core.rules同目录下创建naxsi_local.rules。# /etc/nginx/naxsi_local.rules # 示例定义一个检测特定恶意User-Agent的规则 MainRule str:evil-bot msg:Bad Bot Detected mz:$HEADERS_VAR:user-agent s:$BAD_BOT:8 id:10001;然后在主配置中include这个文件并在CheckRule里为$BAD_BOT设置阈值。自定义规则需要谨慎编写避免误报。3. 性能调优调整缓冲区如果应用有大的文件上传可能需要调整NAXSI的解析缓冲区大小在location中设置# naxsi_buffer_size 64k;取消注释并调整。优化白名单定期审查白名单合并冗余规则移除不再需要的规则。过于宽泛的白名单是性能和安全的风险点。压力测试使用ab或wrk工具对配置了NAXSI的站点进行压力测试与未配置时对比评估性能损耗通常在可接受范围内约5%-15%。4. 应急处理 如果上线后出现大量误报导致业务不可用快速回退的方法是临时在location中设置SecRulesDisabled 1;这将完全禁用NAXSI的检测和拦截。或者将LearningMode重新设为On并重载配置使其回到只记录不拦截的状态。同时立即分析错误日志修正白名单规则。5. 常见问题与排查技巧实录即使按照指南操作在实际部署中也可能遇到各种问题。这里记录一些典型场景和解决方法。5.1 模块加载失败问题sudo nginx -t报错module “/path/to/ngx_http_naxsi_module.so” is not binary compatible原因与解决这是动态模块最常见的问题。意味着编译模块时使用的Nginx版本、编译器选项或依赖库与当前运行的Nginx不兼容。确保版本一致使用nginx -v和编译时./configure的输出严格保证主版本号一致。最好使用从同一源码包编译出的Nginx主程序和模块。使用--with-compat编译模块时务必加上--with-compat选项。使用系统包管理器的工具最省心的办法是使用发行版提供的工具。例如在Ubuntu上可以安装nginx-extras包它已经包含了NAXSI模块。或者使用dh-nginx工具来编译与系统Nginx完全兼容的模块包。5.2 学习模式不记录日志问题配置了LearningMode On但访问恶意链接后error.log里没有NAXSI_FMT记录。排查步骤检查错误日志级别确认nginx.conf中error_log指令的级别是notice或更低如info、debug。error级别不会记录NAXSI的学习日志。检查配置作用域确认LearningMode指令是写在正确的location或server块中并且该块正在处理你的请求。检查请求是否命中确保你的测试请求确实命中了配置了NAXSI的location。可以通过在location里添加add_header X-Test “hit”;并查看响应头来验证。检查规则是否启用确认SecRulesEnabled;指令存在。LearningMode需要与SecRulesEnabled配合。5.3 生产模式误拦截正常请求问题关闭学习模式后某些正常的用户操作如提交包含特殊字符的表单被拦截。解决流程立即查看错误日志找到对应的拦截记录learning0记录下zone、id、var_name和content。临时切换回学习模式在对应location中将LearningMode改为On并重载Nginx。让该正常请求再发生一次此时它会被放行但日志中会生成一条learning1的记录。分析并更新白名单使用naxsi_sig工具分析新的日志或手动根据日志信息编写一条更精确的白名单规则。参考4.3节的规则编写方法。应用并测试将新规则添加到naxsi_whitelist.rules重载Nginx并将LearningMode改回Off测试请求是否正常通过。根本原因分析思考为什么这个合法请求会触发规则。是否是用户输入设计不合理是否可以在前端或后端进行规范化处理避免触发WAF规则这能减少对WAF白名单的依赖。5.4 性能瓶颈排查问题启用NAXSI后服务器负载明显升高响应变慢。排查方向检查白名单规则复杂度过多或过于复杂的正则表达式mz规则会显著增加CPU开销。使用top或htop观察Nginx工作进程的CPU使用率。尝试简化或合并白名单规则。调整缓冲区对于上传大量数据的请求默认缓冲区可能不够导致多次处理。可以适当增加# naxsi_buffer_size。限制检查范围对于已知安全的静态文件如图片、CSS、JS可以禁用NAXSI。location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { SecRulesDisabled; # 完全禁用NAXSI expires 1y; add_header Cache-Control public; }升级硬件或调整阈值如果攻击流量巨大可以考虑提升服务器资源或者微调CheckRule的阈值但后者会降低安全性需权衡。5.5 与其他Nginx模块的冲突问题NAXSI可能与某些Nginx模块特别是修改请求体的模块如ngx_http_lua_module的lua_need_request_body on存在执行顺序冲突。现象请求被错误拦截或模块功能异常。解决Nginx的处理阶段是固定的。NAXSI通常在NGX_HTTP_ACCESS_PHASE访问控制阶段执行。如果其他模块在此之前修改了请求体NAXSI检查的将是修改后的内容。你需要理解模块的执行顺序或者通过测试来验证。一个常见的做法是如果使用了Lua等复杂模块考虑将关键的安全检查放在应用层后端代码中NAXSI作为一道补充防线。部署NAXSI是一个“磨合”的过程尤其是白名单的打磨需要耐心和细致。它带来的安全增益是显著的——你不再依赖于一个可能过时的通用攻击特征库而是拥有一个为你的应用量身定制的、轻量且高效的防护层。当看到日志中那些被成功拦截的、五花八门的攻击尝试时你会觉得这一切的配置都是值得的。