A10 Guardian

🛡️ A10守护者

用于A10 Networks Thunder TPS DDoS抵御设备的REST API+MCP服务器。提供了一个简化的界面来管理受保护区域、监控活动事件和部署缓解配置——可以通过HTTP端点或AI代理通过模型上下文协议（MCP）访问。

✨ 特性

• 🚀 REST API --缓解区、系统监控、事件跟踪、模板管理
• 🤖 MCP服务器 --通过模型上下文协议（Claude Desktop、n8n等）集成AI代理
• 📝 可配置模板 --基于JSON的区域模板，具有自定义配置文件、策略和服务
• 📥 模板导入 --从现有A10区域导入配置，以便在新的缓解措施中重复使用
• 🔐 认证 -用于REST的API令牌，用于MCP HTTP传输的承载器令牌
• 📊 可观测性 --使用Loguru进行结构化日志记录，对写入操作进行审计跟踪
• 🔔 通知 --模板、缓解措施和系统事件的粒度webhook警报（Slack、Discord、Telegram）
• 🐳 Docker就绪 -Two-service组合设置（API+MCP），带有健康检查和持久模板存储

📚 文档

📖 完整文档在 /docs

• API使用指南 完整的 REST API 文档
• 集成指南 -N8N、Claude API、Gemini、Make.com、Zapier
• N8N工作流 - N8N的设置准备就绪
• MCP指南 -模型上下文协议服务器

🛠️ 技术栈

• 🐍 Python 3.10+ / ⚡ 快速API / 🦄 Uvicorn
• 🔌 FastMCP --带stdio和流式http传输的MCP服务器
• 🌐 httpx --用于A10设备通信的HTTP客户端
• ✅ Pydantic v2 --请求/响应验证
• 📝 洛古鲁 --旋转式结构化测井
• ⏱️ 慢速API --速率限制

🚀 快速入门（Docker）

选项1：使用预构建映像（推荐）

Docker编写：

# 1. Download compose file
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. Configure
cp .env.example .env
# Edit .env with your A10 credentials

# 3. Pull and start
docker compose pull
docker compose up -d

直接运行Docker：

# Pull the image
docker pull ghcr.io/opastorello/a10-guardian:latest

# Run REST API server
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

# Run MCP Server (optional - for AI agent integration)
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

常见环境变量：

# Required
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_internal_token            # Internal master token — full access
MCP_SECRET_TOKEN=your_mcp_token                 # Dedicated MCP token — full access

# Optional - 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

# Optional - Telegram (works alongside webhooks)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...            # Get from @BotFather
TELEGRAM_CHAT_ID=-1001234567890                 # Chat/group ID (@userinfobot)

# Optional - 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)

# Optional - Mitigation Notifications
NOTIFY_MITIGATION_START=true                    # Alert on mitigation start
NOTIFY_MITIGATION_STOP=true                     # Alert on mitigation stop

# Optional - Template Notifications
NOTIFY_TEMPLATE_CREATE=true                     # Alert on template creation
NOTIFY_TEMPLATE_IMPORT=true                     # Alert on template import

选项2：从源代码构建

# 1. Clone and configure
git clone https://github.com/opastorello/a10-guardian.git
cd a10-guardian
cp .env.example .env
# Edit .env with your A10 credentials

# 2. Build and start
docker compose up --build -d

💻 本地运行

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install
pip install -e .

# Start API server
uvicorn a10_guardian.main:app --reload

# Start MCP server (separate terminal)
MCP_TRANSPORT=streamable-http MCP_PORT=8001 python src/a10_guardian/mcp_server.py

🔌 API终点

所有端点都需要 x-api-token 头球交互式文档可在 /docs.

🖥️ 系统

🛡️ 缓解

📝 模板

🚨 攻击监控

❤️ 健康

📝 模板系统

📋 概述

模板是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

使用模板

配置后，在创建缓解措施时指定模板：

# Use default template
POST /api/v1/mitigation/zones/mitigate/203.0.113.10

# Use specific template
POST /api/v1/mitigation/zones/mitigate/203.0.113.10?template=gaming

从同一模板创建的所有区域将具有相同的配置（配置文件、策略、服务）。

🚨 实时攻击监控

A10 Guardian提供跨平台DDoS攻击的自动实时监控 所有保护区 （不仅仅是那些通过API创建的）。该系统持续轮询A10设备以查找活动事件，并在检测到或减轻攻击时发送即时通知。

⚙️ 运作原理

