A10 Guardian
by opastorello
README.md
# π‘οΈ 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](./docs/README.md)**
- **[API Usage Guide](./docs/API_USAGE.md)** - DocumentaΓ§Γ£o completa da API REST
- **[Integration Guide](./docs/INTEGRATION_GUIDE.md)** - N8N, Claude API, Gemini, Make.com, Zapier
- **[N8N Workflows](./docs/N8N_INTEGRATION.json)** - ConfiguraΓ§Γ£o pronta para N8N
- **[MCP Guide](./docs/MCP_USAGE.md)** - 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
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
```bash
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:
```bash
# 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`:
```bash
# 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:**
```json
{
"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:**
```json
{
"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:
```bash
# 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):**
```json
{
"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):**
```json
{
"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](#-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](https://t.me/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](https://t.me/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`:**
```bash
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=-1001234567890
```
### π¨ Message Format
Telegram notifications use **Markdown formatting** with emojis:
**Attack Detected:**
```text
*π¨ 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:**
```text
*π‘οΈ 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
```bash
# 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)
```bash
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`:
```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](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:**
```bash
# .env
API_TOKENS={"tok_mysite": ["mitigation:read"]}
```
```bash
# 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](https://github.com/opastorello/a10-guardian)!
## π License
MIT
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues