## 🔥 关于 **Kaido WAF** 是一款由 **Gustavo** 开发的高性能 Web Application Firewall，旨在保护 Web 应用程序免受当前环境中常见及高级的网络攻击。 它作为**异步反向代理**运行于客户端和后端之间，通过具备**10 种不同类别**、涵盖**超过 150 种攻击模式**的高性能检测引擎，**实时检测每一项请求**。 ### 🚨 安全警告 — 生产环境使用前必读 ``` # 🔴 在投入生产环境之前删除此项！ dashboard: password: "CHANGE_ME_IN_PRODUCTION" # ← TROQUE ISSO session_secret: "CHANGE_ME_IN_PRODUCTION" # ← TROQUE ISSO ``` **为什么这很重要？** - Dashboard 的默认密码是公开的（就在本 README 中） - 默认的 `session_secret` 允许伪造 admin 会话 - Redis 默认没有密码（请在 docker-compose 中使用 `REDIS_PASSWORD`） **生产环境安全检查清单：** - [ ] 修改 `dashboard.password` - [ ] 修改 `dashboard.session_secret` - [ ] 在 Redis 中配置 `REDIS_PASSWORD` - [ ] 审查 `ip_blocking.whitelist` - [ ] 如果不需要，在公网暴露环境中禁用 Dashboard - [ ] 使用 HTTPS（前置部署 Nginx/Cloudflare） - [ ] 以非 root 用户运行（Docker 已默认执行此操作） ### 为什么选择 Kaido WAF？ | 特性 | Kaido WAF | ModSecurity | Cloudflare WAF | |---------------|-----------|-------------|----------------| | **性能** | 异步 (aiohttp) | 同步 (Nginx module) | CDN-based | | **检测器** | 10 个类别中的 150+ 种模式 | CRS (可自定义规则) | 托管式 | | **Dashboard** | 内置 SSR (零 JS) | 无 | Cloudflare 面板 | | **Rate Limiting** | 滑动窗口 + Redis | Limit req module | 是 | | **IP Blocker** | 白名单/黑名单/自动 | 是 | 是 | | **Docker** | 原生支持 | 支持有限 | N/A | | **许可证** | MIT (免费) | Apache 2.0 | 付费 | | **成本** | **零** | 免费 | $$ | ## 🏗️ 架构 ``` ┌─────────────┐ ┌──────────────────────────────────────────────┐ ┌─────────────┐ │ │ │ KAIDO WAF │ │ │ │ Cliente │────▶│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │────▶│ Backend │ │ (Browser/ │ │ │ Proxy │──│Detection │──│ Rate │ │ │ (Upstream) │ │ API) │ │ │ Reverso │ │ Engine │ │ Limiter │ │ │ │ │ │ │ └─────────┘ └──────────┘ └───────────┘ │ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │ │ IP │ │ Log │ │Dashboard │ │ │ │ Blocker │ │ Sistema │ │ SSR │ │ │ └─────────┘ └──────────┘ └───────────┘ │ └──────────────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ PG │ │ Redis │ │ Discord │ │ (Memory) │ │ (Cache) │ │ (Webhook)│ └──────────┘ └──────────┘ └──────────┘ ``` ### 请求流程： ``` 1. Cliente envia requisição → WAF (porta 8080) 2. IP Blocker → Verifica whitelist/blacklist/auto-block 3. Rate Limiter → Verifica sliding window (memória ou Redis) 4. Detection Engine → 10 detectores em paralelo no path, query, body, headers, cookies 5. Ataque detectado? ├── SIM → Modo BLOCK: HTTP 403 + JSON + headers │ Modo DETECT: loga + encaminha │ Modo LOG: loga tudo + encaminha └── NÃO → Proxy reverso encaminha para upstream 6. Upstream responde → WAF faz streaming da resposta ao cliente ``` ## 🚀 功能 ### 🔒 安全 | 功能 | 详情 | |---------|----------| | **10 种检测器** | SQLi, XSS, Path Traversal, CMDi, SSRF, LFI/RFI, NoSQL, Cookie Poisoning, Open Redirect, Scanner Detection | | **150+ 种模式** | 真实的攻击特征，编译为优化的 regex | | **3 种模式** | Block (拦截), Detect (仅告警), Log (全面审计) | | **Rate Limiting** | 基于单个 IP 的滑动窗口，突发控制，渐进式超时 | | **IP Blocker** | 白名单，CIDR 黑名单，基于违规的自动封禁（按严重程度赋予权重） | | **自定义拦截** | 状态码，消息，headers，JSON 格式响应 | ### ⚡ 性能 | 功能 | 详情 | |---------|----------| | **异步代理** | aiohttp — 可同时处理数百个并发请求且不阻塞 | | **流式传输** | 支持大响应的 Chunked transfer encoding | | **可配置缓冲区** | 可调整的流式传输缓冲区大小 | | **可调整超时** | 单个请求的超时限制，body size 限制 | | **Redis 后端** | 为多实例提供分布式的 Rate Limiting | ### 📊 管理 | 功能 | 详情 | |---------|----------| | **SSR Dashboard** | 使用 Jinja2 进行服务端渲染 — 零 JavaScript | | **受保护的登录** | 基于 session 的身份验证，使用 HttpOnly cookie | | **JSON 日志** | JSON 格式的结构化日志，自动轮转 | | **Discord Webhook** | 向 Discord 发送安全告警 (WARNING+) | | **Health Check** | 提供用于监控的 `/__health` endpoint | | **统计信息** | 提供包含 WAF 指标的 `/__stats` endpoint | ### 🐳 部署 | 功能 | 详情 | |---------|----------| | **原生 Docker** | 优化的 Dockerfile (Python 3.13-slim) | | **Docker Compose** | 通过 3 个服务启动 WAF + Redis + 后端 | | **非 Root** | 以 `kaido` 用户 (非 root) 身份运行 | | **Healthcheck** | 集成 Docker healthcheck | | **滚动日志** | 带有备份的日志轮转 | ## 📦 安装 ### 前置条件 - Python 3.11+ - pip - Redis (可选，用于分布式 Rate Limiting) ### 通过 pip 安装 (本地) ``` # Clone git clone https://github.com/zlostc/kaido-waf.git cd kaido-waf # 安装依赖 pip install -r requirements.txt # 配置（可选 — 编辑 config.yaml） # vim config.yaml # 运行 python3 -m kaido_waf.main # 或通过 Makefile make run ``` ### 通过 Docker 安装 ``` # Build docker build -t kaido-waf . # Run docker run -d \ --name kaido-waf \ -p 8080:8080 \ -p 9090:9090 \ -v $(pwd)/config.yaml:/etc/kaido-waf/config.yaml \ -v kaido_logs:/var/log/kaido-waf \ kaido-waf ``` ### 通过 Docker Compose 安装 (推荐) ``` docker-compose -f examples/docker-compose.yml up -d ``` 这将会启动： - `kaido-waf` — 端口 8080 上的 WAF，以及端口 9090 上的 Dashboard - `redis` — 用于 Rate Limiting 的缓存 - `backend` — 端口 3000 上的 Nginx 示例 ### 通过 Makefile ``` make install # Instala dependências make run # Executa o WAF make docker-build # Build Docker make docker-run # Run Docker make docker-compose-up # Docker Compose make docker-compose-down # Parar Docker Compose make clean # Limpar cache ``` ## ⚙️ 配置 配置通过 YAML 进行。默认情况下，WAF 会在根目录寻找 `config.yaml`，或者你也可以通过环境变量 `KAIDO_WAF_CONFIG` 来指定。 ### 完整配置： ``` # ⚔️ Kaido WAF — 配置 # 高性能 Web Application Firewall # 由 Gustavo 创建 server: host: "0.0.0.0" # Interface de rede port: 8080 # Porta do WAF workers: 4 # Workers (reservado) upstream: "http://127.0.0.1:3000" # Backend a proteger timeout: 30 # Timeout em segundos buffer_size: 8192 # Tamanho do buffer de streaming (bytes) max_body_size: 10485760 # Tamanho máximo do body (10MB) waf: enabled: true # Liga/desliga o WAF mode: "block" # block | detect | log block_status_code: 403 # HTTP status code de bloqueio block_message: "Blocked by Kaido WAF — Attack detected" detection: sql_injection: true # SQL Injection xss: true # Cross-Site Scripting path_traversal: true # Path Traversal command_injection: true # Command Injection ssrf: true # Server-Side Request Forgery lfi_rfi: true # Local/Remote File Inclusion nosql_injection: true # NoSQL Injection cookie_poisoning: true # Cookie Poisoning open_redirect: true # Open Redirect scanner_detection: true # Scanner/Ferramentas de ataque rate_limiting: enabled: true # Liga/desliga rate limiting backend: "memory" # memory | redis redis_url: "redis://localhost:6379/0" requests_per_minute: 60 # Máx requisições por minuto por IP burst_size: 100 # Máx requisições em 1 segundo block_duration: 300 # Tempo de bloqueio após exceder (segundos) ip_blocking: enabled: true # Liga/desliga IP blocker whitelist: # IPs sempre permitidos - "127.0.0.1" - "::1" blacklist: [] # IPs sempre bloqueados auto_block_threshold: 10 # Ofensas antes de auto-bloquear auto_block_duration: 3600 # Duração do auto-bloqueio (segundos, 1h) logging: level: "INFO" # DEBUG | INFO | WARNING | ERROR | CRITICAL format: "json" # json | text file: "/var/log/kaido-waf/access.log" discord_webhook: "" # URL do webhook do Discord dashboard: enabled: true # Liga/desliga dashboard port: 9090 # Porta do dashboard auth_enabled: true # Exige login username: "admin" # Usuário do dashboard password: "CHANGE_ME_IN_PRODUCTION" # 🔴 MUDE ANTES DE USAR EM PRODUÇÃO! session_secret: "CHANGE_ME_IN_PRODUCTION" # 🔴 MUDE ANTES DE USAR EM PRODUÇÃO! ``` ### 环境变量： | 变量 | 描述 | 默认值 | |----------|-----------|--------| | `KAIDO_WAF_CONFIG` | 配置文件的路径 | `./config.yaml` | ## 🎯 操作模式 | 模式 | 描述 | 用途 | |------|-----------|-----| | **block** 🛡️ | 拦截恶意请求并返回 HTTP 403 | 生产环境 | | **detect** 👁️ | 仅检测并记录攻击，不进行拦截 | 预发布/测试 | | **log** 📝 | 记录所有内容（包括合法请求） | 审计/调试 | **在生产环境中切换模式的示例：** ``` waf: mode: "block" # Mude para "detect" se quiser apenas monitorar ``` ## 🧠 检测器 检测引擎拥有 **10 个分类**，包含**超过 150 种被编译为优化正则表达式的模式**。每个检测器都可以在 `config.yaml` 中单独开启或关闭。 ### 1. SQL Injection (`sql_injection`) 🔠 **20+ 种模式** — 检测主要的 SQL 注入技术： | 模式 | 严重程度 | 示例 | |--------|-----------|---------| | `UNION SELECT` | high | `' UNION SELECT * FROM users--` | | `DROP TABLE` | critical | `'; DROP TABLE users--` | | `EXEC xp_` | critical | `'; EXEC xp_cmdshell('dir')--` | | `WAITFOR DELAY` | critical | `'; WAITFOR DELAY '0:0:5'--` | | `BENCHMARK()` | critical | `' OR BENCHMARK(5000000,MD5('x'))--` | | `OR 1=1` | high | `' OR '1'='1'--` | | `AND 1=1` | high | `' AND '1'='1'--` | | `pg_sleep()` | critical | `'; SELECT pg_sleep(5)--` | | `information_schema` | medium | `' UNION SELECT * FROM information_schema.tables--` | | `@@version` | medium | `' UNION SELECT @@version--` | | `LOAD_FILE()` | critical | `' UNION SELECT LOAD_FILE('/etc/passwd')--` | | `INTO OUTFILE` | critical | `' INTO OUTFILE '/tmp/shell.php'--` | | `0xHEX` | medium | `0x7573657273` | | `SLEEP()` | medium | `' OR SLEEP(5)#` | | `DECLARE @` | medium | `; DECLARE @a VARCHAR(100)--` | ### 2. XSS — Cross-Site Scripting (`xss`) 🎯 **30+ 种模式** — 检测反射型、存储型和基于 DOM 的 XSS： | 模式 | 严重程度 | 示例 | |--------|-----------|---------| | `` | | `onload=` | high | `` | | `onerror=` | high | `` | | `onclick=` | high | `