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

```bash
# 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`:
```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**

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

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

**Step 2 — Pull a model**

```bash
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**

```bash
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`:
```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.

```bash
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)

```bash
# 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

```bash
# 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:
```bash
# 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.

```bash
# 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`](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.

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

### `server` — Start the MCP server

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

### `detect` — Classify 5G telemetry

```bash
# 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

```bash
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

```bash
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

```bash
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

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

### `dataset` — Manage the NCSRD dataset

```bash
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

```bash
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](https://doi.org/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

```bibtex
@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).
