A10 Guardian

REST API + MCP Server for A10 Networks Thunder TPS DDoS mitigation devices. Provides a simplified interface to manage protected zones, monitor active incidents, and deploy mitigation configurations — accessible via HTTP endpoints or AI agents through the Model Context Protocol (MCP).

✨ Features

• 🚀 REST API — Mitigation zones, system monitoring, incident tracking, template management
• 🤖 MCP Server — AI-agent integration via Model Context Protocol (Claude Desktop, n8n, etc.)
• 📝 Configurable Templates — JSON-based zone templates with custom profiles, policies, and services
• 📥 Template Import — Import configurations from existing A10 zones to reuse across new mitigations
• 🔐 Authentication — API token for REST, Bearer token for MCP HTTP transport
• 📊 Observability — Structured logging with Loguru, audit trail for write operations
• 🔔 Notifications — Granular webhook alerts (Slack, Discord, Telegram) for templates, mitigations, and system events
• 🐳 Docker Ready — Two-service Compose setup (API + MCP) with health checks and persistent template storage

📚 Documentação

📖 Documentação Completa em /docs

• API Usage Guide - Documentação completa da API REST
• Integration Guide - N8N, Claude API, Gemini, Make.com, Zapier
• N8N Workflows - Configuração pronta para N8N
• MCP Guide - Model Context Protocol server

🛠️ Tech Stack

• 🐍 Python 3.10+ / ⚡ FastAPI / 🦄 Uvicorn
• 🔌 FastMCP — MCP server with stdio and streamable-http transports
• 🌐 httpx — HTTP client for A10 device communication
• ✅ Pydantic v2 — Request/response validation
• 📝 Loguru — Structured logging with rotation
• ⏱️ SlowAPI — Rate limiting

🚀 Quick Start (Docker)

Option 1: Using Pre-built Image (Recommended)

Docker Compose:

# 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

Direct Docker Run:

# 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

Common Environment Variables:

# 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

Option 2: Build from Source

# 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

Service	Port	URL
REST API	8000	http://localhost:8000/docs
MCP Server	8001	http://localhost:8001/mcp

💻 Running Locally

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

All endpoints require the x-api-token header. Interactive docs available at /docs.

🖥️ System

Method	Path	Description
GET	/api/v1/system/info	Hostname, version, serial, uptime
GET	/api/v1/system/devices	All devices in inventory
GET	/api/v1/system/license	License type, limits, expiration

🛡️ Mitigation

Method	Path	Description
POST	/api/v1/mitigation/zones/mitigate/{ip}?template=default	Create/deploy zone using specified template
GET	/api/v1/mitigation/zones/list	Paginated list of zones
GET	/api/v1/mitigation/zones/status/{ip}	Full zone config by IP
GET	/api/v1/mitigation/under-attack/{ip}	Check if the /24 block of a given IP is under attack
DELETE	/api/v1/mitigation/zones/remove/{ip}	Stop mitigation and delete zone
GET	/api/v1/mitigation/zones/{zone_name}/ip/{ip}	Check whether a specific IP is in a multi-IP zone's ip_list → {found: bool}
POST	/api/v1/mitigation/zones/{zone_name}/ip/{ip}	Add an IP to a multi-IP zone (idempotent)
DELETE	/api/v1/mitigation/zones/{zone_name}/ip/{ip}	Remove an IP from a multi-IP zone (404 if absent, 422 if last IP)

📝 Templates

Method	Path	Description
GET	/api/v1/templates/list	List all configured templates
GET	/api/v1/templates/{name}	Get template details
POST	/api/v1/templates/{name}	Create or update template
POST	/api/v1/templates/validate	Validate template without saving (dry-run)
DELETE	/api/v1/templates/{name}	Delete template
GET	/api/v1/templates/export/{name}	Download template as JSON file
POST	/api/v1/templates/import/{ip}?name={name}	Import template from existing A10 zone

🚨 Attack Monitoring

Method	Path	Description
GET	/api/v1/attacks/ongoing	List all ongoing DDoS attacks (paginated)
GET	/api/v1/attacks/incident/{id}/stats	Get traffic statistics for specific incident
GET	/api/v1/attacks/incident/{id}/details	Get full incident details and raw data

❤️ Health

Method	Path	Description
GET	/health	Health check (optional ?check_upstream=true)

📝 Template System

📋 Overview

Templates are JSON configurations that define how zones are created and monitored. They contain:

• 📦 Zone Payload: Profile, policy, device group, and service list
• 📊 Monitor Payload: Detection algorithm, sensitivity, and per-protocol thresholds

Templates are stored in config/zone_templates/ (excluded from Git for security).

⚙️ Initial Setup

Option 1: Import from existing zone (recommended)

