Ubuntu 24.04 LTS 上编译集成 ModSecurity 3.x 与 Nginx 的完整实战指南

1. 项目概述：为什么要在Ubuntu 24.04 LTS上集成ModSecurity？

最近在加固一个线上Web服务，客户对安全的要求提到了一个新高度，光靠Nginx本身的配置和防火墙规则总觉得心里不踏实。于是，我决定把ModSecurity这个老牌的开源Web应用防火墙（WAF）给整上，让它和Nginx深度绑定，给应用再加一道“安检门”。选择Ubuntu 24.04 LTS作为基础，主要是看中了它的长期支持特性和相对较新的软件包库，能减少一些依赖冲突的麻烦。这个组合，说白了，就是给跑在Nginx上的网站或API接口，装上了一个可以自定义规则的“行为分析仪”，能实时拦截SQL注入、跨站脚本（XSS）、路径遍历等常见Web攻击。

你可能听过云WAF，但自己部署ModSecurity，最大的好处就是数据完全自主可控，规则可以量身定制，并且没有额外的服务费用。对于有一定运维能力的中小团队或个人项目来说，这是一次性价比极高的安全投资。整个过程涉及系统环境准备、Nginx编译、ModSecurity模块集成、核心规则集加载以及最终的策略调优，我会把每一步的细节、踩过的坑和优化心得都摊开来讲清楚。无论你是刚接触Linux服务部署的新手，还是想深化安全实践的老手，这篇从零到一的实战记录都能给你提供一条清晰的路径。

2. 环境准备与依赖梳理

在开始编译和集成之前，一个干净、稳定的基础环境至关重要。Ubuntu 24.04 LTS刚刚发布不久，其自带的软件源为我们提供了比较新的开发工具链。

2.1 系统更新与基础工具安装

首先，确保你的系统是最新的。通过SSH连接到你的Ubuntu服务器，执行标准的更新升级操作。

sudo apt update sudo apt upgrade -y

升级完成后，安装后续编译所需的各类开发工具和库。这里面的包很多，但每一个都有其作用：

• build-essential: 包含GCC、G++、make等核心编译工具。
• libpcre3-dev: PCRE库的开发文件，Nginx用于处理正则表达式。
• libssl-dev: OpenSSL库的开发文件，提供HTTPS支持。
• zlib1g-dev: 用于Gzip压缩。
• libxml2-dev和libcurl4-openssl-dev: 这是ModSecurity 3.x（我们即将安装的版本）所依赖的，用于解析XML和发起HTTP请求（例如，向规则管理服务器发送心跳或日志）。
• git、wget、vim: 方便我们获取源码和编辑文件。

一次性安装它们：

sudo apt install -y build-essential libpcre3-dev libssl-dev zlib1g-dev \ libxml2-dev libcurl4-openssl-dev git wget vim

2.2 获取Nginx与ModSecurity源码

我们不直接使用apt安装Nginx，因为默认仓库中的Nginx不包含我们需要的--add-dynamic-module编译选项来集成第三方模块。因此，我们需要从官网下载源码进行编译。

选择一个合适的目录，例如/usr/local/src，然后开始操作：

cd /usr/local/src # 下载Nginx稳定版源码，以1.24.0为例（请检查官网获取最新稳定版） sudo wget http://nginx.org/download/nginx-1.24.0.tar.gz sudo tar -zxvf nginx-1.24.0.tar.gz

接下来，获取ModSecurity 3.x的源码。ModSecurity 3.x是一个“连接器”架构，它本身是一个库（libmodsecurity），然后为不同的Web服务器（如Nginx、Apache）提供连接器模块。我们需要的是modsecurity-nginx连接器。

# 克隆ModSecurity 3的主库（libmodsecurity） sudo git clone --depth 1 https://github.com/owasp-modsecurity/ModSecurity # 进入目录并切换稳定分支，v3/master相对稳定 cd ModSecurity sudo git submodule init sudo git submodule update # 返回上级目录，克隆Nginx连接器 cd /usr/local/src sudo git clone --depth 1 https://github.com/owasp-modsecurity/modsecurity-nginx.git

注意：git submodule这一步很关键，因为ModSecurity依赖一些子模块（如YAJL、LMDB等）。如果跳过，后续的./configure会失败。

3. 编译与集成Nginx与ModSecurity

这是整个部署的核心环节，步骤虽多，但按顺序操作成功率很高。

