opastorello/a10-guardian
GitHub: opastorello/a10-guardian
为 A10 Thunder TPS 设备提供 REST API 与 MCP 服务的 DDoS 缓解自动化平台。
Stars: 0 | Forks: 0
# 🛡️ A10 Guardian
用于 A10 Networks Thunder TPS DDoS 缓解设备的 REST API + MCP Server。提供了一个简化的接口来管理防护区、监控活动事件并部署缓解配置——可通过 HTTP 端点或通过 Model Context Protocol (MCP) 由 AI 智能体访问。
## ✨ 功能特性
- **🚀 REST API** — 缓解区、系统监控、事件追踪、模板管理
- **🤖 MCP Server** — 通过 Model Context Protocol 实现 AI 智能体集成（Claude Desktop, n8n 等）
- **📝 可配置模板** — 基于JSON 的区域模板，包含自定义配置文件、策略和服务
- **📥 模板导入** — 从现有 A10 区域导入配置，以便在新的缓解措施中复用
- **🔐 身份验证** — REST 使用 API token，MCP HTTP 传输使用 Bearer token
- **📊 可观测性** — 使用 Loguru 进行结构化日志记录，写操作审计追踪
- **🔔 通知** — 针对模板、缓解措施和系统事件的精细 Webhook 告警（Slack, Discord, Telegram）
- **🐳 Docker 就绪** — 双服务 Compose 设置（API + MCP），包含健康检查和持久化模板存储
## 📚 文档
**📖 [完整文档见 /docs](./docs/README.md)**
- **[API 使用指南](./docs/API_USAGE.md)** - REST API 完整文档
- **[集成指南](./docs/INTEGRATION_GUIDE.md)** - N8N, Claude API, Gemini, Make.com, Zapier
- **[N8N 工作流](./docs/N8N_INTEGRATION.json)** - N8N 开箱即用配置
- **[MCP 指南](./docs/MCP_USAGE.md)** - Model Context Protocol 服务器
## 🛠️ 技术栈
- **🐍 Python 3.10+** / **⚡ FastAPI** / **🦄 Uvicorn**
- **🔌 FastMCP** — 支持 stdio 和 streamable-http 传输的 MCP 服务器
- **🌐 httpx** — 用于 A10 设备通信的 HTTP 客户端
- **✅ Pydantic v2** — 请求/响应验证
- **📝 Loguru** — 带轮转的结构化日志
- **⏱️ SlowAPI** — 速率限制
## 🚀 快速开始
### 选项 1：使用预构建镜像（推荐）
**Docker Compose:**
```
# 1. 下载 compose 文件
curl -O https://raw.githubusercontent.com/opastorello/a10-guardian/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/opastorello/a10-guardian/main/.env.example
# 2. 配置
cp .env.example .env
# 使用您的 A10 凭据编辑 .env
# 3. 拉取并启动
docker compose pull
docker compose up -d
```
**直接 Docker 运行:**
```
# 拉取镜像
docker pull ghcr.io/opastorello/a10-guardian:latest
# 运行 REST API 服务器
docker run -d \
--name a10-guardian-api \
-p 8000:8000 \
-e A10_USERNAME=admin \
-e A10_PASSWORD=your_password \
-e A10_BASE_URL=https://your-a10-host:17489 \
-e API_SECRET_TOKEN=your_secret_token \
-e WEBHOOK_ENABLED=true \
-e WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook \
-e NOTIFY_ATTACK_DETECTED=true \
-e NOTIFY_ATTACK_MITIGATED=true \
-v $(pwd)/logs:/app/logs \
-v $(pwd)/config:/app/config \
--restart unless-stopped \
ghcr.io/opastorello/a10-guardian:latest
# 运行 MCP Server (可选 - 用于 AI agent 集成)
docker run -d \
--name a10-guardian-mcp \
-p 8001:8001 \
-e A10_USERNAME=admin \
-e A10_PASSWORD=your_password \
-e A10_BASE_URL=https://your-a10-host:17489 \
-e API_SECRET_TOKEN=your_secret_token \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=8001 \
-v $(pwd)/logs:/app/logs \
-v $(pwd)/config:/app/config \
--restart unless-stopped \
ghcr.io/opastorello/a10-guardian:latest \
python src/a10_guardian/mcp_server.py
```
**常用环境变量:**
```
# 必需
A10_USERNAME=admin # A10 device username
A10_PASSWORD=your_password # A10 device password
A10_BASE_URL=https://your-a10-host:17489 # A10 device URL
API_SECRET_TOKEN=your_secret_token # API authentication token
# 可选 - Webhooks
WEBHOOK_ENABLED=true # Enable webhook notifications
WEBHOOK_URL=https://discord.com/api/webhooks/... # Discord/Slack webhook URL
WEBHOOK_USERNAME=A10 Guardian # Bot display name
# 可选 - Telegram (与 webhooks 配合使用)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF... # Get from @BotFather
TELEGRAM_CHAT_ID=-1001234567890 # Chat/group ID (@userinfobot)
# 可选 - Attack Monitoring
NOTIFY_ATTACK_DETECTED=true # Alert on new attacks
NOTIFY_ATTACK_MITIGATED=true # Alert when attacks end
NOTIFY_ATTACK_ONGOING=false # Periodic updates (15min)
ATTACK_MONITORING_INTERVAL=30 # Check interval (seconds)
# 可选 - Mitigation Notifications
NOTIFY_MITIGATION_START=true # Alert on mitigation start
NOTIFY_MITIGATION_STOP=true # Alert on mitigation stop
# 可选 - Template Notifications
NOTIFY_TEMPLATE_CREATE=true # Alert on template creation
NOTIFY_TEMPLATE_IMPORT=true # Alert on template import
```
### 选项 2：从源码构建
```
# 1. 克隆并配置
git clone https://github.com/opastorello/a10-guardian.git
cd a10-guardian
cp .env.example .env
# 使用您的 A10 凭据编辑 .env
# 2. 构建并启动
docker compose up --build -d
```
| Service | Port | URL |
|---------|------|-----|
| REST API | 8000 | `http://localhost:8000/docs` |
| MCP Server | 8001 | `http://localhost:8001/mcp` |
## 💻 本地运行
```
# 创建 virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装
pip install -e .
# 启动 API 服务器
uvicorn a10_guardian.main:app --reload
# 启动 MCP server (独立终端)
MCP_TRANSPORT=streamable-http MCP_PORT=8001 python src/a10_guardian/mcp_server.py
```
## 🔌 API 端点
所有端点都需要 `x-api-token` 请求头。交互式文档位于 `/docs`。
### 🖥️ 系统
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/system/info` | 主机名、版本、序列号、运行时间 |
| GET | `/api/v1/system/devices` | 清单中的所有设备 |
| GET | `/api/v1/system/license` | 许可证类型、限制、过期时间 |
### 🛡️ 缓解
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/mitigation/zones/mitigate/{ip}?template=default` | 使用指定模板创建/部署区域 |
| GET | `/api/v1/mitigation/zones/list` | 分页区域列表 |
| GET | `/api/v1/mitigation/zones/status/{ip}` | 根据 IP 获取完整区域配置 |
| DELETE | `/api/v1/mitigation/zones/remove/{ip}` | 停止缓解并删除区域 |
### 📝 模板
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/templates/list` | 列出所有已配置的模板 |
| GET | `/api/v1/templates/{name}` | 获取模板详情 |
| POST | `/api/v1/templates/{name}` | 创建或更新模板 |
| POST | `/api/v1/templates/validate` | 验证模板但不保存 (dry-run) |
| DELETE | `/api/v1/templates/{name}` | 删除模板 |
| GET | `/api/v1/templates/export/{name}` | 将模板下载为 JSON 文件 |
| POST | `/api/v1/templates/import/{ip}?name={name}` | 从现有 A10 区域导入模板 |
### 🚨 攻击监控
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/attacks/ongoing` | 列出所有正在进行的 DDoS 攻击（分页） |
| GET | `/api/v1/attacks/incident/{id}/stats` | 获取特定事件的流量统计 |
| GET | `/api/v1/attacks/incident/{id}/details` | 获取完整的事件详情和原始数据 |
### ❤️ 健康
| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | 健康检查 (可选 `?check_upstream=true`) |
## 📝 模板系统
### 📋 概述
模板是定义如何创建和监控区域的 JSON 配置。它们包含：
- **📦 区域载荷**: 配置文件、策略、设备组和服务列表
- **📊 监控载荷**: 检测算法、灵敏度和逐协议阈值
模板存储在 `config/zone_templates/` 中（出于安全考虑已从 Git 中排除）。
### ⚙️ 初始设置
#### 选项 1：从现有区域导入（推荐）
```
curl -X POST "http://localhost:8000/api/v1/templates/import/203.0.113.5?name=default" \
-H "x-api-token: YOUR_TOKEN"
```
#### 选项 2：手动创建
```
curl -X POST "http://localhost:8000/api/v1/templates/default" \
-H "x-api-token: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d @docs/examples/gaming-template.json
```
### 使用模板
配置完成后，在创建缓解措施时指定模板：
```
# 使用默认 template
POST /api/v1/mitigation/zones/mitigate/203.0.113.10
# 使用特定 template
POST /api/v1/mitigation/zones/mitigate/203.0.113.10?template=gaming
```
从同一模板创建的所有区域将具有相同的配置（配置文件、策略、服务）。
## 🚨 实时攻击监控
A10 Guardian 提供对**所有防护区**（不仅仅是通过 API 创建的区域）的 DDoS 攻击自动实时监控。系统持续轮询 A10 设备以获取活动事件，并在检测到攻击或缓解时发送即时通知。
### ⚙️ 工作原理
- **🔍 后台监控任务** 每 10 秒检查一次正在进行的攻击（可配置）
- **🌍 监控所有区域** 在 A10 设备中，无论它们是如何创建的
- **🚨 检测新攻击** 并发送即时通知 (🚨 检测到攻击)
- **⏱️ 追踪攻击持续时间** 并在攻击结束时发送通知 (✅ 攻击已停止)
- **⚠️ 可选定期更新** 针对长时间运行的攻击 (⚠️ 攻击进行中，每 15 分钟)
### ⚙️ 配置
在 `.env` 中启用攻击监控：
```
# Attack Monitoring (实时 DDoS 攻击检测)
NOTIFY_ATTACK_DETECTED=True # Alert when DDoS attack is detected
NOTIFY_ATTACK_MITIGATED=True # Alert when attack stops
NOTIFY_ATTACK_ONGOING=False # Periodic updates for long-running attacks (every 15min)
ATTACK_MONITORING_INTERVAL=30 # Check for attacks every N seconds (min: 10, max: 300)
```
### 🔔 Webhook 通知
当 `WEBHOOK_ENABLED=true` 时，攻击事件会发送到 Discord/Slack/n8n：
**检测到攻击:**
```
{
"title": "🚨 Attack Detected",
"description": "DDoS attack detected on 203.0.113.50",
"color": 16711680, // Red
"fields": [
{"name": "Zone", "value": "203.0.113.50"},
{"name": "Severity", "value": "High"},
{"name": "Incident ID", "value": "a1b2c3d4-..."}
]
}
```
**攻击已停止:**
```
{
"title": "✅ Attack Stopped",
"description": "Attack on 203.0.113.50 has stopped",
"color": 65280, // Green
"fields": [
{"name": "Zone", "value": "203.0.113.50"},
{"name": "Duration", "value": "8 minutes 42 seconds"}
]
}
```
### API 端点
以编程方式查询攻击数据：
```
# 列出所有进行中的攻击
GET /api/v1/attacks/ongoing?page=1&items=20
# 获取特定攻击的详细统计数据
GET /api/v1/attacks/incident/{incident_id}/stats
# 获取包含原始 A10 数据的完整事件详情
GET /api/v1/attacks/incident/{incident_id}/details
```
**示例响应（正在进行的攻击）:**
```
{
"total": 2,
"page": 1,
"items_per_page": 20,
"incidents": [
{
"incident_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"zone_name": "203.0.113.50",
"zone_id": "f6593c0b-9c93-4736-babc-8a3828e35af6",
"severity": "High",
"start_time": "2026-02-13T10:15:30Z",
"status": "Ongoing"
}
]
}
```
**示例响应（事件统计）:**
```
{
"incident_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"zone_name": "203.0.113.50",
"total_packets": 15000000,
"total_bytes": 7500000000,
"peak_pps": 500000,
"peak_bps": 4000000000,
"attack_vectors": [
{"protocol": "UDP", "port": 53, "percentage": 65},
{"protocol": "TCP", "port": 80, "percentage": 25},
{"protocol": "ICMP", "port": null, "percentage": 10}
]
}
```
### 🎯 监控范围
**当前监控内容：**
- ✅ **所有正在进行的 DDoS 攻击** — 整个 A10 设备的实时事件检测
- ✅ **任何防护区** — 无论来源如何监控区域：
- 通过此 API 创建的区域
- 在 A10 TPS Web 界面中手动创建的区域
- 由其他系统或自动化创建的区域
**当前未监控内容**（见 [路线图](#-roadmap)）：
- ⏳ **区域创建/删除** — 当在 API 之外添加/删除区域时
- ⏳ **区域配置更改** — 当在 A10 界面中手动修改区域时
- ⏳ **模板偏差检测** — 当部署的区域与其原始模板不同时
这提供了对所有 DDoS 活动的**完全可见性**。有关基础设施变更监控（区域、配置），请参阅路线图部分中计划的增强功能。
## 📱 Telegram 通知
A10 Guardian 支持 **Telegram 通知**以及 Slack/Discord Webhook。Telegram 通知独立工作，可以与 Webhook 通知同时启用。
### ⚙️ 设置
1. **创建一个 Telegram Bot：**
- 在 Telegram 上私信 [@BotFather](https://t.me/BotFather)
- 发送 `/newbot` 并按照提示操作
- 复制 **bot token** (格式: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)
2. **获取你的 Chat ID：**
- 与你的 bot 开始对话或将其添加到群组
- 私信 [@userinfobot](https://t.me/userinfobot) 获取你的 **Chat ID**
- 私聊：正数 (例如，`123456789`)
- 群组：负数 (例如，`-1001234567890`)
3. **在 `.env` 中配置：**
```
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=-1001234567890
```
### 📨 消息格式
Telegram 通知使用带有表情符号的 **Markdown 格式**：
**检测到攻击：**
```
*🚨 Attack Detected*
DDoS attack detected on zone 203.0.113.50
🌐 *IP:* 203.0.113.50
📎 *Zone ID:* f6593c0b-...
⚙️ *Mode:* monitor
_A10 Guardian API_
```
**缓解已开始：**
```
*🛡️ Mitigation Started*
Protection activated for 203.0.113.50
🌐 *IP:* 203.0.113.50
🛡️ *Services:* 23
📋 *Profile:* Gaming_Profile
📋 *Template:* default
_A10 Guardian API_
```
### ✅ 功能特性
- ✅ **与 Webhook 并行工作** — 同时发送到 Telegram 和 Discord/Slack
- ✅ **相同的事件覆盖范围** — 模板、缓解措施、攻击、系统健康
- ✅ **Markdown 格式** — 粗体、斜体、代码块，以提高可读性
- ✅ **特定事件表情符号** — 🚨 攻击，🛡️ 缓解，📋 模板
- ✅ **精细控制** — 使用与 Webhook 相同的 `NOTIFY_*` 设置
### 🔧 示例配置
```
# 同时启用 Telegram 和 Discord
WEBHOOK_ENABLED=true
WEBHOOK_URL=https://discord.com/api/webhooks/...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_CHAT_ID=-1001234567890
# 通知偏好 (同时适用于两者)
NOTIFY_ATTACK_DETECTED=true
NOTIFY_ATTACK_MITIGATED=true
NOTIFY_MITIGATION_START=true
NOTIFY_TEMPLATE_CREATE=true
```
## 🤖 MCP 集成
MCP 服务器为 AI 智能体暴露了 9 个工具：
#### 🖥️ 系统与监控
| Tool | Description |
|--------------------------------------|-------------------------------------------------------|
| `get_system_health()` | 检查 A10 设备是否在线 |
| `list_active_mitigations()` | 列出当前处于缓解状态的所有 IP |
| `get_zone_status(ip_address)` | 特定区域的完整配置和状态 |
#### 🛡️ 缓解管理
| Tool | Description |
|------------------------------------------|----------------------------------------------------------|
| `mitigate_ip(ip_address, template)` | 使用指定模板创建或重新同步缓解 |
| `remove_mitigation(ip_address)` | 停止缓解并移除区域 |
#### 📝 模板管理
| Tool | Description |
|------------------------------------------|----------------------------------------------------------|
| `list_zone_templates()` | 列出所有可用模板 |
| `get_zone_template(name)` | 获取模板配置 |
| `set_zone_template(template_json, name)` | 创建/更新模板并进行验证 |
| `import_zone_template(ip_address, name)` | 从现有 A10 区域导入模板 |
### 通过 n8n (HTTP) 连接
使用 **MCP Client Tool** 节点，配置如下：
- **URL:** `http://:8001/mcp`
- **Authentication:** Bearer Token
- **Token:** 你的 `API_SECRET_TOKEN` 值
### 通过 Claude Desktop (stdio) 连接
添加到你的 `claude_desktop_config.json`：
```
{
"mcpServers": {
"a10-guardian": {
"command": "python",
"args": ["src/a10_guardian/mcp_server.py"],
"cwd": "/path/to/a10-guardian",
"env": {
"A10_USERNAME": "admin",
"A10_PASSWORD": "your_password",
"API_SECRET_TOKEN": "your_token",
"A10_BASE_URL": "https://your-a10-host:17489"
}
}
}
}
```
完整 MCP 集成指南请见 [docs/MCP_USAGE.md](docs/MCP_USAGE.md)。
## 🔐 身份验证
| Interface | Header | Format |
|-----------|--------|--------|
| REST API | `x-api-token` | 明文 token 值 |
| MCP (HTTP) | `Authorization` | `Bearer ` |
两者都使用 `.env` 中相同的 `API_SECRET_TOKEN`。
## ⚙️ 环境变量
| Variable | Description | Default |
|----------|-------------|---------|
| **A10 Device** | | |
| `A10_USERNAME` | A10 设备用户名 | *required* |
| `A10_PASSWORD` | A10 设备密码 | *required* |
| `A10_BASE_URL` | A10 设备的完整 URL | `https://A10_HOST:A10_PORT` |
| `A10_VERIFY_SSL` | 验证 SSL 证书 | `False` |
| **API Settings** | | |
| `API_SECRET_TOKEN` | API 和 MCP 的认证 token | *required* |
| `DEBUG` | 启用调试模式 | `False` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `RATE_LIMIT_DEFAULT` | API 速率限制 | `60/minute` |
| **Webhooks** | | |
| `WEBHOOK_ENABLED` | 启用 Webhook 通知 | `False` |
| `WEBHOOK_URL` Slack/Discord/n8n Webhook URL | — |
| `WEBHOOK_USERNAME` | Webhook 消息的显示名称 | `A10 Guardian` |
| `WEBHOOK_FOOTER` | Webhook 消息的页脚文本 | `A10 Guardian API` |
| **Notification Control** | | |
| `NOTIFY_TEMPLATE_CREATE` | 模板创建时通知 | `True` |
| `NOTIFY_TEMPLATE_UPDATE` | 模板更新时通知 | `False` |
| `NOTIFY_TEMPLATE_DELETE` | 模板删除时通知 | `True` |
| `NOTIFY_TEMPLATE_IMPORT` | 模板导入时通知 | `True` |
| `NOTIFY_MITIGATION_START` | 缓解开始时通知 | `True` |
| `NOTIFY_MITIGATION_STOP` | 缓解停止时通知 | `True` |
| `NOTIFY_SYSTEM_HEALTH` | 监控 A10 健康状态 (60秒间隔) | `False` |
| **Attack Monitoring** | | |
| `NOTIFY_ATTACK_DETECTED` | 检测到攻击时告警 | `True` |
| `NOTIFY_ATTACK_MITIGATED` | 攻击结束时告警 | `True` |
| `NOTIFY_ATTACK_ONGOING` | 长时间攻击的定期更新 | `False` |
| `ATTACK_MONITORING_INTERVAL` | 检查间隔（秒） (10-300) | `30` |
## 🚧 路线图
未来版本计划的增强功能：
### 🔔 增强监控
- **区域变更检测** — 监控并通知直接在 A10 设备中（API/MCP 之外）创建、修改或删除区域的情况
- 当区域在 A10 清单中出现/消失时的实时告警
- 配置偏差检测（当区域被手动修改时）
- 检测到外部变更时的调整建议
- **高级攻击分析** — 具有模式识别功能的历史攻击数据
- 攻击频率趋势和热力图
- 最常受攻击的服务和端口
- 用于异常检测的自动基线学习
### ⚡ 性能与规模
- **批量区域操作** — 在单个 API 调用中创建/更新多个区域
- **区域分组** — 按客户、环境或服务类型组织区域
- **异步后台任务** — 集成 Celery 以处理长时间运行的操作
### 🔧 运维
- **A10 设备池管理** — 支持多个 A10 设备并进行负载分配
- **配置备份/恢复** — A10 配置的自动快照
- **试运行模式** — 在应用到生产环境之前预览更改
### 🤖 AI/自动化
- **事件响应剧本** — 针对常见场景的预定义 MCP 工作流
- **自动缓解规则** — 基于攻击模式触发区域创建
- **自然语言查询** — 用简单的英语询问有关攻击和区域的问题
想要贡献？在 [GitHub](https://github.com/opastorello/a10-guardian) 上开启 issue 或 PR！
## 📄 许可证
MIT
标签：A10 Networks, AI Agent 集成, API 网关, AV绕过, Claude Desktop, DDoS 防护, Docker, FastAPI, FastMCP, FTP漏洞扫描, Loguru, MCP Server, n8n, Pydantic, Python, REST API, Thunder TPS, Webhook 通知, 区域管理, 威胁缓解, 安全编排, 安全防御评估, 抗 D, 无后门, 模型上下文协议, 流量清洗, 网络安全, 网络测绘, 自动化运维, 请求拦截, 运行时操纵, 逆向工具, 配置错误, 隐私保护