• 🔍 后台监控任务 每10秒检查一次正在进行的攻击（可配置）
• 🌍 监控所有区域 在A10设备中，无论它们是如何创建的
• 🚨 检测新的攻击 并发送即时通知(🚨 检测到攻击）
• ⏱️ 跟踪攻击持续时间 并在攻击结束时发送通知(✅ 攻击停止）
• ⚠️ 可选的定期更新 用于长期攻击(⚠️ 攻击每15分钟进行一次）

⚙️ 配置

在中启用攻击监控 .env:

# Attack Monitoring (real-time DDoS attack detection)
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终点

以编程方式查询攻击数据：

# List all ongoing attacks
GET /api/v1/attacks/ongoing?page=1&items=20

# Get detailed statistics for specific attack
GET /api/v1/attacks/incident/{incident_id}/stats

# Get full incident details with raw A10 data
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界面中手动创建的区域 - 由其他系统或自动化创建的区域

当前未监控的内容 （参见 路线图):

• ⏳ 区域创建/删除 -在API外部添加/删除区域时
• ⏳ 区域配置更改 --在A10界面中手动修改区域时
• ⏳ 模板漂移检测 --当部署的区域与其原始模板不同时

这提供了 完全能见度 进入所有DDoS活动。有关基础设施变更监控（区域、配置），请参阅路线图部分中的计划增强功能。

📱 电报通知

A10 Guardian支持 电报通知 与Slack/Discord webhooks并列。Telegram通知独立工作，可以与webhook通知同时启用。

⚙️ 设置

1. 创建Telegram Bot：

- 消息 @植物学家 在Telegram上 - 发送 /newbot 并按照提示进行操作 - 复制 bot令牌 （格式： 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

1. 获取您的聊天ID:

- 与您的机器人开始对话或将其添加到组中 - 消息 @用户信息机器人 得到你的 聊天ID - 对于私人聊天：正数（例如。， 123456789) - 对于组：负数（例如。， -1001234567890)

1. 在中配置 .env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=-1001234567890

📨 消息格式

电报通知使用 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_

✅ 特性

• ✅ 与webhooks一起工作 --同时发送到Telegram和Discord/Slack
• ✅ 相同的事件报道 --模板、缓解措施、攻击、系统健康状况
• ✅ Markdown格式 --粗体、斜体、代码块，以提高可读性
• ✅ 特定事件表情符号 — 🚨 攻击，🛡️ 缓解措施，📋 模板
• ✅ 精细控制 --使用相同 NOTIFY_* 设置为webhooks

🔧 配置示例

# Enable both Telegram and Discord
WEBHOOK_ENABLED=true
WEBHOOK_URL=https://discord.com/api/webhooks/...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_CHAT_ID=-1001234567890

# Notification preferences (apply to both)
NOTIFY_ATTACK_DETECTED=true
NOTIFY_ATTACK_MITIGATED=true
NOTIFY_MITIGATION_START=true
NOTIFY_TEMPLATE_CREATE=true

🤖 MCP集成

MCP服务器为AI代理提供了15个工具：

🖥️ 系统与监控

🛡️ 缓解管理

📝 模板管理

通过克劳德代码（HTTP）连接

claude mcp add a10-guardian --transport http http://:8001/mcp \
  --header "Authorization: Bearer "

通过n8n（HTTP）连接

使用 MCP客户端工具 节点具有：

• 网址： http://:8001/mcp
• 身份验证： 持有者令牌
• 令牌： 你的 MCP_SECRET_TOKEN 价值

通过克劳德桌面（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_internal_token",
        "MCP_SECRET_TOKEN": "your_mcp_token",
        "A10_BASE_URL": "https://your-a10-host:17489"
      }
    }
  }
}

看 docs/MCP_USAGE.md 了解完整的MCP集成指南。

🔐 认证

令牌配置文件

A10 Guardian支持 具有粒度范围的多个令牌。在中配置它们 .env:

可用范围： system:read, mitigation:read, mitigation:write, templates:read, templates:write, attacks:read

示例--外部网站的只读令牌：

# .env
API_TOKENS={"tok_mysite": ["mitigation:read"]}

# Can call:
GET /api/v1/mitigation/under-attack/{ip}   ✅
GET /api/v1/mitigation/zones/list          ✅
GET /api/v1/mitigation/zones/status/{ip}   ✅

# Blocked:
POST /api/v1/mitigation/zones/mitigate     ❌ 403
DELETE /api/v1/mitigation/zones/remove     ❌ 403

暴力防护： 每60秒每个IP有10次失败尝试→ 429 请求太多。

⚙️ 环境变量

🚧 路线图

未来版本的计划增强功能：

🔔 增强监控

• 区域变化检测 -在A10设备（API/MCP外部）中直接创建、修改或删除区域时进行监控并发出通知

- 当A10库存中出现/消失区域时发出实时警报 - 配置漂移检测（手动修改区域时） - 检测到外部变化时的对账建议

• 高级攻击分析 --具有模式识别的历史攻击数据

- 攻击频率趋势和热图 - 受攻击最多的服务和端口 - 用于异常检测的自动基线学习

⚡ 性能和规模

• 批处理区操作 -在单个API调用中创建/更新多个区域
• 区域分组 --按客户、环境或服务类型组织区域
• 异步后台任务 --针对长时间运行的快速集成

🔧 运营

• A10设备池管理 --支持多个A10设备，具有负载分布功能
• 配置备份/还原 --A10配置的自动快照
• 干运行模式 --在应用于生产之前预览更改

🤖 人工智能/自动化

• 事故响应手册 --常见场景的预定义MCP工作流程
• 自动缓解规则 --基于攻击模式的触发区域创建
• 自然语言查询 --用简单的英语询问有关攻击和区域的问题

想贡献吗？在上打开问题或PR !

📄 许可证

麻省理工学院