3.1 编译libmodsecurity库

首先，我们需要先编译和安装ModSecurity的核心库。

cd /usr/local/src/ModSecurity # 运行构建配置脚本 ./build.sh # 配置编译选项。--prefix指定安装目录，这里我们安装到/usr/local/modsecurity ./configure --prefix=/usr/local/modsecurity

运行./configure时，请留意输出结尾，确保没有显示“missing”或“no”的关键依赖错误。如果一切正常，就可以开始编译了。

# 使用make进行编译，-j$(nproc)表示使用所有CPU核心加速编译 sudo make -j$(nproc) # 安装库文件到指定前缀目录 sudo make install

安装完成后，重要的文件（如libmodsecurity.so）会被放置到/usr/local/modsecurity/lib/下。我们需要让系统知道这个库的位置。

# 创建动态链接库配置文件 echo "/usr/local/modsecurity/lib" | sudo tee /etc/ld.so.conf.d/modsecurity.conf # 更新动态链接库缓存 sudo ldconfig

3.2 编译集成ModSecurity模块的Nginx

现在，我们进入Nginx源码目录，将modsecurity-nginx连接器模块以动态模块的形式编译进去。

cd /usr/local/src/nginx-1.24.0

在配置编译选项时，有几个关键点：

• --add-dynamic-module：指定我们外部的Nginx模块源码路径，这里是/usr/local/src/modsecurity-nginx。这会将模块编译成独立的.so文件，而不是直接嵌入Nginx二进制文件，灵活性更高。
• --with-compat：这个选项对于动态模块的兼容性非常重要，务必加上。
• --with-http_ssl_module和--with-http_v2_module：为现代Web服务启用SSL和HTTP/2支持。
• --prefix：指定Nginx的安装目录。

执行configure命令：

./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=/usr/local/src/modsecurity-nginx

配置成功后，输出会显示一大堆“adding module”的信息，并最终汇总出将要构建的模块列表。确认modsecurity-nginx模块在列表中。

接着进行编译：

sudo make -j$(nproc)

编译完成后，先不要执行make install。因为如果系统里已经有Nginx，直接安装会覆盖。我们首先获取编译好的动态模块文件。

# 查看编译出的模块文件，应该能看到 objs/ngx_http_modsecurity_module.so ls objs/*.so

接下来，安装Nginx到指定目录：

sudo make install

安装完成后，将我们编译好的ModSecurity动态模块文件复制到Nginx的标准模块目录中：

sudo cp objs/ngx_http_modsecurity_module.so /usr/local/nginx/modules/

3.3 配置系统服务与验证安装

为了方便管理，我们为Nginx创建一个systemd服务文件。

sudo vim /etc/systemd/system/nginx.service

将以下内容写入文件：

[Unit] Description=The nginx HTTP and reverse proxy server After=network.target [Service] Type=forking PIDFile=/usr/local/nginx/logs/nginx.pid ExecStartPre=/usr/local/nginx/sbin/nginx -t ExecStart=/usr/local/nginx/sbin/nginx ExecReload=/usr/local/nginx/sbin/nginx -s reload ExecStop=/bin/kill -s QUIT $MAINPID PrivateTmp=true [Install] WantedBy=multi-user.target

保存退出后，重新加载systemd并启动Nginx：

sudo systemctl daemon-reload sudo systemctl start nginx sudo systemctl enable nginx

检查Nginx是否成功加载了ModSecurity模块：

/usr/local/nginx/sbin/nginx -V 2>&1 | grep -o modsecurity

如果输出中包含modsecurity，则说明模块编译成功。再检查服务状态和监听端口：

sudo systemctl status nginx sudo netstat -tlnp | grep :80

4. ModSecurity核心规则集配置与加载

光有引擎还不够，我们需要为引擎提供“行为判断手册”，这就是规则集。OWASP ModSecurity核心规则集（CRS）是最权威、最常用的免费规则集。

4.1 下载与部署OWASP核心规则集（CRS）

我们将在Nginx的配置目录下创建一个专门的结构来存放ModSecurity的配置和规则。

# 创建ModSecurity专用目录 sudo mkdir -p /usr/local/nginx/conf/modsecurity cd /usr/local/nginx/conf/modsecurity # 下载最新的OWASP CRS稳定版 sudo git clone --depth 1 -b v3.3/master https://github.com/coreruleset/coreruleset.git owasp-modsecurity-crs