curl -X POST "http://localhost:8000/api/v1/templates/import/203.0.113.5?name=default" \
  -H "x-api-token: YOUR_TOKEN"

Option 2: Create manually

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

Using Templates

Once configured, specify the template when creating mitigations:

# 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

All zones created from the same template will have identical configurations (profiles, policies, services).

🚨 Real-Time Attack Monitoring

A10 Guardian provides automated real-time monitoring of DDoS attacks across all protected zones (not just those created via API). The system continuously polls the A10 device for active incidents and sends instant notifications when attacks are detected or mitigated.

⚙️ How It Works

• 🔍 Background monitoring task checks for ongoing attacks every 10 seconds (configurable)
• 🌍 Monitors ALL zones in the A10 device, regardless of how they were created
• 🚨 Detects new attacks and sends instant notifications (🚨 Attack Detected)
• ⏱️ Tracks attack duration and sends notifications when attacks end (✅ Attack Stopped)
• ⚠️ Optional periodic updates for long-running attacks (⚠️ Attack Ongoing every 15 min)

⚙️ Configuration

Enable attack monitoring in .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 Notifications

When WEBHOOK_ENABLED=true, attack events are sent to Discord/Slack/n8n:

Attack Detected:

{
  "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-..."}
  ]
}

Attack Stopped:

{
  "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 Endpoints

Query attack data programmatically:

# 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

Example Response (Ongoing Attacks):

{
  "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"
    }
  ]
}

Example Response (Incident Stats):

{
  "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}
  ]
}

🎯 Monitoring Scope

What's Currently Monitored:

• ✅ All ongoing DDoS attacks — Real-time incident detection across the entire A10 device
• ✅ Any protected zone — Monitors zones regardless of origin:
  • Zones created via this API
  • Zones created manually in the A10 TPS web interface
  • Zones created by other systems or automation

What's NOT Currently Monitored (see Roadmap):

• ⏳ Zone creation/deletion — When zones are added/removed outside the API
• ⏳ Zone configuration changes — When zones are manually modified in the A10 interface
• ⏳ Template drift detection — When deployed zones differ from their original templates

This provides complete visibility into all DDoS activity. For infrastructure change monitoring (zones, configs), see planned enhancements in the Roadmap section.

📱 Telegram Notifications

A10 Guardian supports Telegram notifications alongside Slack/Discord webhooks. Telegram notifications work independently and can be enabled concurrently with webhook notifications.

⚙️ Setup

1. Create a Telegram Bot:

   • Message @BotFather on Telegram
   • Send /newbot and follow the prompts
   • Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get your Chat ID:

   • Start a conversation with your bot or add it to a group
   • Message @userinfobot to get your Chat ID
   • For private chats: positive number (e.g., 123456789)
   • For groups: negative number (e.g., -1001234567890)

3. Configure in .env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=-1001234567890

📨 Message Format

Telegram notifications use Markdown formatting with emojis:

Attack Detected:

*🚨 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:

*🛡️ Mitigation Started*

Protection activated for 203.0.113.50

🌐 *IP:* 203.0.113.50
🛡️ *Services:* 23
📋 *Profile:* Gaming_Profile
📋 *Template:* default

_A10 Guardian API_

✅ Features

• ✅ Works alongside webhooks — Send to Telegram AND Discord/Slack simultaneously
• ✅ Same event coverage — Templates, mitigations, attacks, system health
• ✅ Markdown formatting — Bold, italics, code blocks for better readability
• ✅ Event-specific emojis — 🚨 attacks, 🛡️ mitigations, 📋 templates
• ✅ Granular control — Use same NOTIFY_* settings as webhooks

🔧 Example Configuration

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

The MCP server exposes 15 tools for AI agents:

🖥️ System & Monitoring

Tool	Description
get_system_health()	Check if the A10 device is online
get_system_devices()	List all devices in the A10 inventory
get_system_license()	License type, limits, and expiration
list_active_mitigations()	List all IPs currently under mitigation
list_ongoing_attacks()	List all DDoS attacks currently being mitigated
get_zone_status(ip_address)	Full config and status of a specific zone

🛡️ Mitigation Management

Tool	Description
mitigate_ip(ip_address, template)	Create or re-sync mitigation using specified template
remove_mitigation(ip_address)	Stop mitigation and remove the zone
zone_has_ip(zone_name, ip)	Check whether an IP is in a multi-IP zone's ip_list
add_ip_to_zone(zone_name, ip)	Add an IP to a multi-IP zone (idempotent, lock-protected)
remove_ip_from_zone(zone_name, ip)	Remove an IP from a multi-IP zone

📝 Template Management

Tool	Description
list_zone_templates()	List all available templates
get_zone_template(name)	Retrieve template configuration
set_zone_template(template_json, name)	Create/update template with validation
import_zone_template(ip_address, name)	Import template from existing A10 zone

