Black-Cockpit/ansible-secure-nginx

# hasnmehti91.secure_nginx 此 Ansible collection 用于安装 NGINX 并针对其构建 [ModSecurity](https://github.com/owasp-modsecurity/ModSecurity) Web 应用防火墙。它包含两个角色——一个用于在主机上部署 NGINX，另一个用于从源码编译 `libmodsecurity` 和 NGINX 连接器，安装生成的动态模块，并在 `/etc/nginx/waf_rules` 下 编写规则配置。 这两个角色需按顺序执行。`mod_security` 会针对主机上 现有的 NGINX 编译其连接器，若不存在则会拒绝运行，因此 `install` 是使其可用的前提。 ## 角色 - **install** — 安装 NGINX，然后启用并启动服务。 请参阅 [install 角色文档](roles/install/README.md)。 - **mod_security** — 构建并安装适用于 NGINX 的 ModSecurity 模块及其规则配置。请参阅 [mod_security 角色文档](roles/mod_security/README.md)。 ## 覆盖范围 这两个角色支持相同的发行版集合，这些发行版在每个角色的 `supported_distribution` 变量中定义，并由首个任务的断言强制执行。不属于该集合的发行版会导致触发它的主机运行失败，而不会报告 `ok` 且什么都不做。 | 发行版 | 版本 | NGINX 软件包来源 | CI 测试 | | --- | --- | --- | --- | | AlmaLinux | 8, 9, 10 | nginx.org stable | 10 | | CentOS | 8, 9, 10 | nginx.org stable | — | | Debian | 11, 12 | 发行版归档 | — | | Oracle Linux | 8, 9, 10 | nginx.org stable | — | | Red Hat Enterprise Linux | 8, 9, 10 | nginx.org stable | — | | Rocky Linux | 8, 9, 10 | nginx.org stable | — | | Ubuntu | 22.04, 24.04 | 发行版归档 | 24.04 | **经过 CI 测试的平台仅限 Ubuntu 24.04 和 AlmaLinux 10。** 列出其他所有行是因为它们与这两个平台之一共享相同的包管理器、 仓库布局和依赖名称——而并非因为它们已被实际测试过。请将未测试的行视为基于构建逻辑受支持，在依赖它们之前请自行进行验证。 Enterprise Linux 从官方的 nginx.org stable 仓库获取 NGINX，而不是从 AppStream 获取，因为 `mod_security` 需要与运行版本匹配的源码 tarball，而供应商构建版本包含上游从未发布过的版本字符串。Debian 系则继续 安装发行版软件包。有关此差异在各个路径上产生的代价，请参阅 [install 角色](roles/install/README.md)。 ## 要求 - 控制节点上需安装 Python 3 和 Ansible。`meta/runtime.yml` 声明了 `ansible-core` `2.15.8` 或更高版本；代码库自身的工具在 `requirements.txt` 中指定了 `ansible>=10.0.0,<14.0.0`。 - 目标节点需具备 `become` 权限，且每个节点都运行上述平台 之一。 - 每个目标节点都需要对外的 HTTPS 访问权限，以连接到 `github.com`（用于获取 ModSecurity 发布版 tarball 和连接器仓库）和 `nginx.org`（用于在每个平台上获取 NGINX 源码 tarball，以及在 Enterprise Linux 上获取软件包仓库）。 - 每个目标节点在 `build_dir` 下需要大约 2 GB 的可用空间以及几分钟的 CPU 时间。这两个源码构建过程在运行时间中占据了绝大部分。 - `build_dir` 既不能被挂载为 `noexec`，也不能被定期清理。默认路径是 `/tmp`，而在此处这两种策略都很常见，且都会导致构建中断。 ## 安装 ``` ansible-galaxy collection install hasnimehdi91.secure_nginx ``` ## 用法 单独安装 NGINX： ``` - name: Install nginx hosts: all become: true gather_facts: true any_errors_fatal: true roles: - name: hasnimehdi91.secure_nginx.install ``` 安装 NGINX 并针对其构建防火墙。建议从 `detection_only: true` 开始，这会记录规则匹配情况并照常处理请求，审查审计日志后，再将其切换为 `false`： ``` - name: Install nginx and ModSecurity hosts: all become: true gather_facts: true any_errors_fatal: true roles: - name: hasnimehdi91.secure_nginx.install - name: hasnimehdi91.secure_nginx.mod_security vars: detection_only: true ``` `detection_only`、`module_version` 和 `build_dir` 在角色的 `vars/main.yml` 中声明，其优先级高于清单（inventory）。可以像上文那样将它们作为角色参数设置，或在命令行中设置——在 `group_vars` 或 `host_vars` 中使用相同的变量名会被静默忽略： ``` ansible-playbook -i inventory playbook.yml -e detection_only=true ``` ## 结果 在两个角色都运行完毕后，主机上将安装、启用并启动 NGINX；在 NGINX 编译时读取的模块目录中会包含 `ngx_http_modsecurity_module.so`；从 `/etc/nginx/nginx.conf` 中会包含 `load_module` 指令；并且在 `/etc/nginx/waf_rules` 下会有规则配置。完整的路径列表请参见 [mod_security 角色文档](roles/mod_security/README.md#results)。 该 collection 没有完成以下两件事，你需要自己处理： - **没有任何操作会开启防火墙。** 没有将 `modsecurity on;` 或 `modsecurity_rules_file` 指令写入任何 `http`、 `server` 或 `location` 块中，因此该模块虽已加载但处于未激活状态，并且不会检查任何请求。需要添加的代码行请参见 [开启 WAF](roles/mod_security/README.md#switching-the-waf-on)。 - **没有任何操作会重载 NGINX。** `mod_security` 定义了重启和 配置测试的 handler，但从未触发它们，因此正在运行的进程会继续在没有该模块的情况下提供服务，直到手动重启或被角色运行之后的其他操作重启。 该 collection 也没有安装任何攻击规则集。部署在 `/etc/nginx/waf_rules/modsecurity.conf` 中的是上游推荐的 引擎配置，而不是 [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset)； 在此 collection 的基础上添加 CRS 是一个独立的步骤。 ## 测试 该 collection 附带了一个一次性的 VM 集成测试工具，它可以启动一台机器，针对其运行两个角色并断言结果。这里没有单元测试：该 collection 没有提供 Python 插件，因此没有可供单元测试执行的内容。请参阅 [测试文档](tests/README.md)。 该矩阵仅涵盖 Ubuntu 24.04 和 AlmaLinux 10，不包含其他系统，其断言属于结构性的——即验证模块是否已构建、安装和加载，规则文件是否位于磁盘上，以及 `nginx -t` 是否仍然 通过。没有任何测试会断言防火墙是否拦截请求，因为在角色运行完毕后，它并不会执行拦截操作。 ## 链接 - 代码库： - 问题： - ModSecurity： - ModSecurity NGINX 连接器： - OWASP Core Rule Set： - NGINX Linux 软件包：

标签：Ansible, AppImage, ModSecurity, Nginx, Web应用防火墙, 系统加固, 系统提示词, 自动化配置, 负责任AI, 运维, 逆向工具