接下来，我们需要ModSecurity的主配置文件modsecurity.conf和默认的排除规则文件crs-setup.conf。它们通常位于ModSecurity源码的unicode.mapping和CRS目录中。

# 复制主配置文件 sudo cp /usr/local/src/ModSecurity/modsecurity.conf-recommended /usr/local/nginx/conf/modsecurity/modsecurity.conf # 复制CRS配置文件 sudo cp /usr/local/nginx/conf/modsecurity/owasp-modsecurity-crs/crs-setup.conf.example /usr/local/nginx/conf/modsecurity/crs-setup.conf

4.2 关键配置文件详解与调优

现在我们来修改这几个核心配置文件，让ModSecurity按照我们的意愿工作。

首先，编辑主配置文件modsecurity.conf：

sudo vim /usr/local/nginx/conf/modsecurity/modsecurity.conf

找到并修改以下几个关键参数：

• SecRuleEngine：这是引擎模式开关。初始阶段建议设置为DetectionOnly，即只记录日志不拦截，用于观察和测试。正式上线后可改为On。

  SecRuleEngine DetectionOnly

• SecAuditLog：审计日志路径，记录所有触发的规则详情。

  SecAuditLog /usr/local/nginx/logs/modsec_audit.log

• SecAuditLogType和SecAuditLogStorageDir：为了性能，我们使用并发模式（Concurrent）并指定日志目录。

  SecAuditLogType Concurrent SecAuditLogStorageDir /usr/local/nginx/logs/modsec_audit

• SecDebugLog和SecDebugLogLevel：调试日志，初期排查问题时可以打开（如级别设为9），正常运行时建议关闭（设为0）。

  SecDebugLog /usr/local/nginx/logs/modsec_debug.log SecDebugLogLevel 0

然后，编辑CRS配置文件crs-setup.conf。这个文件用于配置CRS的全局行为，比如要启用哪些规则集、设置异常分数阈值等。

sudo vim /usr/local/nginx/conf/modsecurity/crs-setup.conf

你需要关注的部分：

• 在文件靠前的位置，取消注释（删除行首的#）以启用tx（事务变量）相关配置。
• 找到SecAction部分，它定义了默认动作和异常分数。默认的拦截分数是5。你可以根据自己应用的容忍度调整blocking_paranoia_level（通常从1开始，越高越严格，但也可能误报越多）。
• 确保规则文件包含的路径正确。通常，CRS的规则位于owasp-modsecurity-crs/rules/目录下，配置文件末尾会通过Include指令引入。

4.3 在Nginx中启用ModSecurity模块

最后一步，是在Nginx的配置文件中加载模块并指定ModSecurity的配置文件。

编辑Nginx的主配置文件：

sudo vim /usr/local/nginx/conf/nginx.conf

在http { }块内的顶部（通常在events块之后），添加以下两行来加载动态模块：

load_module modules/ngx_http_modsecurity_module.so; modsecurity on; modsecurity_rules_file /usr/local/nginx/conf/modsecurity/modsecurity.conf;

接下来，在你需要保护的server块（虚拟主机）中，启用ModSecurity并指定规则文件。例如：

server { listen 80; server_name your_domain.com; modsecurity on; modsecurity_rules_file /usr/local/nginx/conf/modsecurity/modsecurity.conf; location / { root /usr/local/nginx/html; index index.html; } }

重要提示：modsecurity_rules_file指令可以同时在http块和server块中设置。在http块中设置的是全局默认规则文件。在server或location块中再次设置，可以覆盖全局配置，实现更精细化的规则控制。

配置完成后，务必测试配置语法并重载Nginx：

sudo /usr/local/nginx/sbin/nginx -t sudo systemctl reload nginx

5. 功能验证、问题排查与性能调优

部署完成后，不能假设一切正常，必须进行系统性的验证和测试。

5.1 基础功能验证与攻击模拟测试

首先，检查ModSecurity是否正常运行并加载了规则。查看Nginx的错误日志和ModSecurity的审计日志：

sudo tail -f /usr/local/nginx/logs/error.log # 另一个终端查看审计日志 sudo tail -f /usr/local/nginx/logs/modsec_audit.log

然后，进行简单的攻击测试。由于我们目前处于DetectionOnly模式，攻击不会被拦截，但会被记录。

1. SQL注入测试：在浏览器或使用curl访问你的网站，并在URL后附加一个典型的测试载荷。

   curl "http://your_server_ip/?id=1' OR '1'='1"

