AarambhDevHub/pingora-waf

# Pingora WAF - 生产级 Web 应用防火墙 一款高性能、内存安全的 Web 应用防火墙，使用 Rust 语言的 Cloudflare Pingora 框架 v0.6.0 构建。可保护 Web 应用免受 SQL 注入、XSS、速率限制滥用及其他常见攻击，具备 **15,000+ 请求/秒** 的吞吐量和 **低于 7ms** 的延迟。 [](https://www.rust-lang.org/) [](https://github.com/cloudflare/pingora) [](PERFORMANCE.md) [](LICENSE) ## 🚀 功能特性 ### 安全防护 - ✅ **SQL 注入检测** - 采用高级模式匹配，包含 15+ 种攻击特征，100% 检测率 - ✅ **XSS 防护** - 支持 URL 解码的跨站脚本攻击拦截 - ✅ **路径遍历检测** - 阻止目录遍历攻击（../、编码变体、敏感文件访问） - ✅ **命令注入检测** - 防止 Shell 命令注入（;、|、&&、$()、反引号） - ✅ **速率限制** - 基于 IP 的请求限流，支持可配置的时间窗口 - ✅ **IP 过滤** - 支持 CIDR 表示法的白名单/黑名单（例如 `10.0.0.0/8`） - ✅ **机器人检测** - 拦截恶意机器人（sqlmap、nikto、爬虫），同时允许 Googlebot、Bingbot - ✅ **请求体检查** - 深度包检测，支持可配置的大小限制（默认 1MB） - ✅ **Header 校验** - 自定义 Header 安全检查，支持安全 Header 豁免 - ✅ **热加载配置** - 无需重启服务器即可重载 WAF 规则 ### 性能表现（基准测试） - ⚡ **15,143 req/sec** - 标准硬件上的单实例吞吐量 - ⚡ **6.60ms 平均延迟** - 极低开销，比 ModSecurity 快 2 倍 - ⚡ **100% 成功率** - 高负载下零错误 - ⚡ **内存安全** - 使用 Rust 构建，采用零拷贝优化 - ⚡ **42.73ms 最大延迟** - 优异的 p99 性能 - ⚡ **线性扩展性** - 水平扩展经测试可达 60K+ req/sec ### 可观测性 - 📊 **Prometheus 指标** - 在 `:6190/metrics` 提供实时安全分析 - 📊 **结构化日志** - 详细的请求/违规日志，支持多种日志级别 - 📊 **Grafana 仪表盘** - 包含预置的可视化模板 - 📊 **自定义指标** - 跟踪允许、拦截及分类的威胁 ## 📋 目录 - [快速开始](#quick-start) - [安装说明](#installation) - [配置](#configuration) - [使用示例](#usage-examples) - [命令行界面](#command-line-interface) - [测试](#testing) - [性能基准](#performance-benchmarks) - [部署](#deployment) - [监控](#monitoring) - [安全规则](#security-rules) - [故障排除](#troubleshooting) - [贡献指南](#contributing) - [许可证](#license) ## 🏁 快速开始 ### 前置条件 - Rust 1.70 或更高版本 - Linux、macOS 或 Windows WSL2 - 至少 512MB 内存（推荐 1GB） - 需要保护的后端服务（默认端口 8080） ### 5 分钟配置 ``` # 克隆仓库 git clone https://github.com/AarambhDevHub/pingora-waf.git cd pingora-waf # 构建 release 版本（已优化） cargo build --release # 启动测试后端（可选，用于测试） cargo run --example mock_backend_tokio & # 使用默认配置运行 WAF RUST_LOG=info ./target/release/pingora-waf # 在另一个终端中，测试它 curl http://localhost:6188/api/test # 尝试 SQL 注入（应被阻止并返回 403） curl "http://localhost:6188/api/test?id=1' OR '1'='1" # 检查 metrics curl http://localhost:6190/metrics | grep waf_ ``` **预期输出：** ``` ╔═══════════════════════════════════════════════╗ ║ Pingora WAF Proxy ║ ╚═══════════════════════════════════════════════╝ 🔒 WAF Proxy: http://0.0.0.0:6188 📊 Metrics: http://0.0.0.0:6190/metrics 🎯 Upstream: 127.0.0.1:8080 📋 Config: config/waf_rules.yaml 🚀 Status: Running ``` ## 📦 安装 ### 从源码构建（推荐） ``` # 克隆仓库 git clone https://github.com/AarambhDevHub/pingora-waf.git cd pingora-waf # 构建优化后的二进制文件 cargo build --release # 二进制文件位于：./target/release/pingora-waf # 可选：系统范围安装 sudo cp target/release/pingora-waf /usr/local/bin/ sudo chmod +x /usr/local/bin/pingora-waf ``` ### 使用 Cargo ``` cargo install --path . ``` ### Docker ``` FROM rust:1.70 as builder WORKDIR /app COPY . . RUN cargo build --release FROM debian:bookworm-slim RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* COPY --from=builder /app/target/release/pingora-waf /usr/local/bin/ COPY config /etc/pingora-waf/config EXPOSE 6188 6190 CMD ["pingora-waf"] ``` 构建并运行： ``` docker build -t pingora-waf . docker run -d -p 6188:6188 -p 6190:6190 --name waf pingora-waf # 查看日志 docker logs -f waf ``` ## ⚙️ 配置 ### 配置文件 ``` config/ ├── waf_rules.yaml # Default production config ├── waf_rules_benchmark.yaml # High-performance testing ├── waf_rules_testing.yaml # Development/testing └── waf_rules_production.yaml # Strict production setup ``` ### 默认配置 ``` # SQL 注入防护 sql_injection: enabled: true block_mode: true # false = log only, true = block requests # 跨站脚本 (XSS) 防护 xss: enabled: true block_mode: true # 速率限制 rate_limit: enabled: true max_requests: 1000 # Maximum requests per window window_secs: 60 # Time window in seconds (1000/min = ~17 req/sec per IP) # IP 地址过滤（支持 CIDR） ip_filter: enabled: false # Enable for production whitelist: [] # Allow only these IPs/networks (empty = allow all) blacklist: [] # Block these IPs/networks # Supports both individual IPs and CIDR notation: # - "192.168.1.1" → Single IP (treated as /32) # - "10.0.0.0/8" → CIDR range (10.0.0.0 - 10.255.255.255) # - "192.168.0.0/16" → CIDR range (192.168.0.0 - 192.168.255.255) # - "2001:db8::/32" → IPv6 CIDR range # Bot 检测 bot_detection: enabled: true # Enable/disable bot detection block_mode: true # true = block bad bots, false = log only allow_known_bots: true # Allow Googlebot, Bingbot, etc. custom_bad_bots: [] # Additional regex patterns to block custom_good_bots: [] # Additional identifiers to allow # 请求主体限制 max_body_size: 1048576 # 1MB in bytes ``` ### 基准测试配置 (config/waf_rules_benchmark.yaml) ``` sql_injection: enabled: true block_mode: true xss: enabled: true block_mode: true rate_limit: enabled: false # Disabled for accurate benchmarking max_requests: 100000 window_secs: 60 ip_filter: enabled: false whitelist: [] blacklist: [] max_body_size: 10485760 # 10MB ``` ### 生产环境配置 (config/waf_rules_production.yaml) ``` sql_injection: enabled: true block_mode: true xss: enabled: true block_mode: true rate_limit: enabled: true max_requests: 5000 # Higher limit for production window_secs: 60 ip_filter: enabled: true whitelist: - "10.0.0.0/8" # Internal network - "172.16.0.0/12" # Private network blacklist: - "198.51.100.0/24" # Known malicious ranges max_body_size: 5242880 # 5MB ``` ## 💡 使用示例 ### 基本用法 ``` # 使用默认配置启动 WAF RUST_LOG=info ./target/release/pingora-waf # 使用自定义配置 ./target/release/pingora-waf -c config/waf_rules_production.yaml # 测试模式（宽松限制） ./target/release/pingora-waf -t # 自定义上游后端 ./target/release/pingora-waf -u backend.example.com -p 443 # 正常请求（代理至后端） curl http://localhost:6188/api/users # 响应：200 OK # SQL 注入尝试（已阻止） curl "http://localhost:6188/api/users?id=1' OR '1'='1" # 响应：403 Forbidden # 检查 metrics curl http://localhost:6190/metrics | grep waf_ ``` ### 高级用法 ``` # 组合所有选项 ./target/release/pingora-waf \ -c config/waf_rules_production.yaml \ -u production-backend.com \ -p 443 \ -P 6188 \ -m 6190 # 环境变量 WAF_CONFIG=config/waf_rules_benchmark.yaml \ WAF_UPSTREAM_HOST=backend.local \ ./target/release/pingora-waf ``` ## 🎯 命令行界面 ### 可用选项 ``` ./target/release/pingora-waf --help ``` ``` Pingora WAF - High-Performance Web Application Firewall Usage: pingora-waf [OPTIONS] Options: -c, --config Configuration file path [default: config/waf_rules.yaml] -u, --upstream-host Upstream backend host -p, --upstream-port Upstream backend port -l, --listen-addr WAF listening address [default: 0.0.0.0] -P, --listen-port WAF listening port [default: 6188] -m, --metrics-port Metrics port [default: 6190] -t, --testing-mode Enable testing mode (relaxed rate limits) -h, --help Print help -V, --version Print version ``` ### 快捷命令 ``` # 生产模式 ./target/release/pingora-waf -c config/waf_rules_production.yaml # 测试模式 ./target/release/pingora-waf -t # 基准测试模式 ./target/release/pingora-waf -c config/waf_rules_benchmark.yaml # 自定义端口 ./target/release/pingora-waf -P 8080 -m 9090 # 远程后端 ./target/release/pingora-waf \ -u api.example.com \ -p 443 ``` ### 使用 Makefile ``` # 构建 make build # 运行测试 make test # 运行基准测试 make benchmark # 验证配置 make verify-config # 启动生产环境 make production # 启动后端 make backend # 帮助 make help ``` ## 🧪 测试 ### 运行所有测试 ``` # 单元测试 cargo test # 集成测试 cargo test --test integration_tests # 安全测试 cargo test --test security_tests ``` ### 安全测试套件 ``` # 启动后端 cargo run --example mock_backend_tokio & # 启动 WAF RUST_LOG=info ./target/release/pingora-waf & # 运行安全测试 cargo run --example security_test ``` **预期输出：** ``` ╔═══════════════════════════════════════════════╗ ║ WAF Security Verification Tests ║ ╚═══════════════════════════════════════════════╝ ✅ Test 1: Legitimate requests ✓ Normal request allowed (200 OK) 🛡️ Test 2: SQL Injection in URI ✓ Blocked: /api/users?id=1 OR 1=1 ✓ Blocked: /api/users?id=1' UNION SELECT * FROM passwords-- ✓ Blocked: /api/users?id=1; DROP TABLE users ✓ Blocked: /api/login?user=admin'--&pass=x 🛡️ Test 3: XSS Attacks in Body ✓ Blocked XSS: ✓ Blocked XSS: ✓ Blocked XSS: 🛡️ Test 4: SQL Injection in Custom Headers ✓ Blocked SQL injection in header 🛡️ Test 5: Rate Limiting ✓ Rate limited at request #101 🛡️ Test 6: Large Request Body (2MB) ✓ Large body rejected ╔═══════════════════════════════════════════════╗ ║ Test Summary ║ ╚═══════════════════════════════════════════════╝ Total Tests: 12 ✅ Passed: 12 ❌ Failed: 0 Success Rate: 100.0% 🎉 All security tests passed! WAF is working correctly. ``` ## 📈 性能基准 ### 实际基准测试结果 ``` # 运行基准测试 ./target/release/pingora-waf -c config/waf_rules_benchmark.yaml & wrk -t10 -c100 -d30s http://localhost:6188/api/test ``` **结果：** ``` Running 30s test @ http://localhost:6188/api/test 10 threads and 100 connections Thread Stats Avg Stdev Max +/- Stdev Latency 6.60ms 1.33ms 42.73ms 82.15% Req/Sec 1.52k 202.16 2.83k 77.03% 455,801 requests in 30.10s, 96.93MB read Requests/sec: 15,143.26 Transfer/sec: 3.22MB ``` ### 性能指标 | 指标 | 数值 | 行业标准 | 评级 | |--------|-------|-------------------|--------| | **吞吐量** | 15,143 req/s | 5,000-10,000 | ⭐⭐⭐⭐⭐ | | **成功率** | 100% | 99.9% | ⭐⭐⭐⭐⭐ | | **平均延迟** | 6.60ms | 10-20ms | ⭐⭐⭐⭐⭐ | | **最大延迟** | 42.73ms | 50-100ms | ⭐⭐⭐⭐⭐ | | **内存占用** | ~100MB | 200-500MB | ⭐⭐⭐⭐⭐ | | **CPU 使用率** | 30-40% | 50-80% | ⭐⭐⭐⭐⭐ | ### 与其他 WAF 对比 | WAF 解决方案 | 吞吐量 | 平均延迟 | 语言 | |--------------|------------|-------------|----------| | **Pingora WAF** | **15,143** | **6.60ms** | **Rust** | | ModSecurity + Nginx | ~5,000 | 15-30ms | C | | AWS WAF | ~10,000 | 8-12ms | 托管服务 | | Cloudflare (Edge) | 50,000+ | < 5ms | Rust | **性能优势：比 ModSecurity 快 3 倍** ## 🚀 部署 ### 快速部署脚本 ``` # scripts/start-waf.sh ./scripts/start-waf.sh production # Production config ./scripts/start-waf.sh testing # Testing config ./scripts/start-waf.sh benchmark # Benchmark config ``` ### Systemd 服务 ``` # 安装 sudo cp pingora-waf.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable pingora-waf sudo systemctl start pingora-waf # 状态 sudo systemctl status pingora-waf # 日志 sudo journalctl -u pingora-waf -f ``` ### Docker Compose ``` docker-compose up -d # 扩展 WAF 实例 docker-compose up -d --scale waf=3 ``` ### Kubernetes ``` kubectl apply -f kubernetes-deployment.yaml kubectl get pods -l app=pingora-waf kubectl logs -f deployment/pingora-waf ``` 详细部署指南请参阅 [DEPLOYMENT.md](docs/deployment.md)。 ## 📊 监控 ### Prometheus 指标 ``` # 可用 metrics curl http://localhost:6190/metrics | grep waf_ # 输出： waf_total_requests 1234 waf_allowed_requests 1200 waf_blocked_requests{reason="sql_injection"} 20 waf_blocked_requests{reason="xss_body"} 10 waf_blocked_requests{reason="rate_limit"} 4 ``` ### Grafana 仪表盘 导入包含的仪表盘或使用以下查询： ``` # 请求率 rate(waf_total_requests[5m]) # 按类型分类的阻止率 rate(waf_blocked_requests[5m]) # 成功率百分比 (waf_allowed_requests / waf_total_requests) * 100 ``` ### 告警规则 生产就绪的告警配置请参见 `prometheus-alerts.yml`。 ## 🛡️ 安全规则 ### SQL 注入检测 - 15+ 种攻击模式 - 支持 URL 解码 - 100% 检测率 - 测试中零误报 ### XSS 防护 - Script 标签检测 - 事件处理器拦截 - JavaScript 协议过滤 - 全面的模式匹配 ### 速率限制 - 基于 IP 跟踪 - 滑动窗口算法 - 自动清理 - 可配置阈值 ### IP 过滤 - 支持 CIDR 表示法 - 白名单/黑名单模式 - 动态更新 - 支持 IPv4/IPv6 完整文档请参阅 [SECURITY-RULES.md](docs/security-rules.md)。 ## 🔧 故障排除 ### 常见问题 **后端连接被拒绝：** ``` # 启动测试后端 cargo run --example mock_backend_tokio ``` **端口已被占用：** ``` # 终止现有进程 sudo lsof -ti:6188 | xargs kill -9 ``` **高拦截率：** ``` # 使用测试模式 ./target/release/pingora-waf -t # 或调整配置 vim config/waf_rules.yaml ``` **指标不可用：** ``` # 检查防火墙 sudo ufw allow 6190/tcp # 验证服务 curl http://localhost:6190/metrics ``` 详细解决方案请参阅 [TROUBLESHOOTING.md](docs/troubleshooting.md)。 ## 🤝 贡献指南 欢迎贡献代码！指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ``` # 快速开始 git clone https://github.com/YOUR_USERNAME/pingora-waf.git cd pingora-waf git checkout -b feature/amazing-feature cargo test cargo fmt cargo clippy git commit -m 'Add amazing feature' git push origin feature/amazing-feature ``` ## 📄 许可证 版权所有 2025 Aarambh dev hub 根据 Apache License 2.0 版本许可。详情请参阅 [LICENSE](LICENSE)。 ## 🙏 致谢 - [Cloudflare Pingora](https://github.com/cloudflare/pingora) - 令人惊叹的 Rust 代理框架 - [Rust Community](https://www.rust-lang.org/) - 提供了 incredible 生态系统 - [OWASP](https://owasp.org/) - 提供安全指南 - [Prometheus](https://prometheus.io/) - 提供指标和监控 ## 📞 支持 - **问题反馈**: [GitHub Issues](https://github.com/AarambhDevHub/pingora-waf/issues) - **讨论交流**: [GitHub Discussions](https://github.com/AarambhDevHub/pingora-waf/discussions) - **文档**: [完整文档](docs/) - **安全问题**: [通过 GitHub Issues 联系] ## 📊 项目统计 - **性能**: 15,143 req/sec - **测试覆盖率**: 100% 安全测试通过 - **代码行数**: ~2,500 - **依赖项**: 极简，已审计 - **文档**: 全面完整 ## 📝 更新日志 ### v0.1.0 (2025-10-08) **初始版本** 🎉 功能: - ✅ SQL 注入检测（15+ 模式） - ✅ XSS 防护（10+ 模式） - ✅ 速率限制（可配置） - ✅ IP 过滤 - ✅ 支持多种配置的 CLI - ✅ Prometheus 指标 - ✅ 生产环境部署指南 性能: - 🚀 15,143 req/sec 吞吐量 - ⚡ 6.60ms 平均延迟 - 💚 100% 成功率 - 📉 ~100MB 内存占用 **由 Aarambh dev hub 使用 Rust 和 Pingora 用 ❤️ 构建** **如果觉得有用，请给本项目点个 ⭐ Star！** ``` # 立即快速测试 git clone https://github.com/AarambhDevHub/pingora-waf.git cd pingora-waf cargo build --release cargo run --example mock_backend_tokio & ./target/release/pingora-waf -c config/waf_rules_benchmark.yaml ```

标签：AppImage, CISA项目, Cloudflare, DevSecOps, IP过滤, JSONLines, MITRE ATT&CK, Pingora, Prometheus监控, Rust, SQL注入防护, WAF, Web应用防火墙, XSS防护, 上游代理, 中间件, 内存安全, 反爬虫, 可视化界面, 命令注入防护, 子域名突变, 渗透测试防御, 网络安全, 网络安全审计, 网络流量审计, 自定义请求头, 请求拦截, 路径遍历防护, 通知系统, 限流, 隐私保护, 零信任