hoangtuvungcao/mango-waf
GitHub: hoangtuvungcao/mango-waf
一款基于 Go 语言的高性能七层 DDoS 防护与 Web 应用防火墙，支持 XDP/eBPF 加速、P2P 集群同步及实时监控仪表盘。
Stars: 58 | Forks: 15
# 🥭 Mango Shield v2.0
## 📋 目录
1. [概述](#-tổng-quan)
2. [从头安装（新 VPS）](#-cài-đặt-từ-đầu-vps-mới)
3. [多域名配置](#-cấu-hình-nhiều-domain)
4. [防护模式](#️-các-chế-độ-bảo-vệ)
5. [CLI 管理](#-quản-lý-bằng-cli)
6. [仪表盘](#-dashboard)
7. [详细配置](#️-cấu-hình-chi-tiết)
8. [项目结构](#-cấu-trúc-dự-án)
9. [API Endpoints](#-api-endpoints)
10. [WAF Rules](#-waf-rules)
11. [Telegram 告警](#-cảnh-báo-telegram)
12. [Docker](#-docker)
13. [故障排除](#-xử-lý-sự-cố)
Mango Shield 利用先进的 **多层防御** 模型保护您的网站免受 DDoS Layer 7 攻击：
```
Người dùng → [Mango Shield] → Website gốc (Backend)
Lớp 0: XDP/eBPF Acceleration (Lớp 4) — Chặn IP ở tầng nhân/phần cứng (10M RPS)
Lớp 1: TLS Early Reject (Lớp 7 sớm) — Ngắt kết nối Botnet trước khi giải mã HTTPS
Lớp 2: TLS Fingerprint (JA3/JA4) — Nhận dạng và chấm điểm mức độ tin cậy của Client
Lớp 3: Tình báo IP & Reputation — GeoIP, ASN, Threat Feeds (50k+ IP xấu)
Lớp 4: WAF (Layer 7) — Chặn SQLi, XSS, LFI, RCE (Core 28 OWASP Rules)
Lớp 5: Thử thách JS PoW — Xác minh người dùng thật, không cần CAPTCHA ngoài
Lớp 6: Phân tích Hành vi (Behavior) — AI tự động nhận diện mẫu tấn công mới
Lớp 7: Học thích ứng & Thoái giáng — Tự duy trì dịch vụ khi bị overload
Lớp 8: Smart CDN Caching — Đệm nội dung tĩnh trên RAM (Ristretto) tăng tốc cực nhanh
Lớp 9: Upstream Load Balancing — Rải tải thông minh (Round-Robin) tới nhiều Backend
Lớp 10: Mango P2P Mesh — Đồng bộ Danh sách đen (Ban/Whitelist) giữa các Node không cần Redis
```
**支持：**
- ✅ HTTP & HTTPS
- ✅ 裸 IP & 域名
- ✅ 多域名 → 不同的后端 (Load Balancing)
- ✅ WebSocket pass-through
- ✅ Let's Encrypt (说明见下文)
- ✅ **CDN Smart Caching** (仅缓存静态文件，对所有网站安全)
- ✅ **Gossip Protocol Cluster** (运行多 VPS 集群，无需配置数据库)
- ✅ 支持 Docker 和 CI/CD 的环境变量 (`viper`)
## 🚀 从头安装（新 VPS）
### 步骤 1：安装 Go（如果尚未安装）
```
# Ubuntu/Debian
sudo apt update && sudo apt install -y golang-go git
# 或安装最新版 Go
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
# 检查
go version
```
### 步骤 2：下载源代码
```
# 从 GitHub Clone
git clone https://github.com/hoangtuvungcao/mango-waf.git /opt/mango-shield
# 或从本地上传
# scp -r mango-waf/ root@YOUR_VPS_IP:/opt/mango-shield/
```
### 步骤 3：系统优化（推荐用于大规模 DDoS）
```
cd /opt/mango-shield
# 1. 优化 Linux TCP Stack (扩展文件描述符，优化 socket)
chmod +x scripts/optimize_tcp.sh
sudo ./scripts/optimize_tcp.sh
# 2. 安装 XDP/eBPF (支持拦截 100 万 RPS - 需要 Linux 5.10+)
chmod +x xdp/setup_xdp.sh
sudo ./xdp/setup_xdp.sh
```
### 步骤 4：编译
```
# 编译主服务器
go build -o mango-shield .
# 编译管理 CLI
go build -o mango-cli ./cmd/cli/
# 检查
./mango-shield -version
```
### 步骤 4：创建配置文件
```
# 复制样本文件
cp config/default.yaml config/config.yaml
# 编辑配置（查看下方“配置多域名”部分）
nano config/config.yaml
```
### 步骤 5：试运行
```
# 直接运行以测试（Ctrl+C 停止）
./mango-shield -config config/config.yaml
```
### 步骤 6：安装 systemd 服务（生产环境）
```
# 复制 service 文件
sudo cp deploy/mango-shield.service /etc/systemd/system/
# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable mango-shield
sudo systemctl start mango-shield
# 检查状态
sudo systemctl status mango-shield
# 查看实时日志
sudo journalctl -u mango-shield -f
```
### 步骤 7：开放防火墙
```
# UFW (Ubuntu)
sudo ufw allow 80/tcp # HTTP
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow 9090/tcp # Dashboard (nên giới hạn IP truy cập)
# 或 iptables
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 9090 -j ACCEPT
```
## 🌐 多域名配置
### 工作原理
```
┌─ example.com ───────→ backend :8080 (Web chính)
│
Client → Mango ───────┼─ api.example.com ──→ backend :3000 (API server)
Shield (port 80/443) │
├─ khachhang-a.com ──→ backend :8081 (Khách A)
│
└─ khachhang-b.com ──→ backend :8082 (Khách B)
```
Mango Shield 从 `Host` header 自动识别域名并将其转发到正确的后端。
### 示例 1：一个域名，一个后端
```
# 最简单 — 1 个网站
domains:
- name: "example.com"
upstreams:
- url: "http://127.0.0.1:8080"
```
### 示例 2：多域名 → 多后端（供多用户使用）
```
# 每个域名/客户有独立 backend
domains:
# Website chính của bạn
- name: "example.com"
upstreams:
- url: "http://127.0.0.1:8080"
# API server
- name: "api.example.com"
upstreams:
- url: "http://127.0.0.1:3000"
# Website khách hàng A
- name: "khachhang-a.com"
upstreams:
- url: "http://127.0.0.1:8081"
```
### 示例 3：Load Balancing（多后端负载均衡）
```
# 负载均衡到多个 backend (自动 Round-Robin)
domains:
- name: "web.example.com"
upstreams:
- url: "http://localhost:8080" # Server A
- url: "http://localhost:8081" # Server B
- url: "http://10.0.0.5:8080" # Server Mạng nội bộ
```
### 示例 4：裸 IP（暂无域名）
```
tls:
enabled: false # Không dùng HTTPS khi dùng IP trần
domains:
- name: "103.77.246.172"
upstreams:
- url: "http://127.0.0.1:8080"
```
### 示例 5：使用 Let's Encrypt 的 HTTPS（生产环境）
```
# 1. 安装 certbot
sudo apt install certbot
# 2. 暂停 Mango Shield (certbot 需要 80 端口)
sudo systemctl stop mango-shield
# 3. 获取证书
sudo certbot certonly --standalone \
-d example.com \
-d api.example.com \
-d khachhang-a.com
# 4. 在 config.yaml 中配置 TLS:
```
```
tls:
enabled: true
cert_file: "/etc/letsencrypt/live/example.com/fullchain.pem"
key_file: "/etc/letsencrypt/live/example.com/privkey.pem"
```
```
# 5. 重启
sudo systemctl start mango-shield
# 6. 自动续期证书 (cron job)
echo "0 3 * * * certbot renew --pre-hook 'systemctl stop mango-shield' --post-hook 'systemctl start mango-shield'" | sudo tee -a /etc/crontab
```
### 自动模式（推荐）
系统根据 10 层防护自动对 IP 进行评分。
- **无缝模式：** 如果您是真实用户，系统将立即放行，不显示任何提示。
- **JS Challenge：** 仅当该 IP 的 RPS 升高或指纹有可疑迹象 时才启用。
- **CAPTCHA：** 仅在确凿证据表明遭受持续攻击（强力 DDoS）时出现。
## 🕸️ 多服务器集群
为了抵御大规模 DDoS 攻击，Mango Shield 允许将多个 VPS 连接成一个同步的 Mesh 网络。
### 1. 黑名单同步
当节点 A 封禁一个 IP 时，节点 B 和 C 将立即自动封禁该 IP，无需中央数据库。
### 2. 会话共享
如果用户在节点 A 已通过验证，当他们切换到节点 B（由于 DNS Round-Robin）时，**无需重新完成 challenge**。这要求配置文件中的 `cookie_secret` 在所有节点上必须完全一致。
### 3. Mesh 配置 (P2P Gossip)
在所有 VPS 上打开端口 `7946`（TCP 和 UDP），以便它们能够相互“通信”。
```
cluster:
enabled: true
node_name: "vps-1"
bind_port: 7946
advertise_ip: "103.77.246.172"
secret_key: "AES-32-KHOA-CUA-RIENG-BAN-!!" # Giống nhau mọi Node
join_peers: ["IP_CUA_NODE_DA_CO:7946"]
```
# === 识别 ===
fingerprint:
ja3:
enabled: true
ja4:
enabled: true
http2:
enabled: true
# === 情报 ===
intelligence:
geoip:
enabled: true
db_path: "/etc/mango/GeoLite2-City.mmdb"
blocked_countries: [] # 例如：["CN","RU"]
ip_reputation:
enabled: true
abuseipdb_key: "YOUR_KEY" # https://abuseipdb.com/register
asn:
enabled: true
# === 检测 ===
detection:
baseline:
enabled: true
learning_period: 24h
anomaly:
enabled: true
sensitivity: 0.7
bot_classifier:
enabled: true
# === WAF ===
waf:
enabled: true
owasp_rules: true
paranoia_level: 2 # 1=基础, 2=标准, 3=严格
# === 日志 ===
logging:
level: "info"
format: "json"
file: "/var/log/mango-shield.log"
# === 仪表盘 ===
dashboard:
enabled: true
listen: "127.0.0.1:9090"
username: "admin"
password: "strongpassword123"
# === 告警 ===
alerts:
telegram:
enabled: true
token: "BOT_TOKEN" # 来自 @BotFather
chat_id: "CHAT_ID" # 来自 @userinfobot
discord:
enabled: false
webhook_url: ""
```
### 重载配置（不重启）
```bash
kill -HUP $(pidof mango-shield)
```
## 📁 项目结构
```
mango-waf/
├── scripts/ # TỐI ƯU HỆ THỐNG
│ └── optimize_tcp.sh # Script tối ưu Sysctl cho High Concurrency
├── xdp/ # LỚP PHÒNG THỦ CỨNG
│ ├── mango_xdp.c # Mã nguồn C (eBPF)
│ ├── setup_xdp.sh # Script cài đặt compiler & nạp XDP
│ └── SETUP_XDP.md # Hướng dẫn chi tiết XDP
├── main.go # Điểm vào — khởi tạo 10 hệ con
├── cmd/cli/main.go # CLI quản lý (tiếng Việt)
│
├── config/
│ ├── config.go # Tải YAML, hot-reload, validate
│ └── deploy.yaml # Cấu hình mẫu cho VPS
│
├── core/ # LÕI HỆ THỐNG
│ ├── server.go # TLS server, xử lý HTTP
│ ├── pipeline.go # Pipeline bảo vệ đa tầng
│ ├── xdp.go # Go manager cho eBPF Maps
│ ├── proxy.go # Reverse proxy, WebSocket
│ ├── challenge.go # Thử thách JS/CAPTCHA
│ └── alerts.go # Telegram/Discord/Webhook alerts
│
├── fingerprint/ # NHẬN DẠNG TRÌNH DUYỆT
│ ├── fingerprint.go # Kiểu dữ liệu, chấm điểm
│ ├── early_reject.go # SSL Sniffing & Early Drop logic
│ ├── tls_parser.go # Phân tích TLS ClientHello
│ ├── h2_parser.go # Phân tích HTTP/2 frames
│ ├── database.go # 100+ fingerprint Botnet & Browser
│ ├── interceptor.go # Chặn kết nối TLS StdLib
│ └── silent_js.go # Nhận dạng trình duyệt ẩn
│
├── intelligence/ # TÌNH BÁO IP
│ ├── intelligence.go # Engine đánh giá 5 lớp
│ ├── reputation.go # AbuseIPDB API
│ ├── asn.go # Phân loại nhà mạng (70+)
│ └── feeds.go # 8 nguồn dữ liệu mối đe dọa
│
├── detection/ # PHÁT HIỆN TẤN CÔNG
│ ├── detection.go # Baseline & anomaly
│ ├── behavior.go # Hành vi 6 yếu tố
│ ├── classifier.go # Phân loại bot (13 chữ ký)
│ ├── signatures.go # 10 mẫu tấn công
│ └── adaptive.go # Tự học traffic 24h
│
├── challenge/ # THỬ THÁCH v2
│ ├── challenge.go # Manager PoW/Turnstile/reCAPTCHA
│ └── templates.go # Template UI glassmorphism
│
├── rules/ # WAF ENGINE
│ ├── engine.go # Rules engine, inspector
│ ├── owasp.go # 28 rule OWASP CRS
│ └── custom.go # Tải rule tùy chỉnh YAML
│
├── api/
│ └── dashboard.go # REST API + dashboard nhúng
│
├── perf/ # HIỆU SUẤT
│ ├── pool.go # Rate limiter, memory manager
│ └── hardening.go # Header bảo mật, thoái giáng
│
├── logger/
│ └── logger.go # Ghi log có cấu trúc (zap)
│
├── deploy/
│ └── mango-shield.service # Systemd service
├── Dockerfile # Docker multi-stage
└── docker-compose.yml # Docker Compose
```
## 🕸️ 安装多服务器集群
为了抵御大规模 DDoS 攻击（超过单个 VPS 的 10Gbps 带宽限制），您可以在多个不同的服务器上运行 Mango Shield。**Mango Mesh** 功能将通过 Gossip 协议连接它们（无需 Redis！）。
当 **VPS 1 (河内)** 封禁 IP `1.2.3.4` 时，它会立即通知 **VPS 2 (胡志明市)** 和 **VPS 3 (新加坡)** 在几毫秒内进行封禁。
### 步骤 1：开放 P2P 通信端口
在**所有** VPS 上，您必须为 `TCP` 和 `UDP` 开放端口 `7946`：
```
sudo ufw allow 7946/udp
sudo ufw allow 7946/tcp
```
### 步骤 2：配置 VPS 1（主服务器 - 锚节点）
例如 VPS 1 的 IP 是 `103.77.246.172`。编辑文件 `config/deploy.yaml`：
```
cluster:
enabled: true
node_name: "vps-1-hanoi"
bind_port: 7946
advertise_ip: "103.77.246.172" # BẮT BUỘC để báo hệ thống biết IP Public thực sự
secret_key: "VUI_LONG_DOI_KHOA_BAO_MAT_NAY_THANH_32_BYTE!" # BẮT BUỘC ĐÚNG 32 BYTE & GIỐNG NHAU MỌI VPS
join_peers: [] # Node đầu tiên làm mỏ neo nên không cần nối tới ai
```
### 步骤 3：配置 VPS 2（辅助服务器 1）
例如 VPS 2 的 IP 是 `103.77.246.153`。编辑文件 `config/deploy.yaml`：
```
cluster:
enabled: true
node_name: "vps-2-hcm"
bind_port: 7946
advertise_ip: "103.77.246.153"
secret_key: "VUI_LONG_DOI_KHOA_BAO_MAT_NAY_THANH_32_BYTE!" # Phải y hệt VPS 1 (32 Byte)
join_peers:
- "103.77.246.172:7946" # Trỏ về IP của VPS 1 để xin gia nhập mạng lưới Mesh
```
### 步骤 4：配置域名 DNS（2 台服务器上的 Load Balancing & Failover）
为了让您的网站能够同时利用两台服务器的计算能力，请按 **Round-Robin** 方式配置 DNS 记录（在 Cloudflare 等）：
- 将 **2 条 `A` 记录** 指向 Mango Mesh 集群的 2 个不同 IP。
重启两台 VPS 上的 Mango Shield：`sudo systemctl restart mango-shield`。
检查 VPS 1 上的 Dashboard API：`curl -u admin:admin123 http://103.77.246.172:9090/api/stats`，您将看到 `"mesh_nodes": 2`，表示 2 台机器已成功连接！
**Cloudflare 设置示例（关闭橙色云 - 仅 DNS 灰色勾选）：**
| 类型 | 名称 | 内容 / IP | TTL |
|---|---|---|---|
| A | `@` | `103.77.246.172` | Auto |
| A | `@` | `103.77.246.153` | Auto |
| A | `www` | `103.77.246.172` | Auto |
| A | `www` | `103.77.246.153` | Auto |
**实际运行流程：**
1. 当访客访问网站时，DNS 系统会自动将流量 50-50 平均分配给每台服务器。极大地优化了 CPU。
2. 如果 1 台服务器崩溃或断网，DNS 会自动将其移除，并将访客引导至剩余的服务器。
3. P2P 交叉封禁：如果黑客对服务器 2 发起 HTTP Flood 攻击并被封禁 IP，Mango Mesh 网络将立即把该 IP 的黑名单同步到服务器 1。整个集群共享同一面盾牌！
## 📡 API Endpoints
Dashboard API 默认端口 `9090`：
| Endpoint | Method | 描述 | 测试命令 |
|---|---|---|---|
| `/` | GET | Dashboard 界面 | `curl http://IP:9090/` |
| `/api/stats` | GET | 实时统计 | `curl http://IP:9090/api/stats` |
| `/api/health` | GET | 健康检查 | `curl http://IP:9090/api/health` |
| `/api/config` | GET | 当前配置 | `curl http://IP:9090/api/config` |
| `/api/rps-history` | GET | 5 分钟 RPS 图表 | `curl http://IP:9090/api/rps-history` |
## 🧱 WAF Rules
### 内置 28 条 OWASP CRS 规则
| 类别 | 规则数 | 检测内容 |
|---|:---:|---|
| SQL Injection | 6 | UNION SELECT, tautology, stacked queries, comment bypass |
| XSS | 4 | Script tags, event handlers, eval(), img/iframe |
| LFI | 3 | Path traversal `../`, /etc/passwd, .env, .git |
| RCE | 4 | Unix/Windows command injection, PHP/Node.js |
| RFI | 1 | URL inclusion (http://, php://, data://) |
| SSRF | 1 | 访问 127.0.0.1, 10.x, 192.168.x, metadata |
| Scanner | 2 | Nikto, sqlmap, nuclei, Burp Suite |
| Protocol | 3 | HTTP smuggling, invalid methods, null bytes |
### 添加自定义规则
创建文件 `custom-rules.yaml`：
```
rules:
- id: "CUSTOM-001"
name: "Block WP login brute force"
category: "custom"
severity: "high"
targets: ["URL"]
operator: "contains"
pattern: "/wp-login.php"
action: "challenge"
enabled: true
- id: "CUSTOM-002"
name: "Block admin paths"
category: "custom"
severity: "medium"
targets: ["URL"]
operator: "rx"
pattern: "/(admin|phpmyadmin|manager)"
action: "block"
enabled: true
```
配置：
```
waf:
custom_rules_path: "/opt/mango-shield/custom-rules.yaml"
```
## 🔔 Telegram 告警
### 设置方法
```
1. Mở Telegram → tìm @BotFather
2. Gửi /newbot → đặt tên → nhận TOKEN
3. Mở @userinfobot → nhận CHAT_ID
4. Điền vào config:
```
```
alerts:
telegram:
enabled: true
token: "123456:ABC-DEF..." # Token từ @BotFather
chat_id: "5805939083" # Chat ID từ @userinfobot
```
### 收到的告警样本
```
🚨 CẢNH BÁO TẤN CÔNG DDoS
━━━━━━━━━━━━━━━━━━━━━
⏰ Thời gian: 10:00:00 — 05/03/2026
🌐 Domain: example.com
📊 RPS hiện tại: 500 req/s
⚡ Ngưỡng cảnh báo: 200 req/s
📈 Vượt ngưỡng: 2.5x
🔴 Trạng thái: Đang bị tấn công
🛡️ Hành động: Tự động nâng cấp bảo vệ
━━━━━━━━━━━━━━━━━━━━━
🥭 Mango Shield v2.0
```
## 🐳 Docker
```
# 构建镜像
docker build -t mango-shield .
# 运行容器
docker run -d --name mango-shield \
-p 443:443 -p 80:80 -p 9090:9090 \
-v ./config:/app/config:ro \
-v ./certs:/app/certs:ro \
--cap-add NET_ADMIN \
mango-shield
# 或使用 Docker Compose
docker-compose up -d
# 查看日志
docker logs -f mango-shield
```
## 🔧 故障排除
### 服务器无法启动 — 端口被占用
```
# 查找占用端口的进程
ss -tlnp | grep ':80\|:443\|:9090'
# 释放端口
sudo kill $(sudo lsof -t -i:80)
# 或关闭正在运行的 nginx/apache
sudo systemctl stop nginx
sudo systemctl stop apache2
```
### Bad Gateway — 后端无响应
```
# 检查 backend 是否运行
curl -v http://127.0.0.1:8080
# 检查 Mango Shield 日志
tail -50 /var/log/mango-shield.log
# 确保 config 中的 backend URL 正确
# 错误: backend: "127.0.0.1:8080" (缺少 http://)
# 正确: backend: "http://127.0.0.1:8080"
```
### 重新加载配置（无需重启）
```
kill -HUP $(pidof mango-shield)
```
### 完全重启
```
sudo systemctl restart mango-shield
```
### 健康检查
```
curl http://127.0.0.1:9090/api/health
# 预期: {"status":"healthy","version":"2.0.0",...}
# CLI
./mango-cli health
```
### 查看攻击日志
```
sudo journalctl -u mango-shield -f --grep="attack\|blocked\|banned"
```
## 📜 许可证
MIT License — 由 Mango Team 用 ❤️ 构建。
标签：AI行为分析, AppImage, Bot检测, CDN加速, CISA项目, DDoS防护, Docker, EVTX分析, Golang, JA3指纹, L7防御, P2P网格, Radare2, SQL注入防护, TLS指纹, WAF, Web应用防火墙, XDP, XSS防护, 代码生成, 仪表盘, 反向代理, 威胁情报, 安全编程, 安全防御评估, 开发者工具, 日志审计, 流量清洗, 渗透测试工具, 滥用缓解, 网络安全, 请求拦截, 负载均衡, 配置错误, 防御深度, 隐私保护