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) [](https://sonarcloud.io/dashboard?id=owasp-modsecurity_ModSecurity) Libmodsecurity 是 ModSecurity v3 项目的一个组件。该库的代码库用作与 ModSecurity 连接器的接口，负责接收 Web 流量并应用传统的 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）。这个库被我们称之为“连接器”的程序所使用，这些连接器将与您的 Web 服务器进行交互，并向库提供它能理解的通用格式。这些连接器各自作为独立的 GitHub 项目进行维护。例如，Nginx 连接器由 ModSecurity-nginx 项目 (https://github.com/owasp-modsecurity/ModSecurity-nginx) 提供。 将这些连接器分开维护使得每个项目可以拥有不同的发布周期、Issue（问题）和开发树。此外，这意味着当您安装 ModSecurity v3 时，您只会确切地获得您需要的东西，而不会有您不会用到的额外内容。 # 编译 在开始编译过程之前，请确保您已准备好所有依赖项。请阅读“依赖项”小节以获取更多信息。 编译完成后，请确保您的构建/平台上没有任何问题。我们强烈建议您使用单元测试和回归测试。这些测试工具位于子文件夹 ‘tests’ 中。 作为动态库，请不要忘记必须将 libmodsecurity 安装到您的操作系统会去寻找动态库的位置（文件夹）中。 ### Unix (Linux, MacOS, FreeBSD, …) 在 Unix 上，该项目使用 autotools 来辅助编译过程。请注意，如果您使用的是 `git`，请不要忘记初始化和更新子模块。以下是一个快速指南： ``` $ git clone --recursive https://github.com/owasp-modsecurity/ModSecurity ModSecurity $ cd ModSecurity ``` 然后您可以开始构建过程： ``` $ ./build.sh $ ./configure $ make $ sudo make install ``` 有关特定发行版构建的详细信息可以在我们的 Wiki 中找到： [编译指南](https://github.com/owasp-modsecurity/ModSecurity/wiki/Compilation-recipes) ### Windows Windows 构建信息可以在[此处](build/win32/README.md)找到。 ## 依赖项 该库使用 C++17 标准用 C++ 编写。它还使用 Flex 和 Yacc 来生成 “Sec Rules Language” 解析器。其他强制性依赖项包括 YAJL，因为 ModSecurity 使用 JSON 来生成日志及其测试框架；libpcre（目前非强制）用于处理 SecRules 中的正则表达式；以及 libXML2（目前非强制）用于解析 XML 请求。 所有其他的依赖项都与 SecRules 中指定的操作符或配置指令相关，可能并非编译所必需的。此类依赖项的简短列表如下： * 需要 libinjection 用于 @detectXSS 和 @detectSQL 操作符 * 需要 curl 用于 SecRemoteRules 指令。 如果缺少这些库，ModSecurity 将在没有 @detectXSS 操作符和 SecRemoteRules 配置指令支持的情况下进行编译。 # 库文档 库文档以 Doxygen 格式写在代码中。要生成此文档，请使用提供的配置文件（位于 "doc/" 子文件夹中的 "doxygen.cfg"）运行 doxygen 实用程序。这将生成包含使用示例的 HTML 格式的文档。 # 库使用 该库提供了 C++ 和 C 接口。某些资源目前只能通过 C++ 接口使用，例如，创建自定义日志机制的能力（请参阅回归测试以了解这些日志机制的工作原理）。 我们的目标是让两个 API（C、C++）提供相同的功能，如果您发现某个接口缺少了 API 的某个方面，请提交一个 Issue。 在 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; } ``` # 贡献 我们非常欢迎您为这个项目做出贡献，并期待围绕这个新版本的 ModSecurity 发展社区。感兴趣的领域包括：新功能、修复、错误报告、对新手的支持，或任何您愿意提供帮助的事情。 ## 提供补丁 我们更倾向于您在 GitHub 基础设施内提交补丁，以便于我们的审查工作和 Q.A.（质量保证）集成。GitHub 提供了关于如何执行“Pull Requests”的出色文档，更多信息请访问此处：https://help.github.com/articles/using-pull-requests/ 请尊重代码风格。Pull requests 可以包含各种提交，因此请为每个提交提供一个修复或一项功能。请不要更改目标工作范围之外的任何内容（例如，您路过的某个函数的代码风格）。有关此项目中使用的代码风格的更多信息，请查看：https://www.chromium.org/blink/coding-style 提供具有解释性的提交信息。您的第一行应该说明您补丁的亮点，第三行及之后应提供关于您补丁的更详细解释/技术细节。补丁说明在审查过程中非常有价值。 ### 不知道从哪里开始？ 在我们的代码中，有各种标记为 TODO 或 FIXME 的项目可能需要您的关注。通过执行 grep 来检查项目列表： ``` $ cd /path/to/modsecurity-nginx $ egrep -Rin "TODO|FIXME" -R * ``` TODO 列表也作为 Doxygen 文档的一部分提供。 ### 测试您的补丁 除了手动测试之外，我们强烈建议您使用我们的回归测试和单元测试。如果您实现了一个操作符，请不要忘记为它创建单元测试。如果您实现了其他任何内容，我们鼓励您为此开发补充的回归测试。 回归测试和单元测试工具是原生的，不需要任何外部工具或脚本，尽管您需要从其他仓库获取测试用例，因为它们与 ModSecurity 的其他版本共享，那些其他仓库是 git 子模块。要获取子模块仓库并运行这些实用程序，请遵循下面列出的命令： ``` $ cd /path/to/your/ModSecurity $ git submodule update --init --recursive $ make check ``` ### 调试 在开始调试过程之前，请确定您的错误在哪里。问题可能出在您的连接器或 libmodsecurity 中。为了确定错误在哪里，建议您开发一个回归测试来模拟发生错误的场景。如果该错误可以使用回归测试工具重现，那么调试并确保它不再发生就会简单得多。在 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' 来启用它们。 ### 基准测试 源代码树中包含一个基准测试工具，可以帮助测量库的性能。该工具位于 `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 事务。 每个事务都是一个带有一些 GET 参数的 HTTP/1.1 GET 请求。添加了常见的请求头，随后是响应头和一个 XML 正文。在各个阶段之间，该工具检查是否发生了干预。所有的事务都是使用相同的数据创建的。 请注意，该工具不调用最后一个阶段（日志记录）。 如果您想尝试不同的规则集，请记住重置 `basic_rules.conf`。 ## 报告问题 如果您正面临配置问题或某些东西没有像您预期的那样工作，请使用 ModSecurity 用户邮件列表。我们也欢迎在 GitHub 上提出问题，但我们更希望用户先在邮件列表上提问，这样您就可以接触到整个社区。此外，在创建新问题之前，请不要忘记查找现有问题。 如果您打算在 GitHub 上创建一个新问题，请不要忘记告诉我们您的 libmodsecurity 版本以及特定连接器的版本（如果有的话）。 ### 安全问题 请不要公开任何安全问题。通过以下方式联系我们： modsecurity@owasp.org 报告该问题。一旦问题修复，我们将给予您相应的贡献署名。 ## 功能请求 我们乐于通过邮件列表与社区讨论任何新的功能请求。您也可以随时通过创建 GitHub 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, API安全, AppImage, CISA项目, ETW劫持, HTTP流量监控, IIS, JSON输出, Libmodsecurity, ModSecurity, Nginx, SecRules, WAF, Web应用防火墙, 事件编程, 云计算, 反向代理, 安全引擎, 安全防护, 实时分析, 开源, 攻击拦截, 日志记录, 流量过滤, 漏洞防护, 网络安全, 规则引擎, 隐私保护