a10-guardian: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A10 Guardian — REST API + MCP Server for A10 Networks Thunder TPS DDoS mitigation devices. Manages protected zones, monitors live DDoS incidents, tracks zone-config drift, and exposes 15 MCP tools to AI agents. Two services share the same image and codebase: the FastAPI app (port 8000) and the FastMCP server (port 8001).

Commands

# Install editable + dev deps
pip install -e .[dev]

# Run API locally (auto-reload)
uvicorn a10_guardian.main:app --reload

# Run MCP server locally
#   stdio (default — for Claude Desktop)
python src/a10_guardian/mcp_server.py
#   streamable-http (for n8n / Claude Code remote)
MCP_TRANSPORT=streamable-http MCP_PORT=8001 python src/a10_guardian/mcp_server.py

# Lint / format
ruff check .
ruff format .

# Tests
pytest                                    # all
pytest tests/test_client.py               # one file
pytest tests/test_client.py::test_name    # one test
pytest --cov                              # with coverage (config in pyproject.toml)

# Docker (API + MCP from same image)
docker compose up --build -d

Architecture

src/a10_guardian/
├── main.py                  # FastAPI app, lifespan, 3 background monitors, CORS, rate-limit, /health
├── mcp_server.py            # FastMCP server, 15 tools, lazy-loading Container, Bearer auth middleware
├── api/v1/
│   ├── api.py               # router aggregation
│   └── endpoints/
│       ├── system.py        # GET /system/{info,devices,license}
│       ├── mitigation.py    # zone CRUD + /under-attack/{ip} + /zones/{name}/ip/{ip} (check/add/remove)
│       ├── templates.py     # /templates list/get/create/update/delete/validate/export/import
│       └── attacks.py       # /attacks/ongoing, /attacks/incident/{id}/{stats,details}
├── core/
│   ├── config.py            # pydantic-settings; reads .env. Drives feature toggles via NOTIFY_* flags
│   ├── client.py            # A10Client: session/CSRF/retry, auto re-auth on 403
│   ├── dependencies.py      # require_scope() factory + per-IP brute-force limiter; service DI factories
│   ├── exceptions.py        # RFC 7231 ProblemDetails handlers + Template* custom exceptions
│   ├── logging.py           # Loguru setup with audit-file rotation
│   └── limiter.py           # SlowAPI instance (default 60/minute)
├── services/                # All business logic. Endpoints are thin wrappers.
│   ├── auth_service.py      # A10 form-login, CSRF extraction, session JSON cache
│   ├── system_service.py    # info / devices / license
│   ├── mitigation_service.py # ensure_mitigation (idempotent create-or-resync), zone CRUD
│   ├── template_service.py  # template file I/O + A10 validation (profiles/policies/device groups)
│   ├── attack_service.py    # ongoing incidents, stats, details, attack notifications
│   ├── zone_change_service.py # diffs zone snapshots to detect external create/modify/delete
│   └── notification_service.py # webhook (Discord/Slack/n8n) + Telegram fan-out, gated by NOTIFY_*
└── schemas/                 # Pydantic v2 — system, mitigation, template, attack, common