Real-time DDoS attack visualization on a 3D globe with a 6-layer threat intelligence pipeline, hybrid ML classification, SQLite persistence, and MITRE ATT&CK mapping.
- 3D Globe Visualization — Three.js with NASA Blue Marble texture, severity-colored arcs, atmospheric glow, city dots
- Real-time WebSocket Streaming — attacks broadcast to all connected clients with 500-packet history
- 6-Layer Threat Intelligence Pipeline — Cloudflare Radar → AbuseIPDB → GeoLite2 → ML → MITRE ATT&CK → SQLite
- 3-Tier ML Classification — CIC-DDoS2019 (99.65% binary / 94.03% multi-class) → IP Classifier (GradientBoosting + StandardScaler) → Rules fallback
- MITRE ATT&CK Mapping — 16 attack types mapped to T1498/T1499/T1110/T1046 techniques
- SQLite Persistence — 30-day history, CSV export, analytics endpoints
- SOC Dashboard — live stats, trend indicators, attack log, severity distribution, top countries
- Honeypot Integration — Cowrie SSH honeypot event monitoring
- Packet Sniffer — Scapy-based SYN/UDP/ICMP/DNS flood detection
- Rate Limiting — 30 req/min on ingest endpoint (slowapi)
- Optional API Auth — X-API-Key header (disabled by default for demo use)
- TypeScript Frontend — strict mode, typed interfaces for all data structures
- Docker Support — multi-stage builds for backend and frontend
- CI/CD — GitHub Actions: pytest + vitest + docker build on every push
┌─────────────────────────────────────────────────────────────┐
│ Frontend — React 18 + Three.js + TypeScript │
│ 3D Globe | SOC Dashboard | Attack Log | MITRE Tags │
└──────────────────────────┬──────────────────────────────────┘
│ WebSocket ws://<host>:8000/ws/attacks
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Backend (Python 3.11) │
│ │
│ Ingest → Geo → AbuseIPDB → ML → MITRE → Broadcast → SQLite │
│ │
│ ┌──────────────┬──────────────┬─────────────────────────┐ │
│ │ Cloudflare │ AbuseIPDB │ MaxMind GeoLite2 │ │
│ │ Radar API │ Cache+TTL │ (simulated fallback) │ │
│ └──────────────┴──────────────┴─────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 3-Tier ML Classifier │ │
│ │ 1. CIC-DDoS2019 Binary (99.65% accuracy) │ │
│ │ 2. CIC-DDoS2019 Multi (94.03% accuracy) │ │
│ │ 3. IP Classifier + Scaler (GradientBoosting) │ │
│ │ 4. Rules fallback (always available) │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────┬───────────────────────┬──────────────────────┘
│ │
┌───────┴───────┐ ┌─────────┴────────┐
│ Honeypot │ │ Packet Sniffer │
│ (Cowrie SSH) │ │ (Scapy — 5 ops) │
└───────────────┘ └──────────────────┘
- Python 3.11+
- Node.js 20+
- Git
git clone https://github.com/your-username/ddos-attack-map.git
cd ddos-attack-map
cp .env.example .envThe project runs without any API keys — simulated data is used automatically as fallback.
pip install -r requirements.txt
cd backend
python main.pyBackend available at:
- API:
http://localhost:8000 - Swagger UI:
http://localhost:8000/docs - WebSocket:
ws://localhost:8000/ws/attacks
cd frontend/app
npm install
npm run devOpen http://localhost:5173
docker compose up --build| Service | URL |
|---|---|
| Frontend | http://localhost |
| Backend API | http://localhost:8000 |
| Swagger UI | http://localhost:8000/docs |
docker compose downCopy .env.example to .env and fill in the values you want:
# AbuseIPDB — IP reputation scoring (1000 req/day free)
# Register at: https://www.abuseipdb.com/register
ABUSEIPDB_API_KEY=
# Cloudflare Radar — real DDoS data (public API, optional token)
# Get at: https://dash.cloudflare.com/profile/api-tokens
CLOUDFLARE_RADAR_TOKEN=
# MaxMind GeoLite2 — IP geolocation
# Register and download GeoLite2-City.mmdb from: https://dev.maxmind.com
# Place the file at: data/GeoLite2-City.mmdb
MAXMIND_LICENSE_KEY=
# CORS allowed origins (comma-separated, for production)
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
# Optional API key for the /api/attacks/report endpoint
# Leave empty to disable authentication (demo mode)
# Generate: python -c "import secrets; print(secrets.token_hex(32))"
API_SECRET_KEY=Everything is optional — the system has graceful fallbacks for all missing configurations.
The project ships with a rules-based fallback that requires no training. To enable the CIC-DDoS2019 models:
The CIC-DDoS2019 dataset comes in two formats:
Option A — Pre-extracted CSV (recommended)
Download directly from Kaggle as CSV files:
https://www.kaggle.com/datasets/dhoogla/cicddos2019
Files are named like Friday-WorkingHours-Afternoon-DDos.pcap_ISCX.csv — despite the .pcap in the name, they are plain CSV files with pre-extracted network flow features.
Option B — Raw PCAP (binary)
If you downloaded raw PCAP captures from the UNB official site, convert them first using CICFlowMeter:
# Download CICFlowMeter: https://github.com/ahlashkari/CICFlowMeter/releases
java -jar CICFlowMeter.jar -f capture.pcap -c output/Then use the generated CSV with the training script.
cd backend
# Multi-class classifier (11 attack types, ~94% accuracy)
python train_cic_model.py --data data/Friday-WorkingHours-Afternoon-DDos.pcap_ISCX.csv
# Binary classifier (BENIGN vs DDoS, ~99% accuracy — faster)
python train_cic_model.py --data data/Friday-WorkingHours-Afternoon-DDos.pcap_ISCX.csv --binary
# Multiple CSV files combined
python train_cic_model.py --data data/combined.csv --max-samples 30000Trained models are saved to models/ and loaded automatically on next startup.
Detects SYN flood, UDP flood, ICMP flood, DNS amplification, and high-rate traffic in real time.
# Linux/macOS
sudo python sniffer/packet_sniffer.py --interface eth0 --api http://localhost:8000
# Windows (run terminal as Administrator)
python sniffer/packet_sniffer.py --interface "Ethernet" --api http://localhost:8000Monitors a running Cowrie SSH honeypot and forwards events to the map.
# Point it at your Cowrie JSON log
python honeypot/honeypot_feed.py --log ~/cowrie/var/log/cowrie/cowrie.json
# Test mode (generates simulated honeypot events)
python honeypot/honeypot_feed.py --test --api http://localhost:8000| Method | Endpoint | Description |
|---|---|---|
| GET | /api/stats |
System stats (realtime + database) |
| GET | /api/attacks/recent?limit=50 |
Recent attacks (in-memory session) |
| GET | /api/attacks/by-country/{code} |
Filter attacks by source country |
| POST | /api/attacks/report |
Ingest attack from external source (rate limited: 30/min) |
| GET | /api/db/attacks |
Query SQLite with filters (country, severity, type, IP, date range) |
| GET | /api/db/stats |
Aggregated database analytics |
| GET | /api/db/timeline?hours=24 |
Attacks per hour (for charts) |
| GET | /api/db/top/ips |
Top attacking IPs |
| GET | /api/db/top/countries |
Top source countries |
| GET | /api/db/top/types |
Top attack types |
| GET | /api/db/export |
Download all attacks as CSV |
| GET | /api/ml/info |
Loaded ML models and accuracy |
| POST | /api/ml/predict-flow |
Classify network flow with CIC-DDoS2019 model |
Full interactive docs at http://localhost:8000/docs
For a complete walkthrough of all features — WebSocket, REST endpoints with curl examples, Packet Sniffer, Honeypot integration, ML training, and Docker — see EXECUTION_GUIDE.txt.
# Backend — 185 tests
cd backend
pytest tests/ -v
# Frontend — 17 tests
cd frontend/app
npm testInconsistentVersionWarning on startup (cosmetic — safe to ignore)
InconsistentVersionWarning: Trying to unpickle estimator RandomForestClassifier
from version 1.8.0 when using version 1.6.1.
The bundled CIC-DDoS2019 model files were serialized with scikit-learn 1.8.0.
The project pins scikit-learn==1.6.1, which is fully compatible at runtime — the warning is cosmetic and does not affect accuracy or functionality.
To suppress it entirely, retrain the models locally after installing the requirements:
cd backend
python train_cic_model.py --data <path-to-cic-ddos2019.csv> --binary
python train_cic_model.py --data <path-to-cic-ddos2019.csv>The pre-trained models are provided so the project runs out of the box without the dataset.
ddos-attack-map/
├── backend/
│ ├── main.py # FastAPI server, WebSocket, pipeline orchestration
│ ├── abuseipdb_client.py # IP reputation with cache and rate limiting
│ ├── geolocation.py # IP → coordinates (GeoLite2 + simulated fallback)
│ ├── cloudflare_radar.py # DDoS data from Cloudflare + realistic simulation
│ ├── database.py # SQLite persistence, analytics, CSV export
│ ├── threat_classifier.py # 3-tier ML: CIC models → IP classifier → rules
│ └── train_cic_model.py # Train Random Forest on CIC-DDoS2019 dataset
├── frontend/app/
│ ├── src/
│ │ ├── DDoSMap.tsx # Main component: 3D globe + SOC dashboard
│ │ ├── ErrorBoundary.tsx # React error boundary with fallback UI
│ │ ├── App.tsx # Root component
│ │ └── main.tsx # Entry point
│ ├── tsconfig.json
│ └── vite.config.ts
├── honeypot/
│ └── honeypot_feed.py # Cowrie SSH honeypot log monitor
├── sniffer/
│ └── packet_sniffer.py # Scapy packet capture and DDoS detection
├── docs/
│ ├── DATABASE_SCHEMA.md # SQLite schema reference
│ ├── TROUBLESHOOTING.md # Common issues and solutions
│ └── REFERENCES.md # 14 academic and technical references
├── deploy/
│ ├── nginx.conf # Reverse proxy config
│ └── README.md # Deployment guide
├── Dockerfile.backend
├── Dockerfile.frontend
├── docker-compose.yml
├── requirements.txt
└── .env.example
- Sharafaldin, I., Lashkari, A. H., Hakak, S., & Ghorbani, A. A. (2019). Developing Realistic Distributed Denial of Service Attack Dataset. IEEE International Conference on Big Data. — CIC-DDoS2019 Dataset
- @vishnurg — Turning Raw IP Data into a Global Cyber Threat Map
- @onmouse0ver — Automate Threat Analysis with AbuseIPDB
- @darkmarc — DDoS Attack Detection Techniques
- @nayangoel — ML in Cybersecurity: Beyond the Hype
- @genrunic — DDoS Detection Using Python Scapy
- @pythonandchill — Protect Your API From Abuse
- @pocketflow — FastAPI & WebSockets
Full reference list: docs/REFERENCES.md
- Kaspersky Cyberthreat Real-time Map
- Digital Attack Map (Google + Arbor Networks)
MIT — Educational use only. Never run on third-party networks without authorization.