5g-ddos-mcp

<p align="center"> <img src="logo.svg" alt="5g-ddos-mcp" width="520"/> </p>

<p align="center"> <b>Model Context Protocol server for real-time 5G DDoS detection and response</b><br/> Powered by the <a href="https://doi.org/10.5281/zenodo.13900057">NCSRD-DS-5GDDoS dataset</a> — a physical 3GPP-compliant 5G testbed from the EU Horizon PRIVATEER project </p>

<p align="center"> <img src="https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white"/> <img src="https://img.shields.io/badge/MCP-1.3%2B-green?style=flat-square"/> <img src="https://img.shields.io/badge/XGBoost-ML%20model-orange?style=flat-square"/> <img src="https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white"/> <img src="https://img.shields.io/badge/Kubernetes-ready-326CE5?style=flat-square&logo=kubernetes&logoColor=white"/> <img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square"/> </p>

---

What It Does

Gives any LLM agent the ability to detect, explain, and respond to 5G DDoS attacks:

Tool	What it does
detect_anomaly	Classify live 5G telemetry as benign/attack — returns type, confidence, severity
explain_attack	Generate a natural-language incident report via the configured LLM
recommend_response	Slice-aware mitigation plan with generic REST API call examples
query_history	Search past incidents + dataset reference patterns for few-shot LLM reasoning

Supports SYN, UDP, ICMP, DNS, and GTP-U flooding (the last being 5G-specific, critical severity).

---

Quick Start

Pick your LLM backend and follow the matching path. The server runs in demo mode (rule-based heuristics) without a trained model, so you can try all tools immediately.

---

Option A — Claude (Anthropic API)

Best output quality for incident reports and recommendations.

# 1. Clone and install
git clone https://github.com/ncsrd/5g-ddos-mcp
cd 5g-ddos-mcp
pip install -r requirements.txt

# 2. Configure
cp .env.example .env
#    Set: LLM_BACKEND=claude
#    Set: ANTHROPIC_API_KEY=sk-ant-...

# 3. Run
python -m src.server

Connect in claude_desktop_config.json:

