Mayerust/shadowguard

# ShadowGuard — 基于 ML 的 Web 应用防火墙 ## 这是什么 ShadowGuard 是一款 Web 应用防火墙 (WAF)，它结合了**基于确定性规则的检测**与**机器学习异常检测**，以实时识别并阻止常见的 Web 攻击。 与作为黑盒的商业 WAF 不同，ShadowGuard 是从第一性原理构建的——每一个设计决策都有文档记录，每一个组件都是可复现的。 **它能检测的攻击：** SQL 注入 (Union、Boolean 盲注、Time-Based 盲注) · 跨站脚本攻击 (反射型、存储型、DOM 型) · 路径遍历 · 命令注入 · Shellshock · Log4Shell · XXE · SSRF · 空字节注入 · 自动化扫描器流量 ## 架构 流量通过一个**四层检测流水线**。每一层只有在无法做出明确决定时才会调用下一层——干净的请求会提前退出，而不会触及 ML 模型。 ``` Client Request │ ▼ ┌─────────────────────────────────────────────────────┐ │ Nginx (Port 80) │ │ Rate limiting · Security headers · SSL termination │ └───────────────────────┬─────────────────────────────┘ │ proxy_pass ▼ ┌─────────────────────────────────────────────────────┐ │ ShadowGuard WAF (Port 5000) │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ TIER 0 — Safe Pass < 1ms │ │ │ │ Zero attack-surface chars → ALLOW │ │ │ │ ~85% of legitimate traffic exits here │ │ │ └──────────────────┬───────────────────────────┘ │ │ │ if any attack chars present │ │ ┌──────────────────▼───────────────────────────┐ │ │ │ TIER 1 — Hard Block < 3ms │ │ │ │ 25 precision regex rules (OWASP-based) │ │ │ │ Blocks 90%+ of real attacks here │ │ │ └──────────────────┬───────────────────────────┘ │ │ │ if no hard rule triggered │ │ ┌──────────────────▼───────────────────────────┐ │ │ │ TIER 2 — Soft Score < 4ms │ │ │ │ 18 indicators accumulate suspicion points │ │ │ │ Score < 4 → ALLOW (no ML needed) │ │ │ └──────────────────┬───────────────────────────┘ │ │ │ if soft_score ≥ 4 │ │ ┌──────────────────▼───────────────────────────┐ │ │ │ TIER 3 — ML Gate < 20ms │ │ │ │ Random Forest (58 features, F1=0.88) │ │ │ │ Adaptive threshold: 62%–82% │ │ │ │ Handles ambiguous/obfuscated payloads │ │ │ └──────────────────┬───────────────────────────┘ │ │ │ if ALLOWED │ └─────────────────────┼───────────────────────────────┘ ▼ Target Application (Port 8080) ``` **为什么这种设计能防止安全流量的误报：** ML 模型仅在一个请求通过多个弱指标累积了 ≥ 4 个可疑点时才会被调用。像 `q=python+tutorial` 这样的干净搜索查询没有任何攻击面特征，会在第 0 层直接退出，完全不会触及正则表达式或 ML。 ## 功能 ### 检测引擎 - **混合架构**：确定性规则处理已知模式；ML 处理新型、混淆和零日变体 - **四层流水线**：安全通过 (Safe Pass) → 强拦截 (Hard Block) → 软评分 (Soft Score) → ML 门控 (ML Gate) - **自适应 ML 阈值**：置信度要求根据触发的软指标数量进行调整 (62%–82%) - **LRU 缓存**：重复的相同 payload（在自动化扫描中很常见）会被缓存，不会重复调用模型 ### 机器学习核心 - 基于 **HTTP CSIC 2010** 数据集进行训练（真实的电商 HTTP 流量，带标注的攻击） - **58 个安全专用特征**：香农熵、SQL 关键字密度、n-gram SQL 片段、复合攻击评分、编码异常检测等 - **Random Forest** 分类器（在 5 个模型的对比中 F1 得分最高） - **5 折分层交叉验证** + GridSearchCV 超参数调优 - F1 分数：**0.88** · AUC-ROC：**0.94** · 召回率：**0.91** (能捕获 91% 的攻击) ### 运维功能 - **自动 IP 黑名单**：触发 5 次以上攻击的 IP 将被封禁 5 分钟 - **速率限制**：每个 IP 10 秒内 30 个请求 → HTTP 429 - **结构化 JSON 日志** (`logs/events.ndjson`) — 可直接导入 Splunk/ELK SIEM - **实时仪表盘**，提供实时请求流、攻击类型细分、层级统计 - **仪表盘 HTTP 基本认证**（可通过环境变量配置） - **反向代理模式**：透明地部署在任何 Web 应用前面 ### 部署 - **完整的 Docker Compose 技术栈**：一条命令启动 Nginx + ShadowGuard + 目标应用 - **容器安全加固**：非 root 用户、移除 capabilities、禁止权限提升 (no-new-privileges) - **局域网可用**：执行 `docker-compose up` 后，同一网络中的任何设备均可访问 ## 模型性能 基于 CSIC 2010 HTTP 数据集进行训练（10,000 个正常样本 + 10,000 个攻击样本，数据均衡）。 | 指标 | 得分 | |--------|-------| | F1 分数 | **0.88** | | AUC-ROC | **0.94** | | 召回率 (攻击检测率) | **0.91** | | 精确率 | **0.86** | | 误报率 | ~9% (被 ML 错误标记为攻击的安全请求) | **按重要性排名的主要特征：** 1. `composite_attack_score` — 手工构建的所有攻击信号组合 2. `sql_keyword_density` — 每个字符包含的 SQL 关键字比例（用于捕获隐藏的注入） 3. `entropy` / `url_entropy` — 指示混淆的随机性 4. `sql_ngram_hits` — 用于捕获 `UN/**/ION SE/**/LECT` 变体的 n-gram 片段 5. `has_union_select`, `has_tautology` — 结构性 SQL 攻击指标 ## 快速开始 ### 前置条件 - Python 3.10+ - Docker + Docker Compose（用于生产部署） - Git ### 选项 A — Docker（推荐，支持局域网） ``` # 1. Clone 仓库 git clone https://github.com/Mayerust/ShadowGuard.git cd ShadowGuard # 2. 首先训练模型（在 Docker 构建前必须执行） python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt python 01_prepare_dataset.py python 02_train_model.py # 这会创建 models/ — WAF 容器所需 # 3. 启动完整技术栈（Nginx → WAF → 目标应用） docker-compose up --build # 4. 在浏览器中打开 # Dashboard: http://localhost/dashboard (admin / admin) # Demo: http://localhost/demo # 局域网: http://YOUR_LAN_IP/dashboard ``` ### 选项 B — 开发模式（无 Docker） ``` # 终端 1 python target_app.py # Vulnerable app on :8080 # 终端 2 python app.py # WAF on :5000 # 打开: http://localhost:5000/demo ``` ### 环境变量 ``` # 复制并编辑 cp .env.example .env ``` | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `TARGET_APP_URL` | `http://localhost:8080` | 受保护应用的 URL | | `DASH_USER` | `admin` | 仪表盘用户名 | | `DASH_PASS` | `admin` | 仪表盘密码 | ## 训练你自己的模型 训练流水线是完全可复现的。请按以下顺序运行： ``` # 步骤 1 — 准备 dataset # 下载 CSIC 2010，如果文件缺失则使用合成回退数据 python 01_prepare_dataset.py # 步骤 2 — 训练与评估 # 比较 5 个模型，运行 5 折 CV，调优胜出者，保存 .pkl python 02_train_model.py # 输出: # models/shadowguard_model.pkl ← 序列化模型（不在仓库中） # models/feature_columns.json ← 特征列表（不在仓库中） # models/training_report.json ← 指标 + 混淆矩阵 # models/training_report.png ← 图表 ``` **数据集来源 (CSIC 2010)：** ``` # 选项 A — 官方 wget http://www.isi.csic.es/dataset/http_dataset_csic_2010.zip unzip http_dataset_csic_2010.zip -d data/raw/ # 选项 B — Kaggle 镜像 kaggle datasets download -d kukurupupu/http-csic-2010-http-dataset unzip *.zip -d data/raw/ # 如果两者均无效：01_prepare_dataset.py 会自动生成合成数据 ``` ## API 参考 所有端点均位于 `http://localhost:5000`。 ### `POST /api/analyze` 通过完整的 WAF 流水线分析 payload 字符串。 ``` curl -X POST http://localhost:5000/api/analyze \ -H "Content-Type: application/json" \ -d '{"payload": "'\'' OR '\''1'\''='\''1", "url": "/login", "method": "POST"}' ``` **响应：** ``` { "action": "BLOCKED", "attack_type": "SQL Injection", "attack_category": "sqli", "severity": "Critical", "risk_score": 97, "detection_tier": 1, "triggered_rule": "SQLi – Tautology (quote)", "ml_confidence": 0.0, "soft_score": 0, "latency_ms": 1.2, "recommendations": ["Use parameterized queries...", "..."] } ``` ### `GET /api/stats` 实时统计数据——拦截率、热门攻击类型、ML 调用率、层级细分。 ### `GET /api/logs?n=50` 按时间倒序获取最后 N 条请求日志。 ### `GET /api/health` WAF 健康检查——模型状态、架构描述、被封禁的 IP 数量。 ### `GET /api/model_stats` ML 专用指标——调用率、平均置信度、缓存统计。 ## 局域网测试 请参阅 **[GUIDE.md](GUIDE.md)** 获取完整的局域网攻击测试演练指南，包括： - 直接局域网网线连接设置（无需路由器） - Windows 和 Kali Linux 上的静态 IP 配置 - 从攻击者机器运行攻击测试套件 - 对运行中的 WAF 使用 sqlmap、Nikto 和 Burp Suite - 实时解读仪表盘结果 ``` # 从攻击机（机器 B）发起 python lan_attack_test.py --target 192.168.1.1 --port 80 --mode full ``` ## 项目结构 ``` ShadowGuard/ ├── 01_prepare_dataset.py ← Feature engineering + SMOTE pipeline ├── 02_train_model.py ← Model training, CV, tuning ├── lan_attack_test.py ← LAN attack test suite ├── Dockerfile ← Container build (non-root, hardened) ├── docker-compose.yml ← Full stack: Nginx + WAF + Target ├── nginx/nginx.conf ← Reverse proxy + security headers ├── requirements.txt ← Python dependencies ├── README.md ← This file ├── GUIDE.md ← LAN testing walkthrough ├── .env.example ← Environment variable template │ ├── templates/ ← HTML frontend │ ├── dashboard.html ← Live threat dashboard │ └── demo.html ← Interactive WAF demo │ ├── models/ ← NOT in repo (trained locally) │ ├── shadowguard_model.pkl │ ├── feature_columns.json │ └── training_report.json │ ├── data/ ← NOT in repo (dataset files) │ ├── raw/ ← CSIC 2010 .txt files │ └── processed/ ← Generated CSVs │ └── logs/ ← NOT in repo (runtime logs) ├── shadowguard.log └── events.ndjson ← SIEM-ready structured log ``` ## 技术栈 | 层级 | 技术 | 用途 | |-------|-----------|---------| | 入口 | Nginx | 反向代理、速率限制、SSL 终结 | | WAF 引擎 | Python + Flask | 请求检测流水线 | | ML 模型 | Scikit-learn (Random Forest) | 异常检测 | | 特征工程 | NumPy + Regex | 从原始 HTTP 中提取 58 个安全特征 | | 数据集 | CSIC 2010 HTTP | 带标签的 Web 攻击流量 | | 数据均衡 | imbalanced-learn (SMOTE) | 处理类别不平衡 | | 容器化 | Docker Compose | 可复现的部署 | | 仪表盘 | Vanilla JS + Chart.js | 实时可视化 | ## 局限性与未来工作 - **数据集范围**：基于 CSIC 2010（2010 年代的电商流量）进行训练。在此日期之后出现的新型攻击模式可能不在训练分布范围内。 - **HTTPS 检测**：目前在 Nginx 处执行 SSL 终结。对加密请求体的深度检测需要 WAF 持有服务器的私钥。 - **无模型重训流水线**：尚未实现基于仪表盘误报报告的主动学习/反馈循环。 - **IPv6**：速率限制和黑名单功能目前仅适用于 IPv4。 **计划中：** - [ ] 基于 LSTM 的序列模型，用于检测缓慢/分布式攻击 - [ ] IP 信誉源集成 (AbuseIPDB) - [ ] 用于 Grafana 仪表盘的 Prometheus 指标端点 - [ ] 主动学习：管理员标记的误报用于重新训练模型 ## 许可证 MIT — 详见 [LICENSE](LICENSE)

标签：AMSI绕过, Apex, AppImage, CISA项目, CSIC 2010, Docker, Docker Compose, DOE合作, Flask, IP 地址批量处理, Log4Shell防御, MIT开源许可, Nginx, Python, Shellshock防御, SQL注入防御, SSRF防御, WAF, Web安全, Web应用防火墙, XSS跨站脚本防御, XXE防御, 云计算, 反向代理, 命令注入防御, 威胁情报, 威胁检测, 安全仪表盘, 安全网关, 安全防御评估, 开发者工具, 异常检测, 攻击拦截, 无后门, 机器学习, 流量清洗, 深度包检测, 混合检测, 版权保护, 生产级, 网络安全, 网络安全分析, 自动化扫描器防御, 蓝队分析, 规则引擎, 请求拦截, 路径遍历防御, 逆向工具, 随机森林, 隐私保护, 零日漏洞防护