sudoNaji/ngx-shield

# NGX-Shield：生产级 NGINX WAF 技术栈 [](https://opensource.org/licenses/MIT) [](https://docs.docker.com/compose/) [](https://coreruleset.org/) 一个生产可用的 Docker-Compose 技术栈，部署由 ModSecurity 和 OWASP Core Rule Set (CRS) 驱动的 NGINX Web Application Firewall (WAF)，并通过 Prometheus 和 Grafana 提供完善的可观测性。 ## 目录 - [概述](#overview) - [功能](#features) - [项目结构](#project-structure) - [前置条件](#prerequisites) - [快速开始](#quick-start) - [测试 WAF](#testing-the-waf) - [可观测性](#observability) - [配置](#configuration) - [维护](#maintenance) - [贡献](#contributing) - [许可证](#license) - [联系方式](#contact) ## 概述 NGX-Shield 提供了一个安全、可配置且隔离的环境，用于测试和部署 NGINX 作为 WAF。该技术栈包含： - **NGINX** 作为反向代理和 WAF 网关 - **ModSecurity** 搭配 **OWASP CRS** 提供实时威胁防护 - **Prometheus** 用于指标收集和监控 - **Grafana** 用于可视化和告警 - **NGINX Exporter** 用于将 NGINX 指标暴露给 Prometheus - 一个简单的 **Flask 应用**，用于测试 WAF 功能 该技术栈非常适合用于学习 WAF 概念、测试安全规则，或作为生产部署的起点。 ## 功能 - 🛡️ **实时 WAF 防护**：使用 OWASP CRS 阻止常见的 Web 攻击（SQLi、XSS、RCE 等） - 📊 **全面可观测性**：通过 Prometheus 获取指标，通过 Grafana 展示仪表盘 - 🐳 **Dockerized**：使用 Docker Compose 轻松部署 - 🔧 **可配置**：方便地调整规则、端口和设置 - 📝 **详细日志**：ModSecurity 审计日志、NGINX 访问/错误日志 - 🧪 **开箱即用的测试**：包含测试应用和验证步骤 - 📚 **文档完善**：提供涵盖设置、测试和扩展的综合指南 ## 项目结构 ``` ngx-shield/ ├── docker-compose.yml # Main compose file ├── nginx/ # NGINX configuration │ ├── nginx.conf # Main NGINX config │ ├── conf.d/ │ │ └── waf.conf # WAF-specific site config │ └── modsec/ # ModSecurity configuration │ ├── modsecurity.conf │ ├── unicode.mapping │ └── crs/ # OWASP Core Rule Set │ ├── crs-setup.conf │ └── rules/ ├── prometheus/ # Prometheus configuration │ └── prometheus.yml ├── grafana/ # Grafana provisioning │ └── provisioning/ │ ├── datasources/ds.yml │ └── dashboards/ngx-shield.json ├── logs/ # Bind-mounted logs directory ├── app/ # Test Flask application │ ├── Dockerfile │ └── app.py └── README.md # This file ``` ## 前置条件 - [Docker Engine](https://docs.docker.com/engine/install/) (v20.10+) - [Docker Compose](https://docs.docker.com/compose/install/) (v2.0+) - 约 2GB 的可用磁盘空间 - 对终端/命令行有基本了解 ## 快速开始 ### 1. 设置 OWASP CRS 由于许可限制，默认不包含 OWASP CRS。使用以下命令初始化： ``` git clone https://github.com/coreruleset/coreruleset nginx/modsec/crs cp nginx/modsec/crs/crs-setup.conf.example nginx/modsec/crs/crs-setup.conf ``` ### 2. 启动技术栈 ``` docker compose up -d ``` ### 3. 验证服务 检查所有容器是否健康： ``` docker compose ps ``` ### 4. 测试 WAF - **正常请求**（应返回 200）： curl -i http://localhost/ - **SQL 注入尝试**（应返回 403 被阻止）： curl -i "http://localhost/?id=1'+OR+1=1--" ### 5. 访问 Grafana - URL: - 用户名: `admin` - 密码: `ngxshield` - **NGX-Shield** 仪表盘已自动预配置，并显示关键指标。 ## 测试 WAF ### 特定模块测试 #### 1. App 和 NGINX-WAF ``` docker compose up -d app nginx-waf # 测试如上普通请求和 SQLi docker compose stop app nginx-waf ``` #### 2. NGINX Exporter ``` docker compose up -d app nginx-waf nginx-exporter curl -s http://localhost:9113/metrics | head -n 20 docker compose stop app nginx-waf nginx-exporter ``` #### 3. Prometheus ``` docker compose up -d app nginx-waf nginx-exporter prometheus # 访问 http://localhost:9090，检查 target 状态，查询 nginx_http_requests_total docker compose stop app nginx-waf nginx-exporter prometheus ``` #### 4. Grafana（全栈） ``` docker compose up -d # 访问 http://localhost:3000，探索预构建的 dashboard ``` ### WAF 专属面板（需要 Loki） 要启用高级 WAF 面板（被阻止的 IP、触发的规则），请添加 Loki 和 Promtail： 1. 添加到 `docker-compose.yml`： loki: image: grafana/loki:2.9.4 ports: ["3100:3100"] networks: [shield] promtail: image: grafana/promtail:2.9.4 volumes: - ./logs:/var/log/nginx:ro - ./promtail-config.yml:/etc/promtail/config.yml:ro networks: [shield] 2. 创建 `promtail-config.yml`： server: http_listen_port: 9080 grpc_listen_port: 0 positions: filename: /tmp/positions.yaml clients: - url: http://loki:3100/loki/api/v1/push scrape_configs: - job_name: nginx static_configs: - targets: [localhost] labels: job: nginx __path__: /var/log/nginx/modsec_audit.log 3. 更新 Grafana 仪表盘以使用 Loki 数据源。 ## 可观测性技术栈 | 组件 | 端口 | 用途 | |-----------|------|---------| | **NGINX** | 80 | WAF 入口点 | | **Prometheus** | 9090 | 指标收集和查询 | | **Grafana** | 3000 | 可视化和告警 | | **NGINX Exporter** | 9113 | 将 NGINX 指标暴露给 Prometheus | ## 配置 ### ModSecurity 规则 - 核心规则: `nginx/modsec/crs/` - 自定义规则: 将 `.conf` 文件添加到 `nginx/modsec/rules/` 并在 `modsecurity.conf` 中引入 - 要在 DetectionOnly 和 Prevention 模式之间切换，请编辑 `nginx/modsec/modsecurity.conf` 中的 `SecRuleEngine` ### NGINX 设置 - 主配置: `nginx/nginx.conf` - WAF 站点: `nginx/conf.d/waf.conf`（根据您的应用调整 `proxy_pass`） - 日志格式: 在 `waf.conf` 中定义 ### Prometheus & Grafana - Prometheus 抓取配置: `prometheus/prometheus.yml` - Grafana 仪表盘: `grafana/provisioning/dashboards/` - 数据源: `grafana/provisioning/datasources/ds.yml` ## 维护 ### 日志监控 ``` # ModSecurity 审计日志（攻击详情） tail -f logs/modsec_audit.log # NGINX 访问日志 tail -f logs/access.log # NGINX 错误日志 tail -f logs/error.log ``` ### 技术栈管理 ``` # 查看所有 service 的日志 docker compose logs -f # 重启特定 service docker compose restart nginx-waf # 更新 OWASP CRS（定期） cd nginx/modsec/crs git pull cd ../.. ``` ### 安全最佳实践 1. **始终先在 DetectionOnly 模式下测试规则** 2. **定期更新** OWASP CRS 和容器镜像 3. **审查日志**以发现误报，并相应地调整规则 4. 在生产环境中**考虑速率限制**和 IP 信誉 5. 在生产环境中**使用 HTTPS**（在 upstream 终止或向 NGINX 添加证书） ## 许可证 该项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。 **注意**：该项目使用的 OWASP CRS 单独基于 [Apache License 2.0](https://github.com/coreruleset/coreruleset/blob/master/LICENSE) 授权。 ## 联系方式 项目链接: [https://github.com/sudoNaji/ngx-shield](https://github.com/sudoNaji/ngx-shield) 如有问题、建议或安全疑虑，请在 GitHub 仓库中提 issue。 *❤️ 打造安全的 Web 应用*

标签：AppImage, CISA项目, Docker, ModSecurity, NGINX, WAF, Web应用防火墙, 安全防御评估, 安全防护, 版权保护, 自定义请求头, 负责任AI, 逆向工具