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/                    # 158 tests (pytest)
├── requirements.txt          # runtime dependencies
├── requirements-dev.txt      # + test/lint tooling
├── Dockerfile
└── 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 (credentials list) with an "accept after N failures" lure (accept_after_failures)
• Optional live payload capture: with fetch_downloads: true, a wget/curl for a URL makes the honeypot host fetch and store the file (SHA256-named, in data/malware/), feeding the YARA/alerting pipeline. Off by default — it makes outbound requests, so only enable it behind strict egress controls. Bounded by max_download_bytes and download_timeout.

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:

1. Threat Analyzer — Pattern matching against 35+ indicators (reverse shells, download cradles, privilege escalation, lateral movement, container escape, encoded payloads)
2. Session Correlator — Links sessions from the same IP, detects campaigns via shared credentials and command fingerprints
3. Behavioral Fingerprinter — Classifies timing (automated/human), credential strategy (dictionary/spray/targeted), and identifies tools (Mirai, cryptominers, manual operators)
4. C2 Detector — Matches against known C2 framework signatures
5. Database — All data persisted to SQLite for dashboard queries and historical analysis

---

Testing

source .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest tests/ -v

158 passed

CI runs the suite on Python 3.9–3.12 and checks formatting with black on every push and pull request (.github/workflows/ci.yml).

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_rate_limiter.py	6	Per-IP limits, global flood cap, reset
test_ssh_auth.py	5	Credential acceptance, accept-after-failures
test_threat_analyzer.py	15	Pattern matching, classification, scoring

---

Deployment

Docker

# Build
docker build -t phantomtrap .

# Run — map honeypot ports and keep the dashboard local.
# The container runs as a non-root user; -p maps host ports without host root.
docker run -d --name phantomtrap \
  -p 22:22 \
  -p 127.0.0.1:8080:8080 \
  -v phantomtrap-data:/opt/phantomtrap/data \
  phantomtrap

Captured sessions, malware, and signatures persist in the phantomtrap-data volume. For containment, run it on an isolated network and restrict egress (see Network Recommendations below) — this matters especially if you enable SSH download capture.

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