khoilv2005/An-Explainable-Hybrid-WAF

# WebGuard：使用基于 Attention 的 CNN-BiLSTM 的可解释混合 WAF，用于规避性攻击检测 [](https://python.org) [](https://fastapi.tiangolo.com) [](https://docker.com) [](https://mysql.com) [](LICENSE) **WebGuard** 是一个 **Web 应用防火墙 (WAF)**，它将基于规则的检测与**深度学习**（基于 Attention 的 CNN-BiLSTM）相结合，以检测 Web 攻击，包括规避性攻击。该系统集成了 **LIME XAI** 以实现可解释的决策制定。 ### 项目贡献 **Le Van Khoi：** WebGuard 架构、混合规则/ML 检测、可解释性集成以及安全强化。 **[Tiếng Việt](README.vi.md)** ## 目录 - [特性](#-features) - [系统架构](#-system-architecture) - [安装说明](#-installation) - [配置](#-configuration) - [使用方法](#-usage) - [API Endpoints](#-api-endpoints) - [管理面板](#-admin-panel) - [深度学习](#-deep-learning) - [项目结构](#-project-structure) ## 特性 ### 基于规则的检测 - **SQL Injection** - 检测常见的 SQL 注入模式 - **XSS (跨站脚本攻击)** - 拦截恶意脚本 - **目录遍历** - 防止未经授权的目录访问 - **命令注入** - 检测 shell 命令注入 - **IP 黑名单** - 自动封锁多次违规的 IP ### 深度学习检测 - **深度学习模型** - 带有 Attention 机制的 PyTorch 模型 - **ONNX Runtime** - 通过 ONNX 优化实现快速推理 - **LIME XAI** - 解释攻击检测决策 - **字符级 Tokenization** - 检测混淆的 payload ### 管理面板 - **仪表盘** - 实时活动监控 - **规则管理** - 添加/编辑/删除规则 - **IP 黑名单** - 管理被封锁的 IP 地址 - **活动日志** - 分页查看请求历史 ## 系统架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ │ │ Client │────▶│ WAF Proxy │────▶│ Backend App │ │ │ │ (Port 8080) │ │ (Your App) │ └─────────────────┘ └────────┬────────┘ └─────────────────┘ │ ┌────────────┼────────────┐ │ │ │ ┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐ │ Rule │ │ ML │ │ MySQL │ │ Engine │ │ Engine │ │ Database │ └───────────┘ └─────────┘ └───────────┘ │ ┌─────────▼─────────┐ │ Admin Panel │ │ (Port 5000) │ └───────────────────┘ ``` ## 安装说明 ### 前置条件 - **Docker** & **Docker Compose** - **Git** ### 步骤 1：克隆仓库 ``` git clone cd An-Explainable-Hybrid-WAF ``` ### 步骤 2：配置环境 ``` cp .env.example .env ``` 根据需要编辑 `.env` 文件（参见[配置](#-configuration)）。 ### 步骤 3：使用 Docker Compose 运行 ``` docker-compose up -d ``` ### 步骤 4：验证服务 ``` # 检查正在运行的 containers docker-compose ps # 查看 logs docker-compose logs -f waf_app docker-compose logs -f waf_admin ``` ## 配置 ### `.env` 文件 | 变量 | 描述 | 默认值 | |----------|-------------|---------------| | `MYSQL_ROOT_PASSWORD` | MySQL root 密码 | 必须在 `.env` 中设置 | | `MYSQL_DATABASE` | 数据库名称 | `wafdb` | | `MYSQL_USER` | MySQL 用户名 | `waf` | | `MYSQL_PASSWORD` | MySQL 密码 | 必须在 `.env` 中设置 | | `WAF_LISTEN_PORT` | WAF 监听端口 | `8080` | | `WAF_BACKEND_ADDRESS` | 后端应用地址 | `http://host.docker.internal:8888` | | `WAF_BLOCK_THRESHOLD` | IP 封锁阈值 | `100000` | | `WAF_ML_ENABLED` | 启用/禁用 ML 检测 | `true` | | `WAF_ML_CONFIDENCE_THRESHOLD` | ML 置信度阈值 | `0.5` | | `WAF_ML_LIME_ENABLED` | 启用/禁用 LIME XAI | `false` | | `ADMIN_LISTEN_PORT` | 管理面板端口 | `5000` | | `ADMIN_SECRET_KEY` | Flask 密钥 | 必须设置为随机值 | | `ADMIN_ALLOWED_IPS` | 允许的 IP 列表 | `127.0.0.1,::1` | ### ML 配置 ``` # 启用 ML 检测 WAF_ML_ENABLED=true # 置信度阈值 (0.0 - 1.0) # 越低 = 越敏感，越高 = 误报越少 WAF_ML_CONFIDENCE_THRESHOLD=0.5 # 启用 LIME 解释（影响性能） WAF_ML_LIME_ENABLED=false ``` ## 使用方法 ### 访问服务 | 服务 | URL | 描述 | |---------|-----|-------------| | **WAF Proxy** | `http://localhost:8080` | WAF 反向代理 | | **管理面板** | `http://localhost:5000` | WAF 管理 | | **MySQL** | `localhost:3306` | 数据库 | ### 使用 curl 测试 WAF ``` # 有效的请求 curl http://localhost:8080/ # 测试 SQL Injection（将被拦截） curl "http://localhost:8080/?id=1' OR '1'='1" # 测试 XSS（将被拦截） curl "http://localhost:8080/?q=" # 测试 Path Traversal（将被拦截） curl "http://localhost:8080/../../../etc/passwd" ``` ## API Endpoints ### WAF 应用（端口 8080） | Endpoint | 方法 | 描述 | |----------|--------|-------------| | `/{path:path}` | ALL | 到后端的反向代理 | | `/health` | GET | 健康检查 endpoint | | `/reset-db-management` | POST | 从数据库重新加载规则 | ### 管理面板（端口 5000） | Endpoint | 方法 | 描述 | |----------|--------|-------------| | `/` | GET | 主仪表盘 | | `/api/logs/latest` | GET | 获取日志 API (AJAX) | | `/rules` | GET | 查看规则列表 | | `/rules/add` | GET, POST | 添加新规则 | | `/rules/delete/` | POST | 删除规则 | | `/rules/delete-all` | POST | 删除所有规则 | | `/rules/import` | POST | 从 JSON 导入规则 | | `/blacklist` | GET | 查看 IP 黑名单 | | `/blacklist/remove/` | POST | 从黑名单中移除 IP | | `/reset-all` | POST | 重置所有数据 | ## 管理面板 ### 仪表盘 - 查看总体统计数据（总请求数、已拦截、已放行） - 自动刷新的实时活动日志 - 分析图表 ### 规则管理 - 添加/编辑/删除规则 - 从 JSON 文件导入规则 - 按类型分类：SQLi、XSS、目录遍历等。 ### IP 黑名单 - 查看被封锁的 IP 列表 - 从黑名单中移除 IP - 查看触发拦截的规则 ## 深度学习 ### 概述 该系统使用由 **PyTorch** 构建的自定义**深度学习**模型，结合了多种先进技术以实现高准确率的 Web 攻击检测。 ### 模型架构：WAF_Attention_Model ``` ┌─────────────────────────────────────────────────────────────────┐ │ INPUT (Character-level) │ │ Max Length: 500 characters │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ EMBEDDING LAYER │ │ Vocab Size → Embedding Dim (128) │ │ + Dropout (0.1) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ CNN FEATURE EXTRACTION │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ ResBlock 1 │→ │ ResBlock 2 │→ │ ResBlock 3 │ │ │ │ 128 → 128 │ │ 128 → 256 │ │ 256 → 256 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ + Squeeze-and-Excitation (SE) Attention │ │ + MaxPool + Dropout │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ MULTI-HEAD SELF-ATTENTION │ │ 8 Attention Heads │ │ + Layer Normalization │ │ + Residual Connections │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ BI-DIRECTIONAL LSTM │ │ 2 Layers, 256 Hidden │ │ + Attention Pooling │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ CLASSIFICATION HEAD │ │ Dense(512→256) → GELU → Dense(256→128) → Dense(128→1) │ │ + Layer Norm + Dropout │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ OUTPUT │ │ Sigmoid → Probability (0: Normal, 1: Attack) │ └─────────────────────────────────────────────────────────────────┘ ``` ### 关键组件 | 组件 | 描述 | |-----------|-------------| | **Multi-Head Self-Attention** | 8 个头，用于捕获 payload 中字符之间的关系 | | **残差块** | 跳跃连接，用于高效的深度网络训练 | | **SE Block (Squeeze-Excitation)** | 通道注意力机制，用于聚焦重要特征 | | **Bi-LSTM** | 从序列的两个方向捕获上下文 | | **GELU 激活函数** | 平滑的激活函数，比 ReLU 更有效 | | **Layer Normalization** | 稳定训练并加速收敛 | ### 训练 Pipeline | 技术 | 详情 | |-----------|---------| | **损失函数** | Focal Loss (α=0.25, γ=2.0) - 处理类别不平衡问题 | | **优化器** | 带有权重衰减的 AdamW | | **Label Smoothing** | 0.1 - 帮助模型更好地泛化 | | **Tokenization** | 字符级 - 检测 payload 混淆 | | **混合精度** | FP16 训练以实现更快的速度 | ### ONNX 优化 模型被导出为 **ONNX** 格式，以便在生产环境中实现更快的推理： ``` # 使用 ONNX Runtime 进行推理 ML_FORCE_ONNX=true ML_MODEL_ONNX_PATH=/app/models/waf_model.onnx ``` | 指标 | PyTorch | ONNX Runtime | |--------|---------|--------------| | **延迟** | ~15ms | ~3ms | | **内存** | ~500MB | ~150MB | | **吞吐量** | ~65 req/s | ~300 req/s | ### 使用 LIME 的可解释 AI (XAI) 当 `WAF_ML_LIME_ENABLED=true` 时，系统会使用 **LIME（局部可解释的模型不可知解释）** 来： 1. **解释决策** - 突出显示对预测有贡献的 token 2. **检测模式** - 自动检测 SQL、XSS、命令注入模式 3. **调试与审计** - 记录详细的拦截原因日志 ``` Example LIME Output: ───────────────────────────────────── Request: /search?q=1' OR '1'='1 Prediction: ATTACK (confidence: 0.98) Top contributing tokens: [+0.45] OR [+0.32] '1'='1 [+0.21] ' ───────────────────────────────────── ``` ### 文件与模型 | 文件 | 大小 | 描述 | |------|------|-------------| | `waf_model.onnx` | ~15MB | 用于生产环境的 ONNX 模型 | | `waf_model.pth` | ~15MB | PyTorch checkpoint | | `tokenizer_word_index.json` | ~1KB | 字符词汇表 | | `model.py` | - | 模型架构定义 | | `train.py` | - | 训练脚本 | | `preprocess.py` | - | 数据预处理 | ### 深度学习配置 ``` # 启用/禁用 Deep Learning 检测 WAF_ML_ENABLED=true # 置信度阈值 (0.0 - 1.0) # 越高 = 误报越少，越低 = 检测到的越多 WAF_ML_CONFIDENCE_THRESHOLD=0.5 # 启用 LIME 解释（增加约 100ms 延迟） WAF_ML_LIME_ENABLED=false # 强制使用 ONNX（推荐用于生产环境） ML_FORCE_ONNX=true ``` ## 项目结构 ``` An-Explainable-Hybrid-WAF/ ├── WAF_app/ # WAF Application │ ├── main.py # FastAPI reverse proxy │ ├── ml_predictor.py # ML inference engine │ ├── decoder.py # URL/HTML decoder │ ├── Dockerfile │ └── models/ # ML models │ ├── waf_model.onnx │ └── tokenizer_word_index.json │ ├── WAF_admin/ # Admin Panel │ ├── main.py # Flask application │ ├── Dockerfile │ └── templates/ # HTML templates │ └── admin_dashboard.html │ ├── shared/ # Shared code │ ├── models.py # SQLAlchemy models │ └── database.py # Database connection │ ├── rules/ # WAF rules │ └── complete_rules_import.json │ ├── docker-compose.yml # Docker Compose config ├── requirements.txt # Python dependencies ├── .env.example # Environment template └── README.md # This file ``` ## 数据库 Schema ### 表 | 表 | 描述 | |-------|-------------| | `rules` | WAF 规则 | | `ip_blacklist` | 被封锁的 IP 列表 | | `activity_log` | 活动日志 | ### 规则结构 ``` { "id": 1, "enabled": true, "description": "SQL Injection - Basic", "category": "SQLi", "severity": "HIGH", "target": "REQUEST_URI", "operator": "rx", "value": "(?i)(union\\s+select|select.*from)", "action": "BLOCK" } ``` ## Docker 命令 ``` # 启动服务 docker-compose up -d # 停止服务 docker-compose down # 查看 logs docker-compose logs -f # 重建 containers docker-compose up -d --build # 访问 container docker exec -it waf_app bash docker exec -it waf_admin bash docker exec -it waf_mysql mysql -u waf -p ``` ## 许可证 MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。 ## 贡献者 - **Le Van Khoi** (khoakim09@gmail.com / 23520770@gmail.com) ## 致谢 - [FastAPI](https://fastapi.tiangolo.com/) - 现代的 Python Web 框架 - [Flask](https://flask.palletsprojects.com/) - 轻量级的 Python Web 框架 - [ONNX Runtime](https://onnxruntime.ai/) - 高性能推理 - [LIME](https://github.com/marcotcr/lime) - 可解释 AI - [SQLAlchemy](https://www.sqlalchemy.org/) - Python SQL 工具包 - [PyTorch](https://pytorch.org/) - 深度学习框架

标签：AppImage, CISA项目, DOE合作, SQL注入防护, Web应用防火墙, XSS防护, 凭据扫描, 可解释AI, 安全防护, 深度学习, 请求拦截, 逆向工具