owasp-modsecurity/ModSecurity-nginx
GitHub: owasp-modsecurity/ModSecurity-nginx
ModSecurity v3 的 Nginx 连接器模块，为 Nginx 与 libmodsecurity 之间提供通信通道以启用 Web 应用防火墙功能。
Stars: 1840 | Forks: 307
[](https://travis-ci.org/SpiderLabs/ModSecurity-nginx)
[](https://zenhub.com)
ModSecurity-nginx connector 是 nginx 与 libmodsecurity (ModSecurity v3) 之间的连接点。换言之，这个项目提供了 nginx 和 libmodsecurity 之间的通信通道。在 nginx 中使用 LibModSecurity 必须需要此 connector。
ModSecurity-nginx connector 采用了 nginx 模块的形式。该模块仅作为 nginx 与 ModSecurity 之间的通信层。
请注意，该项目依赖于 libmodsecurity，而不是 ModSecurity（2.9 及以下版本）。
### 这个项目与旧的 nginx ModSecurity 插件有什么区别？
旧版本使用 ModSecurity 独立版，它是一个封装了
Apache 内部结构以将 ModSecurity 链接到 nginx 的包装器。当前版本更贴近
nginx，使用了不再依赖于
Apache 的新版 libmodsecurity。因此，当前版本依赖更少、bug 更少且速度更快。此外，还提供了一些新功能——例如支持使用全局规则配置，并允许按目录/location 进行自定义（例如 SecRuleRemoveById）。
# 编译
在编译此软件之前，请确保您已安装 libmodsecurity。
您可以从 [ModSecurity git 仓库](https://github.com/SpiderLabs/ModSecurity) 下载它。有关 libmodsecurity 编译和安装的信息，请查阅随附的文档。
安装好 libmodsecurity 后，您就可以继续安装 ModSecurity-nginx connector 了，该过程遵循 nginx 第三方模块的安装步骤。在 nginx 源码目录中执行：
```
./configure --add-module=/path/to/ModSecurity-nginx
```
或者，构建一个动态模块：
```
./configure --add-dynamic-module=/path/to/ModSecurity-nginx --with-compat
```
请注意，在构建动态模块时，您的 nginx 源码版本
需要与您为其编译的 nginx 版本相匹配。
有关 nginx 第三方插件支持的更多信息，请访问[这里](https://www.f5.com/company/blog/nginx/compiling-dynamic-modules-nginx-plus)。
# 用法
用于 nginx 的 ModSecurity 扩展了您的 nginx 配置指令。
它添加了四个新指令，分别是：
## modsecurity
**语法:** *modsecurity on | off*
**上下文:** *http, server, location*
**默认值:** *off*
开启或关闭 ModSecurity 功能。
请注意，此配置指令不再与 SecRule 的状态相关。
相反，它现在仅作为 nginx 的标志，用于启用或禁用该模块。
## modsecurity_rules_file
**语法:** *modsecurity_rules_file <规则文件路径>*
**上下文:** *http, server, location*
**默认值:** *无*
指定 modsecurity 配置文件的位置，例如：
```
server {
modsecurity on;
location / {
root /var/www/html;
modsecurity_rules_file /etc/my_modsecurity_rules.conf;
}
}
```
## modsecurity_rules_remote
**语法:** *modsecurity_rules_remote <密钥> <规则 URL>*
**上下文:** *http, server, location*
**默认值:** *无*
指定从互联网上的何处下载 modsecurity 配置文件。
它还指定了用于向该服务器进行身份验证的密钥：
```
server {
modsecurity on;
location / {
root /var/www/html;
modsecurity_rules_remote my-server-key https://my-own-server/rules/download;
}
}
```
## modsecurity_rules
**语法:** *modsecurity_rules <modsecurity 规则>*
**上下文:** *http, server, location*
**默认值:** *无*
允许将 ModSecurity 规则直接包含在 nginx 配置中。
以下示例从文件中加载规则，并按目录/alias 注入特定的配置：
```
server {
modsecurity on;
location / {
root /var/www/html;
modsecurity_rules_file /etc/my_modsecurity_rules.conf;
}
location /ops {
root /var/www/html/opts;
modsecurity_rules '
SecRuleEngine On
SecDebugLog /tmp/modsec_debug.log
SecDebugLogLevel 9
SecRuleRemoveById 10
';
}
}
```
## modsecurity_transaction_id
**语法:** *modsecurity_transaction_id string*
**上下文:** *http, server, location*
**默认值:** *无*
允许从 nginx 传递 transaction ID，而不是在库中生成它。
这对于追踪目的非常有用，例如参考以下配置：
```
log_format extended '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" $request_id';
server {
server_name host1;
modsecurity on;
modsecurity_transaction_id "host1-$request_id";
access_log logs/host1-access.log extended;
error_log logs/host1-error.log;
location / {
...
}
}
server {
server_name host2;
modsecurity on;
modsecurity_transaction_id "host2-$request_id";
access_log logs/host2-access.log extended;
error_log logs/host2-error.log;
location / {
...
}
}
```
结合使用 log_format 和 modsecurity_transaction_id，您将
能够通过相同的唯一标识符，在 access log 和 error log 条目之间找到相关性。
该字符串可以包含变量。
## modsecurity_use_error_log
**语法:** *modsecurity_use_error_log on | off*
**上下文:** *http, server, location*
**默认值:** *on*
开启或关闭 ModSecurity 的 error log 功能。
## 功能请求
我们非常乐意听取您关于新功能的任何想法。请记住，这是一个社区驱动的项目，因此请务必先通过邮件列表联系社区以获取反馈。或者，
随时可以在 GitHub 上提出请求新功能的 issue。在创建新 issue 之前，请检查是否已有针对所需功能的请求。
## 打包
我们非常希望我们的软件包能及时进入各个发行版。如果
有任何事情可以方便您作为打包人员的工作，请告诉我们。标签：AppImage, Nginx模块, WAF, Web应用防火墙, 反向代理, 安全防护, 网络通信