AI-Augmented Adaptive Honeypot Framework
MIRAGE is an adaptive honeypot framework that traps, profiles, and deceives attackers using four coordinated deception protocols. Unlike passive honeypots that only log, MIRAGE actively wastes attacker resources, fingerprints their tools, extracts TTPs, plants trackable credentials, and alerts defenders in real time.
Key capabilities:
- 🪞 Multi-protocol service emulation (SSH, Telnet, HTTP, FTP, MySQL, Redis)
- ⏳ Progressive time dilation that wastes attacker compute
- 🐉 Ghost network that fakes an entire corporate infrastructure
- 🪤 Canary tokens that track stolen credentials across the internet
- 🤖 AI-powered attacker profiling and incident report generation
- 📊 Real-time SOC dashboard with attack map and session drilldowns
- 🔔 Telegram alerting with structured, de-duplicated SOC notifications
This is a defensive security tool. No code in this repository attacks or exploits any system. The fake credentials, shells, and services exist solely to deceive attackers who have already targeted the honeypot. All testing is performed against localhost or controlled environments.
Attacker (internet)
│
▼
┌─────────────────────────────────────────────┐
│ Layer 1: Exposure Surface │
│ SSH:22 HTTP:80 FTP:21 MySQL:3306 │
│ Redis:6379 Telnet:23 HTTPS:443 │
│ (Cowrie + OpenCanary in Docker) │
└──────────────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Layer 2: Detection Engine │
│ Fingerprint tools · Score threat │
│ Classify intent · Decide protocol │
└──────────────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Layer 3: Protocol Router │
│ Routes attacker to appropriate trap │
└──┬──────────┬──────────┬────────────┬───────┘
│ │ │ │
▼ ▼ ▼ ▼
DORMAMMU MIRAGE HYDRA CANARY
Time Service Ghost Token
dilation emulation network tracking
│ │ │ │
└──────────┴──────────┴────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
AI Engine Dashboard Alerting
Profiler React UI Telegram
Every command response gets progressively slower, wasting attacker compute while logging everything.
Command #1: ~0.3s delay
Command #10: ~0.8s delay
Command #30: ~1.8s delay
Command #50: ~2.8s delay (max 5s)
Formula: delay = 0.3 + (cmd_count × 0.05) + random(0, 0.2)
When attackers run network scans, MIRAGE responds with a fake corporate network: 15 ghost hosts (gateway, db-primary, redis-cache, jenkins, gitlab, k8s-master, etc.) with consistent hostnames, IPs, MAC addresses, and port/service mappings.
After 3 commands, fake credential files appear in the virtual filesystem:
/root/.aws/credentials— fake AWS keys with embedded tracking ID/var/www/html/.env— fake database password with tracking ID/root/.ssh/id_rsa_backup— fake SSH key with tracking ID
If the attacker uses these credentials anywhere, the tracking ID enables attribution.
Cowrie (SSH/Telnet) and OpenCanary (HTTP, FTP, MySQL, Redis) provide realistic service frontends that log every interaction.
| Layer | Technology |
|---|---|
| SSH/Telnet honeypot | Cowrie (Docker) |
| Multi-protocol honeypot | OpenCanary (Docker) |
| Protocol engine | Python 3.11, asyncio, asyncssh |
| Backend API | FastAPI + uvicorn |
| Real-time comms | WebSocket |
| Frontend dashboard | React 18, Vite |
| AI profiling | Ollama (local LLM) |
| IP intelligence | AbuseIPDB |
| Alerting | Telegram Bot API |
| Containerization | Docker Compose (6 services) |
- Docker & Docker Compose
- Python 3.11+ (for simulation scripts)
- Ollama (optional, for AI profiling)
# Clone the repository
git clone https://github.com/your-org/mirage.git
cd mirage
# Configure environment
cp .env.example .env
# Edit .env with your Telegram token, AbuseIPDB key, etc.
# (Optional) Install Ollama for AI profiling
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:2b
# Launch all services
make up
# Verify everything is running
make ps| Service | URL |
|---|---|
| SOC Dashboard | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| SSH Honeypot (Cowrie) | ssh root@localhost -p 22 |
| Interactive Shell (Demo) | ssh root@localhost -p 2222 |
make simulateThis sends a realistic multi-phase attack scenario (randomly chosen from 5 scenarios) to the backend. Watch the dashboard and Telegram for real-time events.
mirage/
├── backend/ # FastAPI backend
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── main.py # API + WebSocket server
│ ├── models.py # Pydantic event schemas
│ ├── alerting.py # Telegram alerter (anti-spam)
│ ├── storage.py # JSONL log read/write
│ └── pdf_report.py # PDF report generation
│
├── protocols/ # Deception protocol engine
│ ├── router.py # Protocol routing logic
│ ├── interactive_server.py # asyncssh demo shell (port 2222)
│ ├── Dockerfile
│ ├── dormammu/
│ │ ├── dormammu.py # Shell trap + command handling
│ │ ├── virtual_fs.py # Fake filesystem layer
│ │ └── time_dilation.py # Progressive delay formula
│ ├── hydra/
│ │ └── ghost_network.py # Fake internal network (15 hosts)
│ ├── canary/
│ │ ├── canary_tokens.py # Token generation + planting
│ │ └── token_store.py # Token → session mapping
│ └── mirage_svc/
│ ├── service_router.py # Routes to fake services
│ ├── fake_mysql.py # MySQL protocol emulation
│ ├── fake_redis.py # Redis protocol emulation
│ └── fake_http.py # Fake admin panel
│
├── ai_engine/ # AI-powered analysis
│ ├── profiler.py # LLM-based session profiling
│ ├── classifier.py # Rule-based tool fingerprinting
│ ├── report_generator.py # Incident report builder
│ ├── ip_enrichment.py # AbuseIPDB integration
│ └── threat_intel.py # Threat intelligence enrichment
│
├── dashboard/ # React frontend
│ ├── Dockerfile
│ ├── package.json
│ └── src/
│ ├── App.jsx
│ └── components/
│ ├── EventFeed.jsx # Live event stream
│ ├── SessionView.jsx # Per-session drilldown
│ └── AttackMap.jsx # Leaflet geolocation map
│
├── logger/ # Log aggregation
│ ├── watcher.py # Tails Cowrie JSON → backend
│ └── normalizer.py # Event format normalization
│
├── alerting/ # Telegram notifications
│ ├── bot.py # Interactive Telegram bot
│ └── templates.py # SOC-grade alert templates
│
├── cowrie/ # Cowrie SSH honeypot config
│ ├── cowrie.cfg
│ └── userdb.txt
│
├── opencanary/ # OpenCanary config
│ ├── Dockerfile
│ └── opencanary.conf
│
├── tests/ # Test suite
│ ├── simulate.py # Attack scenario simulator
│ ├── smoke_test.sh # End-to-end smoke test
│ ├── test_dormammu.py
│ ├── test_canary.py
│ ├── test_backend.py
│ └── test_ai_engine.py
│
├── docs/ # Documentation
│ ├── PROTOCOLS.md # Protocol design deep dive
│ ├── DEPLOYMENT.md # Deployment guide
│ ├── TESTING.md # Testing strategy
│ └── DEMO_SCRIPT.md # Hackathon demo walkthrough
│
├── reports/ # Generated incident reports (gitignored)
├── docker-compose.yml # Service orchestration
├── Makefile # Dev commands
├── .env.example # Environment variable template
├── ARCHITECTURE.md # Technical architecture doc
├── CHANGELOG.md # Version history
├── SECURITY.md # Security policy
├── LICENSE # MIT License
└── README.md # ← You are here
| Method | Endpoint | Description |
|---|---|---|
POST |
/event |
Ingest a honeypot event |
GET |
/events |
List events (with filters) |
GET |
/sessions |
List all attacker sessions |
GET |
/report/{session_id} |
Generate incident report |
GET |
/report/{session_id}/pdf |
Download PDF report |
GET |
/export/events |
Export events as JSON/CSV |
WS |
/ws |
Real-time event stream |
GET |
/health |
Liveness check |
Full API docs available at http://localhost:8000/docs (Swagger UI) when running.
# Run backend locally (hot reload)
make backend-dev
# Run dashboard locally (hot reload)
make dashboard-dev
# Run unit tests
make test
# Run smoke test against live stack
make test-smoke
# View logs
make logs