PhantomTrap
High-interaction honeypot framework with behavioral fingerprinting, campaign detection, and a real-time dashboard.
## Overview
PhantomTrap deploys realistic SSH, HTTP, and MySQL honeypots that are designed to be indistinguishable from real services. It captures attacker sessions, correlates activity across services, identifies known attack tools, and presents everything through a live web dashboard.
**Key capabilities:**
- **Anti-fingerprinting** — Consistent system identity across all services (kernel, hostname, users, /proc). Attackers running `uname -a` over SSH get the same kernel shown in HTTP `phpinfo()` and MySQL `@@version_comment`.
- **Behavioral analysis** — Command timing classification (automated vs. human), n-gram fingerprinting, credential pattern detection (dictionary, spray, targeted).
- **Campaign detection** — Cross-IP correlation via shared credential lists and command sequences. Identifies coordinated attacks from botnets and scan campaigns.
- **C2 identification** — Signature matching for Cobalt Strike, Metasploit, Empire, Mirai, and other frameworks.
- **Real-time dashboard** — WebSocket-powered SPA with live attack feed, session drill-down, attacker profiles, and campaign timelines.
## Architecture
┌──────────────────────────┐
│ HoneypotManager │
│ (core/manager.py) │
│ │
│ SystemProfile │
│ RateLimiter │
│ SessionDatabase │
│ ThreatAnalyzer │
│ SessionCorrelator │
│ BehavioralFingerprinter │
└────┬────┬────┬────┬──────┘
│ │ │ │
┌──────────────┘ │ │ └──────────────┐
▼ ▼ ▼ ▼
┌─────────────┐ ┌────────────┐ ┌─────────────┐ ┌───────────┐
│ SSH :22 │ │ HTTP :80 │ │ MySQL :3306 │ │ Dashboard │
│ asyncssh │ │ aiohttp │ │ raw TCP │ │ :8080 │
└─────────────┘ └────────────┘ └─────────────┘ └───────────┘
## Quick Start
# Clone the repository
git clone https://github.com/SP1R4/PhantomTrap.git
cd PhantomTrap
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Create data directories
mkdir -p data/{malware,signatures,sessions,logs}
# Generate SSH host key (required for SSH honeypot)
ssh-keygen -t rsa -b 2048 -f data/ssh_host_key -N ""
# Run
sudo python3 core/manager.py
The dashboard will be available at `http://127.0.0.1:8080` (default credentials: `admin` / `changeme123`).
## Configuration
All settings live in `config/honeypot_config.json`. Key sections:
### Services
{
"honeypots": [
{"type": "ssh", "port": 22, "enabled": true, "accept_after_failures": 3},
{"type": "http", "port": 80, "enabled": false, "personality": "apache"},
{"type": "mysql", "port": 3306, "enabled": false}
]
}
The HTTP honeypot supports `apache`, `nginx`, and `iis` personalities. All headers, error pages, and default pages match the chosen server type.
### Alerting
{
"alerts": {
"min_threat_level": 3,
"channels": {
"console": {"enabled": true},
"file": {"enabled": true, "path": "data/alerts.log"},
"email": {"enabled": false, "smtp_server": "smtp.gmail.com", "...": "..."},
"telegram": {"enabled": false, "bot_token": "...", "chat_id": "..."},
"webhook": {"enabled": false, "url": "https://..."}
}
}
}
### Dashboard
{
"dashboard": {
"enabled": true,
"port": 8080,
"bind_address": "127.0.0.1",
"username": "admin",
"password": "changeme123"
}
}
## Project Structure
.
├── core/
│ ├── manager.py # Main orchestrator
│ ├── database.py # SQLite session storage (async)
│ ├── system_profile.py # Consistent randomized system identity
│ └── rate_limiter.py # Per-IP sliding window rate limiter
│
├── honeypots/
│ ├── ssh_honeypot.py # SSH — 30+ commands, pipes, redirects, shell chaining
│ ├── http_honeypot.py # HTTP — server personalities, session cookies, stateful login
│ ├── mysql_honeypot.py # MySQL — extended protocol, SHOW responses, error codes
│ └── fake_filesystem.py # In-memory Ubuntu 22.04 filesystem (~500 files)
│
├── analysis/
│ ├── threat_analyzer.py # 35+ malicious patterns, C2 detection, advanced scoring
│ ├── correlator.py # Cross-session IP correlation, campaign clustering
│ ├── behavioral.py # Timing analysis, n-gram fingerprinting, tool identification
│ ├── c2_patterns.py # Cobalt Strike, Metasploit, Empire, Mirai signatures
│ ├── signature_gen.py # YARA rule generation
│ ├── alert_system.py # Multi-channel alerting
│ └── intelligence.py # GeoIP, IP reputation
│
├── dashboard/
│ ├── server.py # REST API + WebSocket server
│ └── static/ # SPA frontend (HTML/CSS/JS, no build step)
│
├── config/
│ └── honeypot_config.json # Main configuration
│
├── tests/ # 146 tests (pytest)
├── requirements.txt
└── LICENSE
## Honeypot Details
### SSH Honeypot
- Interactive shell with 30+ commands (`ls`, `cat`, `wget`, `curl`, `ps`, `netstat`, `df`, `free`, `top`, `ifconfig`, `find`, `grep`, etc.)
- Shell features: pipes (`|`), redirects (`>`, `>>`), chaining (`&&`, `||`, `;`), environment variables, command substitution
- Realistic `/proc` filesystem (cpuinfo, meminfo, uptime — all derived from SystemProfile)
- `/etc/passwd` with 21 users, consistent `/etc/hostname`, `/etc/os-release`
- `.bash_history` grows with attacker commands
- Configurable credential acceptance with "accept after N failures" option
### HTTP Honeypot
- Server personality system (Apache/nginx/IIS) — headers, error pages, and default pages all match
- Attack-path responses: `/wp-admin`, `/.env`, `/.git/HEAD`, `/phpinfo.php`, `/phpmyadmin`, `/actuator`, `/api/`
- Session cookies (`PHPSESSID`) with stateful login flow
- Dynamic headers: `ETag`, `Last-Modified`, `X-Request-ID`, `Cache-Control`
- Timing variance to mimic real server response times
### MySQL Honeypot
- MySQL wire protocol implementation with 8 COM_* commands
- `SHOW DATABASES`, `SHOW TABLES`, `SHOW ENGINES`, `SHOW VARIABLES`, `SHOW STATUS`, `SHOW PROCESSLIST`
- Per-database table schemas (webapp, customers, mysql, information_schema, performance_schema)
- `SELECT` queries against fake data, `information_schema` queries
- Proper MySQL error codes (1064, 1146, 1049) with SQL states
- Incrementing connection IDs
## Analysis Pipeline
Every session flows through:
## Testing
source .venv/bin/activate
pip install pytest pytest-asyncio pytest-timeout
python -m pytest tests/ -v
147 passed
| Test Suite | Tests | Coverage Area |
|------------------------|-------|--------------------------------------------------|
| test_behavioral.py | 18 | Timing, n-grams, credential patterns, tool ID |
| test_correlator.py | 8 | IP linking, campaign detection |
| test_dashboard.py | 19 | API endpoints, auth, WebSocket, pagination |
| test_database.py | 15 | Session CRUD, profiles, campaigns, stats, alerts |
| test_fake_filesystem.py| 25 | /proc, ls, globs, paths, file ops, content |
| test_http_honeypot.py | 19 | Routes, cookies, headers, personalities |
| test_mysql_honeypot.py | 18 | Protocol, COM_PING, SHOW, errors, connection IDs |
| test_threat_analyzer.py| 15 | Pattern matching, classification, scoring |
## Deployment
### Systemd (Production)
# /etc/systemd/system/phantomtrap.service
[Unit]
Description=PhantomTrap Honeypot
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/phantomtrap
ExecStart=/opt/phantomtrap/.venv/bin/python3 core/manager.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
sudo systemctl enable phantomtrap
sudo systemctl start phantomtrap
### Network Recommendations
- Deploy on a dedicated VM or isolated VLAN
- Allow inbound on honeypot ports only
- Block or restrict outbound traffic (except DNS, NTP, alerting)
- Bind the dashboard to `127.0.0.1` and access via SSH tunnel
## Legal
**For authorized security research and network defense only.** Deploy only on infrastructure you own or have explicit written permission to monitor. Ensure proper containment to prevent the honeypot from being used as a pivot point. Comply with all applicable laws and regulations.
## License
MIT License. See [LICENSE](LICENSE) for details.