2. XSS测试：

   curl "http://your_server_ip/?q=<script>alert('test')</script>"

执行后，立即去查看modsec_audit.log文件。如果你看到类似以下内容，说明ModSecurity成功检测到了攻击并记录了日志（但未阻断）：

--abcd1234-A-- [timestamp] /?id=1' OR '1'='1 --abcd1234-B-- ... --abcd1234-H-- Message: Warning. detected SQLi using libinjection. [file "/usr/local/nginx/conf/modsecurity/owasp-modsecurity-crs/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf"] [line "55"] [id "942100"] ...

5.2 常见问题排查实录

在实际部署中，你几乎一定会遇到一些问题。以下是我踩过的一些坑和解决方法：

问题1：Nginx启动失败，错误日志显示“modsecurity_rules_file” directive is not allowed here

• 原因：modsecurity_rules_file指令被放在了错误的配置层级。它不能放在http块之外，或者在某些不支持该指令的上下文中。
• 解决：确保modsecurity_rules_file指令只出现在http、server或location块内。最稳妥的做法是放在http块内（全局生效）或需要保护的特定server块内。

问题2：审计日志目录权限错误，日志无法写入。

• 原因：Nginx工作进程（通常是www-data或nginx用户）对/usr/local/nginx/logs/modsec_audit目录没有写权限。
• 解决：

  sudo mkdir -p /usr/local/nginx/logs/modsec_audit sudo chown -R www-data:www-data /usr/local/nginx/logs/modsec_audit # 或者，如果你的Nginx用户是nginx # sudo chown -R nginx:nginx /usr/local/nginx/logs/modsec_audit

问题3：规则误报（False Positive）太多，阻塞了正常业务。

• 原因：CRS的某些规则可能过于严格，与你应用的正常行为模式冲突。
• 解决：这是WAF调优的常态。不要轻易关闭整个规则。步骤是：
  1. 在审计日志中找到误报事件的唯一id（例如942100）和msg。
  2. 在对应的规则文件（如REQUEST-942-APPLICATION-ATTACK-SQLI.conf）中找到该规则。
  3. 使用ModSecurity的SecRuleRemoveById指令在配置中禁用单条规则（在http或server块中），或者更精细地，使用SecRuleUpdateTargetById修改规则的检查目标。最佳实践是在modsecurity.conf或单独的自定义规则文件中创建排除规则。

问题4：性能明显下降，服务器负载升高。

• 原因：ModSecurity的规则检查是CPU密集型操作，特别是启用了复杂的正则表达式和链式规则时。
• 解决：
  • 调整SecRequestBodyLimit和SecRequestBodyNoFilesLimit：限制检查的请求体大小，避免因上传大文件导致引擎过载。
  • 启用SecAuditLogType Concurrent：如我们之前所做，使用并发审计日志，避免磁盘I/O阻塞。
  • 优化规则集：在crs-setup.conf中，可以调整paranoia_level（从1开始），级别越高规则越严格但性能开销越大。对于生产环境，PL2是一个比较平衡的选择。
  • 考虑硬件或架构升级：对于高流量站点，可能需要更强大的CPU，或者考虑将WAF功能卸载到专门的硬件设备或云服务。

5.3 从检测模式切换到防护模式

经过一段时间的观察（建议至少一个完整的业务周期），确认规则误报在可接受范围内，且日志记录正常后，就可以正式开启防护了。

编辑modsecurity.conf文件：

sudo vim /usr/local/nginx/conf/modsecurity/modsecurity.conf

将SecRuleEngine的值从DetectionOnly改为On。

SecRuleEngine On

再次测试配置并重载Nginx：

sudo /usr/local/nginx/sbin/nginx -t sudo systemctl reload nginx

此时，再执行之前的攻击测试命令，你应该会收到一个403 Forbidden的错误页面，并且在审计日志中可以看到Intercepted（已拦截）的动作。这标志着你的ModSecurity WAF已经正式上线运行，主动保护你的Web应用。

整个部署过程从系统准备到最终上线，涉及编译、配置、调优多个环节，任何一个步骤的疏忽都可能导致失败。我的经验是，一定要善用日志（Nginx的error.log和ModSecurity的modsec_audit.log），它们是指引你排除故障最可靠的灯塔。对于规则调优，要有耐心，它是一个持续的过程，需要结合业务流量和安全日志不断磨合。