{
  "mcpServers": {
    "5g-ddos": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/5g-ddos-mcp",
      "env": {
        "LLM_BACKEND": "claude",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

---

Option B — Ollama (local open-source LLMs, fully offline)

Best for air-gapped or privacy-sensitive deployments. No data leaves your machine.

Step 1 — Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows: download from https://ollama.com/download

Step 2 — Pull a model

ollama pull llama3.2       # 3B (fast) or 8B (balanced) — recommended default
ollama pull mistral        # 7B — strong reasoning
ollama pull phi4           # 14B — best structured output
ollama pull gemma3         # Google Gemma 3, 4B–27B
ollama pull deepseek-r1    # 8B chain-of-thought distill
ollama pull qwen2.5        # 7B / 14B / 72B

Step 3 — Run the MCP server

cp .env.example .env
#    Set: LLM_BACKEND=ollama
#    Set: OLLAMA_MODEL=llama3.2   (or whichever you pulled)
#    OLLAMA_BASE_URL defaults to http://localhost:11434

python -m src.server

Connect in claude_desktop_config.json:

{
  "mcpServers": {
    "5g-ddos": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/5g-ddos-mcp",
      "env": {
        "LLM_BACKEND": "ollama",
        "OLLAMA_MODEL": "llama3.2"
      }
    }
  }
}

---

Option C — OpenAI-compatible endpoint

Works with vLLM, LM Studio, Groq, Together.ai, Mistral API, Perplexity, and any other OpenAI-compatible provider.

cp .env.example .env
#    Set: LLM_BACKEND=openai_compatible
#    Set: OPENAI_BASE_URL=<your endpoint>
#    Set: OPENAI_MODEL=<model name>
#    Set: OPENAI_API_KEY=<your key>

python -m src.server

Provider examples:

Provider	OPENAI_BASE_URL	OPENAI_MODEL
vLLM (self-hosted)	http://localhost:8080/v1	your deployed model
LM Studio (local)	http://localhost:1234/v1	model loaded in LM Studio
Groq	https://api.groq.com/openai/v1	llama-3.3-70b-versatile
Together.ai	https://api.together.xyz/v1	meta-llama/Llama-3-70b-chat-hf
Mistral API	https://api.mistral.ai/v1	mistral-large-latest
Perplexity	https://api.perplexity.ai	llama-3.1-sonar-large-128k-online
OpenAI	https://api.openai.com/v1	gpt-4o

---

Option D — Docker (any backend)

# Build
docker build -t 5g-ddos-mcp .

# Run with Claude
docker run --env-file .env -p 8000:8000 \
  -v $(pwd)/models:/app/models:ro \
  -v $(pwd)/data:/app/data:ro \
  5g-ddos-mcp

# Run with Ollama (Ollama running on host)
docker run -p 8000:8000 \
  -e LLM_BACKEND=ollama \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=llama3.2 \
  5g-ddos-mcp

# Full stack: MCP server + Ollama side-by-side
docker compose --profile with-ollama up
# Then pull a model inside the Ollama container:
docker exec -it ollama ollama pull llama3.2

# Full stack with InfluxDB + Grafana (mirrors the NCSRD testbed pipeline)
docker compose --profile full up

---

Option E — Kubernetes

# 1. Apply namespace, storage, and config
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/pvc.yaml
kubectl apply -f k8s/configmap.yaml

# 2. Create secrets (replace with real values)
kubectl create secret generic 5g-ddos-mcp-secrets \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-... \
  -n 5g-ddos-mcp

# 3. Deploy (set LLM_BACKEND in k8s/deployment.yaml before applying)
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

# 4. Train the model inside the cluster (after populating the data PVC)
kubectl apply -f k8s/train-job.yaml
kubectl logs -f job/train-classifier -n 5g-ddos-mcp

# 5. Check status
kubectl get pods -n 5g-ddos-mcp

To deploy Ollama as a sidecar for a fully self-contained cluster:

# Ollama deployment + service are already included in k8s/deployment.yaml
# Set LLM_BACKEND=ollama and OLLAMA_BASE_URL=http://ollama-service:11434 in configmap.yaml
kubectl apply -f k8s/deployment.yaml   # deploys both mcp-server and ollama
kubectl apply -f k8s/service.yaml
# Then exec into the Ollama pod to pull a model:
kubectl exec -it deploy/ollama -n 5g-ddos-mcp -- ollama pull llama3.2

---

Dataset Setup

The ML model requires the NCSRD-DS-5GDDoS v3.0 dataset (~620 MB), which must be downloaded separately. The server runs in heuristic demo mode without it.

# Automatic download from Zenodo (DOI: 10.5281/zenodo.13900057)
chmod +x scripts/download_dataset.sh
./scripts/download_dataset.sh

# Then train the classifier (~5–15 min depending on hardware)
python scripts/train_model.py

# Quick smoke-test with 100k rows
python scripts/train_model.py --nrows 100000

See data/DATASET_INSTRUCTIONS.md for full details on files and manual download.

Target metrics (from published results on this dataset):

Metric	Target	Published
Binary F1	> 0.95	0.98
AUC-ROC	> 0.99	0.999
Multi-class Weighted F1	> 0.95	0.98

---

CLI

The 5g-ddos command lets you run detections, query history, get recommendations, and manage the dataset directly from your terminal — no MCP client required.

pip install -e ".[all]"   # installs the 5g-ddos entry point
5g-ddos --help

server — Start the MCP server

5g-ddos server                          # uses LLM_BACKEND from .env
5g-ddos server --backend ollama --model phi4
5g-ddos server --backend claude

detect — Classify 5G telemetry

# Inline single-sample detection
5g-ddos detect --ul-bitrate 9500000 --dl-bitrate 1200000 \
               --ul-retx 0.42 --pdu-session-setup-request 95 \
               --ue-id UE-007

# Batch detection from a CSV file (matches NCSRD dataset schema)
5g-ddos detect --input telemetry.csv --format table
5g-ddos detect --input telemetry.csv --format csv --output results.csv

# Output formats: table (default) | json | csv

explain — Generate an incident report

5g-ddos explain --attack-type gtp_u_flood --severity critical \
                --slice URLLC --ue-ip 10.45.0.3 --cells "1,2"

5g-ddos explain --attack-type syn_flood --severity high \
                --imeisv 3533890312345678 --format json --output report.json

recommend — Get mitigation recommendations

5g-ddos recommend --attack-type udp_flood --severity high --slice eMBB

# Preview auto-execute REST API commands (does not call any API without RESPONSE_API_URL set)
5g-ddos recommend --attack-type gtp_u_flood --severity critical \
                  --ue-ip 10.45.0.5 --imeisv 3533890312345678 \
                  --auto-execute

history — Query incident history

5g-ddos history                                  # last 10 incidents
5g-ddos history --attack-type syn_flood --limit 20
5g-ddos history --severity critical --slice URLLC --time-range 24

train — Train the XGBoost classifier

5g-ddos train                     # full dataset (~5–15 min)
5g-ddos train --nrows 100000      # quick smoke-test with 100k rows

dataset — Manage the NCSRD dataset

5g-ddos dataset status            # show which files are present / missing
5g-ddos dataset download          # print download instructions
5g-ddos dataset download --auto   # run scripts/download_dataset.sh automatically

version — Show environment info

5g-ddos version
# ┌──────────────────────┬───────────────────────────────┐
# │ 5g-ddos-mcp          │ 1.0.0                         │
# │ LLM Backend          │ claude (claude-sonnet-4-6)    │
# │ ML Model             │ loaded (binary + multi-class) │
# │ Dataset records      │ 7 files present               │
# └──────────────────────┴───────────────────────────────┘

---

Architecture

┌──────────────────────────────────────────────┐
│             MCP Client (any LLM)             │
└──────────────────┬───────────────────────────┘
                   │  MCP Protocol (stdio / HTTP)
┌──────────────────▼───────────────────────────┐
│             5G-DDoS MCP Server               │
│                                              │
│  ┌─────────────┐   ┌──────────────────────┐  │
│  │  ML Layer   │   │      LLM Layer       │  │
│  │  XGBoost    │   │  Claude  │  Ollama   │  │
│  │  Classifier │   │  OpenAI-compatible   │  │
│  └──────┬──────┘   └──────────────────────┘  │
│         │                                    │
│  ┌──────▼────────────────────────────────┐   │
│  │              MCP Tools                │   │
│  │  detect_anomaly  │  explain_attack    │   │
│  │  recommend_response  │  query_history │   │
│  └───────────────────────────────────────┘   │
└──────────────────────────────────────────────┘
                   │
        ┌──────────▼──────────┐
        │    NCSRD Dataset    │
        │    (local CSV)      │
        └─────────────────────┘

Tier 1 — Perception: XGBoost classifier (trained on NCSRD-DS-5GDDoS) detects attacks from real-time telemetry.

Tier 2 — Reasoning: LLM produces contextual incident reports and mitigation recommendations.

Tier 3 — Action: Generic REST API integration for automated response (blacklist UE, isolate slice, rate-limit). Compatible with Open5GS, free5GC, OAI, or any custom NMS — set RESPONSE_API_URL to enable.

---

Configuration Reference

All settings via environment variables. Copy .env.example to .env to get started.

Variable	Default	Description
LLM_BACKEND	claude	claude | ollama | openai_compatible
ANTHROPIC_API_KEY	—	Required when LLM_BACKEND=claude
CLAUDE_MODEL	claude-sonnet-4-6	Anthropic model ID
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	llama3.2	Any model pulled via ollama pull
OPENAI_API_KEY	—	Required when LLM_BACKEND=openai_compatible
OPENAI_BASE_URL	https://api.openai.com/v1	Any OpenAI-compatible endpoint URL
OPENAI_MODEL	gpt-4o-mini	Model name at the endpoint
LLM_MAX_TOKENS	2048	Max tokens for LLM completions
LLM_TEMPERATURE	0.3	Generation temperature
ANOMALY_THRESHOLD	0.5	Attack confidence threshold (0.0–1.0)
RESPONSE_API_URL	—	Network management API for auto-execute (optional)
RESPONSE_API_KEY	—	Bearer token for the response API (optional)
MCP_PORT	8000	Server port
LOG_LEVEL	INFO	Logging level

---

Dataset

NCSRD-DS-5GDDoS v3.0 — DOI: 10.5281/zenodo.13900057

File	Size	Description
amari_ue_data_merged_with_attack_number.csv	241.5 MB	Primary ML file — labeled, 6 classes
amari_ue_data_classic_tabular.csv	143.6 MB	UE metrics, Classic cells
amari_ue_data_mini_tabular.csv	87.3 MB	UE metrics, Mini cell
enb_counters_data_classic_tabular.csv	72.2 MB	Cell-level eNB counters
enb_counters_data_mini_tabular.csv	38.2 MB	Mini cell counters
mme_counters.csv	37.1 MB	NAS-layer MME counters
summary_report.xlsx	18.0 kB	Attack summary per UE

Attack labels (attack_number column): 0 benign · 1 SYN flood · 2 UDP flood · 3 ICMP flood · 4 DNS flood · 5 GTP-U flood

---

Project Alignment

EU Project	Integration
MARE	Agentic AI for 5G Security

---

Citation

@dataset{ncsrd_5gddos_2024,
  title     = {NCSRD-DS-5GDDoS: 5G Radio & Core Metrics -- DDoS Attack Dataset},
  author    = {NCSRD and Space Hellas},
  year      = {2024},
  doi       = {10.5281/zenodo.13900057},
  publisher = {Zenodo},
  license   = {CC BY 4.0},
  note      = {EU Horizon PRIVATEER project, Grant 101096110}
}

---

License

MCP server code: MIT. Dataset: CC BY 4.0 (cite the DOI above).