Medusa is a real-time DDoS defense system that leverages eBPF/XDP to detect, analyze, and block malicious traffic at the kernel level with minimal overhead. It combines kernel-space packet filtering with userspace statistical anomaly detection and a React-based dashboard.
| Protocol | Detection | Description |
|---|---|---|
| TCP | Flood / Port Scan | SYN flood detection, closed port analysis, packet count threshold |
| UDP | Flood | Volume-based anomaly detection with Z-score analysis |
| ICMP | Ping Flood | Echo request blocking via XDP |
| MAC | Spoofing | MAC address blacklist at driver level |
React Dashboard (port 3000)
↓ Axios
Gin REST API (port 8081)
↓
Monitor / Analyzer / Blocker (Go userspace)
↓ cilium/ebpf
XDP Program (kernel space) ←→ BPF Maps (ip_blacklist, mac_blacklist)
↓
Network Interface (driver level)
- Linux kernel 5.15+ with eBPF support
- Go 1.23+
- Clang 14+ / LLVM 14+
- MySQL 8.0+ (or MariaDB)
- Node.js 18+
- Root privileges for XDP attachment
# Backend
cd Back
go generate ./core/... # Compile eBPF programs
go build -o medusa .
sudo ./medusa
# Frontend
cd Front
npm install
npm start| Variable | Default | Description |
|---|---|---|
DB_USER |
root |
MySQL username |
DB_PASSWORD |
qwer1234 |
MySQL password |
DB_HOST |
127.0.0.1 |
MySQL host |
DB_PORT |
3306 |
MySQL port |
DB_NAME |
ddos |
Database name |
Medusa/
├── Back/
│ ├── main.go # Entry point, pinned map cleanup
│ ├── DDOS.go # Orchestrator (starts all goroutines)
│ ├── core/
│ │ ├── xdp.c # eBPF/XDP kernel program
│ │ ├── Monitor.go # Packet capture via ring buffer
│ │ ├── Analyzer.go # Statistical anomaly detection
│ │ └── Blocker.go # IP/MAC blacklist management
│ ├── handler/
│ │ └── Handler.go # REST API endpoints (Gin)
│ ├── logger/
│ │ └── Logger.go # MySQL operations
│ ├── config/
│ │ ├── config.go # DB, GeoIP, Gin initialization
│ │ └── GeoLite2-Country.mmdb
│ ├── common/
│ │ └── common.go # Graceful shutdown
│ ├── types/
│ │ └── types.go # Shared type definitions
│ └── signal/
│ └── signal.go # WaitGroup synchronization
├── Front/
│ └── src/
│ ├── App.js # Main router
│ ├── Home.js # Dashboard (graph, status, packets)
│ ├── IPT.js # IP/MAC block/allow management
│ ├── Setting.js # Protocol blocking toggles
│ └── store.js # Redux state
└── Attack/ # Test attack tools
| Method | Endpoint | Description |
|---|---|---|
| GET | /packet/count/all |
Packet counts (60s window, 5s intervals) |
| GET | /packet/count/:ip |
Packet counts for specific IP |
| GET | /packet/count/recent/:num |
Last N packets |
| GET | /suspicious/ip/list |
List suspicious IPs |
| GET | /block/ip/list |
List blocked IPs |
| PUT | /block/ip/on |
Block an IP address |
| PUT | /block/ip/off |
Unblock an IP address |
| GET | /block/mac/list |
List blocked MACs |
| PUT | /block/mac/on |
Block a MAC address |
| PUT | /block/mac/off |
Unblock a MAC address |
| GET | /allow/ip/list |
List allowed IPs |
| PUT | /allow/ip/on |
Add IP to allow list |
| PUT | /allow/ip/off |
Remove from allow list |
| Method | Mechanism | Action |
|---|---|---|
| Threshold | >500 packets from single source | Auto-block (reason=4) |
| Z-score | Packet size statistical anomaly per port | Flag suspicious |
| Port scan | Traffic to closed ports | Mark suspicious (reason=2) |
| Host check | nmap liveness verification | Mark suspicious (reason=2) |
| Blacklist | BPF map lookup at XDP level | XDP_DROP (kernel) |
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Copyright 2025 BoanLab @ DKU