owasp-modsecurity/ModSecurity
GitHub: owasp-modsecurity/ModSecurity
ModSecurity 是一个开源跨平台的 Web 应用防火墙引擎，提供基于规则的 HTTP 流量监控、攻击防护与实时分析能力。
Stars: 9650 | Forks: 1729
[](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)
[](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)
[](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)
[](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)
[](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity)
Libmodsecurity 是 ModSecurity v3 项目的一个组成部分。该库的代码库作为 ModSecurity 连接器（Connectors）的接口，负责接收网络流量并应用传统的 ModSecurity 处理。通常，它提供加载/解释以 ModSecurity SecRules 格式编写的规则，并通过连接器将规则应用于您的应用程序提供的 HTTP 内容。
如果您正在寻找适用于 Apache 的 ModSecurity（即 ModSecurity v2.x），它仍处于维护状态，可在此处获取：[此处](https://github.com/owasp-modsecurity/ModSecurity/tree/v2/master)。
### 本项目与旧版 ModSecurity（v2.x.x）有何区别？
* 所有 Apache 依赖项已被移除
* 更高的性能
* 新功能
* 新架构
Libmodsecurity 是 ModSecurity 平台的完全重写。最初的 ModSecurity 项目仅作为一个 Apache 模块启动。随着时间的推移，由于广泛需求，该项目被扩展以支持其他平台，包括（但不限于）Nginx 和 IIS。为了满足对更多平台支持日益增长的需求，有必要移除该项目底层的 Apache 依赖项，使其更加独立于平台。
作为这一目标的结果，我们重新设计了 Libmodsecurity，使其不再依赖于 Apache Web 服务器（无论在编译时还是运行时）。产生的一个附带效果是，在所有平台上用户都可以期待更高的性能。此外，我们借此机会为一些用户长期寻求的新功能奠定了基础。例如，我们计划在未来版本中原生支持 JSON 格式的审计日志，以及其他一系列功能。
### 它不再仅仅是一个模块。
'ModSecurity' 分支不再包含传统上打包在一起的模块逻辑（针对 Nginx、Apache 和 IIS）。相反，该分支仅包含此项目的库部分（libmodsecurity）。该库被我们称为'连接器'（Connectors）的组件使用，这些连接器会与您的 Web 服务器交互，并以一种库能理解的通用格式提供数据。每个连接器都作为一个独立的 GitHub 项目进行维护。例如，Nginx 连接器由 ModSecurity-nginx 项目提供（https://github.com/owasp-modsecurity/ModSecurity-nginx）。
将这些连接器分开维护，可以使每个项目拥有不同的发布周期、问题和开发树。此外，这意味着当您安装 ModSecurity v3 时，只会获得您需要的部分，而不会包含您不会用到的额外内容。
# 编译
在开始编译过程之前，请确保所有必需的依赖项都已安装。
有关更多信息，请参阅[依赖项](#dependencies)和[Git 子模块](#Git-submodules)部分。
编译后，请确保您的构建/平台上没有问题。
我们强烈建议运行单元测试和回归测试。这些测试工具位于 [`tests/`](#testing-your-patch) 子文件夹中。
作为一个动态库，`libmodsecurity` 必须安装在操作系统可以找到动态库的位置。
### Unix（Linux、macOS、FreeBSD 等）
在类 Unix 系统上，项目使用 autotools 进行编译过程。
如果您使用的是 Git 检出版本，请确保递归克隆仓库或在构建前初始化所有子模块。
另请参阅[Git 子模块](#git-submodules)部分。
```
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
```
此仓库使用 git 子模块。克隆后，请确保初始化并获取所有子模块：
```
git submodule update --init --recursive
```
您可以通过以下命令验证所有子模块是否已正确初始化：
```
git submodule status
```
正确初始化的子模块会显示一个提交哈希。
开头的 `-` 表示该子模块尚未初始化。
然后您可以开始构建过程：
```
./build.sh
./configure
make
sudo make install
```
有关特定于发行版的构建的详细信息，请参阅我们的 Wiki：
[编译指南](https://github.com/owasp-modsecurity/ModSecurity/wiki/Compilation-recipes)
### Windows
Windows 构建信息可在[此处](build/win32/README.md)找到。
## 依赖项
* 本库使用 C++ 编写，采用 C++17 标准。
* 它使用 Flex 和 Bison（Yacc）生成“Sec 规则语言”解析器。
* 强制依赖项包括 YAJL，因为 ModSecurity 使用 JSON 进行日志记录和测试框架。
* libXML2（可选）用于解析 XML 请求。
### 正则表达式引擎（PCRE2 / PCRE）
* SecRules 中的正则表达式处理通过 `Regex` 工具（`src/utils/regex.*`）实现。
* 默认情况下，ModSecurity 使用 **PCRE2** 进行正则表达式处理。
* 它被诸如 `@rx`、`@rxGlobal` 和 `@verifyCC` 等操作符使用。
* 构建时的行为：
* **默认：** 检测并使用 PCRE2。
* **回退：** 如果明确提供 `--with-pcre`（`WITH_PCRE`），则可以使用旧版 PCRE。
* 换句话说，除非明确配置为其他方式，否则当前构建期望使用 PCRE2。
所有其他依赖项与 SecRules 中指定的操作符或配置指令相关，可能不是编译所必需的。
### 操作符相关依赖项
* `libinjection` 是 `@detectXSS` 和 `@detectSQL` 操作符所必需的。
* `curl` 是 `SecRemoteRules` 指令所必需的。
如果缺少这些库，ModSecurity 将在没有相应操作符或指令支持的情况下编译。
### Git 子模块
仓库包含以下子模块：
* `others/libinjection` – 由 `@detectSQLi` 和 `@detectXSS` 操作符使用。
* `others/mbedtls`（TF-PSA-Crypto 子集）– 用于加密函数和辅助工具（例如哈希、base64）。
**注意：** 较新的 mbedTLS v4 布局与较旧的 v3 不兼容。
内部结构发生了重大变化，许多组件已移到子模块中（例如 TF-PSA-Crypto）。
合并 PR #3532 后，需要运行：
git submodule update --init --recursive
这确保获取所有必需的子模块。如果没有此步骤，项目将无法成功构建。
您可以通过以下命令验证所有子模块是否已正确初始化：
git submodule status
示例输出：
bc625d5... bindings/python
2117822... others/libinjection (v4.0.0)
0fe989b... others/mbedtls (v4.1.0)
a3d4405... test/test-cases/secrules-language-tests
如果缺少子模块，将显示为以 `-` 开头的行，例如：
-bc625d5... bindings/python
开头的 `-` 表示该子模块尚未初始化或获取。
* `test/test-cases/secrules-language-tests` – 由 `make check` 使用的共享 SecRules 一致性及回归测试套件。
* `bindings/python` – ModSecurity 的 Python 绑定（核心库编译不需要）。
`others/libinjection` 和 `others/mbedtls` 实际上是源码构建所必需的，必须在构建前初始化。
### 可选的外部依赖项
几个外部库是可选的，可以启用附加功能，包括：
* `libcurl` – 用于 `SecRemoteRules`
* LMDB – 持久化存储支持
* Lua – 脚本支持
* XML 库 – 扩展的 XML 处理
* **GeoIP（旧版）/ MaxMind**
旧版 **GeoIP C API**（libGeoIP）已被 MaxMind **弃用且不再维护**。
上游仓库已归档，不应用于新部署。
相反，ModSecurity 支持现代且积极维护的 **MaxMind DB API（libmaxminddb）**。
在配置过程中，您可能会看到类似这样的内容：
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
这表明正在使用 **libmaxminddb**（推荐）。
强烈建议使用 MaxMind DB 而不是旧版 GeoIP 库。
# 库文档
库文档采用 Doxygen 格式编写在代码中。要生成此文档，请使用位于 `doc/` 子文件夹中的配置文件 `doxygen.cfg` 运行 doxygen 工具。这将生成 HTML 格式的文档，包含使用示例。
# 库利用
本库提供 C++ 和 C 接口。目前某些功能仅通过 C++ 接口提供，例如创建自定义日志记录机制的能力（请参阅回归测试以了解这些日志机制的工作方式）。
目标是使两种 API（C、C++）提供相同的功能，如果您发现某个 API 方面在特定接口中缺失，请提出问题。
在 examples 子文件夹中，有简单的 API 使用示例。
下面说明了一些示例：
### 使用 C++ 的简单示例
```
using ModSecurity::ModSecurity;
using ModSecurity::Rules;
using ModSecurity::Transaction;
ModSecurity *modsec;
ModSecurity::Rules *rules;
modsec = new ModSecurity();
rules = new Rules();
rules->loadFromUri(rules_file);
Transaction *modsecTransaction = new Transaction(modsec, rules);
modsecTransaction->processConnection("127.0.0.1");
if (modsecTransaction->intervention()) {
std::cout << "There is an intervention" << std::endl;
}
```
### 使用 C 的简单示例
```
#include "modsecurity/modsecurity.h"
#include "modsecurity/transaction.h"
char main_rule_uri[] = "basic_rules.conf";
int main (int argc, char **argv)
{
ModSecurity *modsec = NULL;
Transaction *transaction = NULL;
Rules *rules = NULL;
modsec = msc_init();
rules = msc_create_rules_set();
msc_rules_add_file(rules, main_rule_uri);
transaction = msc_new_transaction(modsec, rules);
msc_process_connection(transaction, "127.0.0.1");
msc_process_uri(transaction, "http://www.modsecurity.org/test?key1=value1&key2=value2&key3=value3&test=args&test=test");
msc_process_request_headers(transaction);
msc_process_request_body(transaction);
msc_process_response_headers(transaction);
msc_process_response_body(transaction);
return 0;
}
```
### 调试
在开始调试过程之前，请确定您的 bug 所在。问题可能出现在您的连接器中，也可能出现在 libmodsecurity 中。为了确定 bug 的位置，建议您开发一个模拟 bug 发生场景的回归测试。如果 bug 可以通过回归测试工具重现，那么调试将简单得多，并且可以确保它不再发生。在 Linux 上，建议任何进行调试的人根据需要使用 gdb 和/或 valgrind。
在配置/编译期间，您可能希望禁用编译器优化，使“回溯”包含可读的数据。使用 CFLAGS 禁用编译优化参数：
```
$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install
```
"断言使我们能够记录假设并在开发过程中尽早发现违规行为。更重要的是，断言使我们能够以最少的努力发现违规行为。" https://dl.acm.org/doi/pdf/10.1145/240964.240969
建议在适用的地方使用断言，并在测试和调试工作流程中使用 `--enable-assertions=yes` 启用它们。
### 基准测试
源码树包含一个 Benchmark 工具，可以帮助衡量库的性能。该工具位于 `test/benchmark/` 目录中。构建过程也会在此处生成二进制文件，因此编译完成后您将拥有该工具。
要运行，只需输入：
```
cd test/benchmark
$ ./benchmark
Doing 1000000 transactions...
```
您也可以传递一个较低的值：
```
$ ./benchmark 1000
Doing 1000 transactions...
```
要测量时间：
```
$ time ./benchmark 1000
Doing 1000 transactions...
real 0m0.351s
user 0m0.337s
sys 0m0.022s
```
这非常快，因为基准测试使用了最小的 `modsecurity.conf.default` 配置，其中不包含太多规则：
```
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
```
要使用真实规则进行测量，请运行同一目录中的一个下载脚本：
```
$ ./download-owasp-v3-rules.sh
Cloning into 'owasp-v3'...
remote: Enumerating objects: 33007, done.
remote: Counting objects: 100% (2581/2581), done.
remote: Compressing objects: 100% (907/907), done.
remote: Total 33007 (delta 2151), reused 2004 (delta 1638), pack-reused 30426
Receiving objects: 100% (33007/33007), 9.02 MiB | 16.21 MiB/s, done.
Resolving deltas: 100% (25927/25927), done.
Switched to a new branch 'tag3.0.2'
/path/to/ModSecurity/test/benchmark
Done.
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
Include "owasp-v3/crs-setup.conf.example"
Include "owasp-v3/rules/*.conf"
```
现在该命令将给出更高的值。
#### 基准测试的工作原理
该工具是一个简单的包装应用程序，它使用库。它创建一个 ModSecurity 实例和一个 RuleSet 实例，然后根据指定数量运行一个循环。在此循环内，它创建一个 Transaction 对象来模拟真实的 HTTP 事务。
每个事务都是一个 HTTP/1.1 GET 请求，带有一些 GET 参数。添加了常见的头部，然后是响应头部和 XML 主体。在各个阶段之间，工具会检查是否发生了干预。所有事务都使用相同的数据创建。
请注意，该工具不会调用最后一个阶段（日志记录）。
如果您想尝试不同的规则集，请记得重置 `basic_rules.conf`。
## 报告问题
如果您遇到配置问题或某些功能不如预期，请使用 ModSecurity 用户邮件列表。GitHub 上的问题也欢迎，但我们更希望用户首先在邮件列表上提问，这样您可以接触到整个社区。另外，在提出新问题之前，不要忘记查找现有问题。
如果您要在 GitHub 上提出新问题，不要忘记告诉我们您使用的 libmodsecurity 版本以及特定连接器的版本（如果有的话）。
### 安全问题
请不要公开任何安全问题。请通过 modsecurity@owasp.org 联系我们报告问题。问题修复后，我们会给予致谢。
## 功能请求
我们愿意通过邮件列表与社区讨论任何新功能请求。或者，您也可以随时在 GitHub 上提出请求新功能的 issue。在提出新 issue 之前，请检查是否已有相同主题的 issue 存在。
## 绑定
libModSecurity 的设计允许与绑定集成。我们努力避免破坏 API [二进制] 兼容性，以便与可能的绑定轻松集成。目前，社区维护着几个值得注意的项目：
* Python - https://github.com/actions-security/pymodsecurity
* Rust - https://github.com/rkrishn7/rust-modsecurity
* Varnish - https://github.com/xdecock/vmod-modsecurity
## 打包
我们希望能够及时在我们的发行版中提供我们的包，所以如果有任何我们可以做的事情来促进您作为打包者的工作，请告诉我们。
## 赞助说明
ModSecurity 的开发由 Trustwave 赞助。赞助将于 2024 年 7 月 1 日结束。更多信息可在此处找到：https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/
标签：Apache, AppImage, ETW劫持, HTTP流量监控, IIS, ModSecurity, Nginx, Redis利用, WAF, Web安全, Web应用防火墙, 事件编程语言, 云计算, 安全引擎, 实时分析, 开源, 攻击防御, 日志记录, 渗透测试防护, 网络安全, 蓝队分析, 规则引擎, 隐私保护