Connecting via Claude Code (HTTP)

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

Connecting via n8n (HTTP)

Use the MCP Client Tool node with:

• URL: http://<host>:8001/mcp
• Authentication: Bearer Token
• Token: Your MCP_SECRET_TOKEN value

Connecting via Claude Desktop (stdio)

Add to your 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"
      }
    }
  }
}

See docs/MCP_USAGE.md for the full MCP integration guide.

🔐 Authentication

Interface	Header	Format
REST API	x-api-token	Plain token value
MCP (HTTP)	Authorization	Bearer <MCP_SECRET_TOKEN>

Token Profiles

A10 Guardian supports multiple tokens with granular scopes. Configure them in .env:

Token	Variable	Scopes	Use Case
Internal / Team	API_SECRET_TOKEN	all	Full API access — internal team
MCP clients	MCP_SECRET_TOKEN	all	Dedicated token for Claude, n8n, AI agents
External sites	API_TOKENS (JSON)	configurable	Read-only embeds, partner integrations

Available scopes: system:read, mitigation:read, mitigation:write, templates:read, templates:write, attacks:read

Example — read-only token for an external website:

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

Brute-force protection: 10 failed attempts per IP per 60 seconds → 429 Too Many Requests.

⚙️ Environment Variables

Variable	Description	Default
A10 Device
A10_USERNAME	A10 device username	required
A10_PASSWORD	A10 device password	required
A10_BASE_URL	Full URL to A10 device	https://A10_HOST:A10_PORT
A10_VERIFY_SSL	Verify SSL certificates	False
API Settings
API_SECRET_TOKEN	Internal master token — full access, all scopes	required
MCP_SECRET_TOKEN	Dedicated token for MCP clients (Claude, n8n) — full access	required
API_TOKENS	Additional tokens with granular scopes (JSON)	{}
CORS_ORIGINS	Allowed CORS origins, comma-separated	"" (block all)
DEBUG	Enable debug mode	False
LOG_LEVEL	Logging level	INFO
RATE_LIMIT_DEFAULT	API rate limit	60/minute
Webhooks
WEBHOOK_ENABLED	Enable webhook notifications	False
WEBHOOK_URL	Slack/Discord/n8n webhook URL	—
WEBHOOK_USERNAME	Display name for webhook messages	A10 Guardian
WEBHOOK_FOOTER	Footer text for webhook messages	A10 Guardian API
Notification Control
NOTIFY_TEMPLATE_CREATE	Notify on template creation	True
NOTIFY_TEMPLATE_UPDATE	Notify on template updates	False
NOTIFY_TEMPLATE_DELETE	Notify on template deletion	True
NOTIFY_TEMPLATE_IMPORT	Notify on template imports	True
NOTIFY_MITIGATION_START	Notify when mitigation starts	True
NOTIFY_MITIGATION_STOP	Notify when mitigation stops	True
NOTIFY_SYSTEM_HEALTH	Monitor A10 health (60s interval)	False
Attack Monitoring
NOTIFY_ATTACK_DETECTED	Alert when attack is detected	True
NOTIFY_ATTACK_MITIGATED	Alert when attack ends	True
NOTIFY_ATTACK_ONGOING	Periodic updates for long attacks	False
ATTACK_MONITORING_INTERVAL	Check interval in seconds (10-300)	30

🚧 Roadmap

Planned enhancements for future releases:

🔔 Enhanced Monitoring

• Zone Change Detection — Monitor and notify when zones are created, modified, or deleted directly in the A10 device (outside API/MCP)

  • Real-time alerts when zones appear/disappear from the A10 inventory
  • Configuration drift detection (when zones are manually modified)
  • Reconciliation suggestions when external changes are detected

• Advanced Attack Analytics — Historical attack data with pattern recognition

  • Attack frequency trends and heatmaps
  • Top attacked services and ports
  • Automatic baseline learning for anomaly detection

⚡ Performance & Scale

• Batch Zone Operations — Create/update multiple zones in a single API call
• Zone Grouping — Organize zones by customer, environment, or service type
• Async Background Tasks — Celery integration for long-running operations

🔧 Operations

• A10 Device Pool Management — Support for multiple A10 devices with load distribution
• Configuration Backup/Restore — Automated snapshots of A10 configurations
• Dry-run Mode — Preview changes before applying to production

🤖 AI/Automation

• Incident Response Playbooks — Pre-defined MCP workflows for common scenarios
• Auto-mitigation Rules — Trigger zone creation based on attack patterns
• Natural Language Queries — Ask questions about attacks and zones in plain English

Want to contribute? Open an issue or PR on GitHub!

📄 License

MIT