ShadowTrap

Multi-protocol network honeypot for threat intelligence and attack pattern analysis. Listens on common service ports, captures payloads, logs credentials, and provides a real-time dashboard for monitoring attacker behavior.

Features

• 21 Protocol Emulators — SSH, HTTP/HTTPS, FTP, Telnet, SMTP, DNS, MySQL, PostgreSQL, MSSQL, Redis, MongoDB, Elasticsearch, Memcached, RDP, VNC, SMB, LDAP, SNMP, SIP, Docker API
• Interactive Shell — Dynamic fake filesystem (shared across SSH/Telnet/FTP), pipe support, sudo escalation, wget/curl URL capture
• Honeytokens — Planted fake AWS keys, SSH keys, .env files, .git-credentials that trigger alerts when accessed
• Rich Fake Data — MySQL with 7 databases and user tables, Redis with 16 pre-seeded keys, Elasticsearch with searchable indices
• Payload Capture — Full session payload dumps with SHA-256 hashing for forensic analysis
• GeoIP Resolution — Automatic geolocation of attacker IPs with caching
• Threat Scoring — Configurable weights for different attack behaviors (brute force, exploit attempts, data exfil)
• Alerting — Webhook (with HMAC signatures) and syslog (RFC 5424) for external notification
• HTTPS Dashboard — Real-time monitoring with SSE live streaming, attack map, timeline charts, attacker profiles
• GitHub Integration — Report issues directly from the dashboard

Quick Start

# Clone and install
git clone https://github.com/rayketcham/shadowtrap.git
cd shadowtrap
pip install -r requirements.txt

# Run (requires root for privileged ports, or use port forwarding)
sudo python3 honeypot.py

The dashboard will be available at https://localhost:8443 (default credentials: admin/changeme).

Configuration

All settings are in config.py and can be overridden via environment variables:

Variable	Default	Description
HONEYPOT_SERVICES	(all)	Comma-separated whitelist of services to start
HONEYPOT_ENABLE_<SVC>	true	Enable/disable individual services
HONEYPOT_PORT_<SVC>	(standard)	Override port for a service
WEB_PORT	8443	Dashboard HTTPS port
WEB_ALLOWED_IPS	(empty)	IP whitelist for dashboard (comma-separated)
ALERT_WEBHOOK_URL	(empty)	Webhook URL for alert notifications
ALERT_SYSLOG_HOST	(empty)	Syslog server for alert forwarding
CAPTURE_ENABLED	true	Enable payload capture
RETENTION_DAYS	90	Days to retain connection data
LOG_LEVEL	INFO	Logging verbosity

Run specific services only

HONEYPOT_SERVICES=ssh,http,mysql sudo python3 honeypot.py

Custom ports

HONEYPOT_PORT_SSH=2222 HONEYPOT_PORT_HTTP=8080 sudo python3 honeypot.py

Production Deployment

A systemd service file and deployment script are included:

# Install as systemd service
sudo bash install.sh

# Or deploy to a VPS
sudo bash deploy-vps.sh

The systemd unit runs with security hardening: NoNewPrivileges, ProtectSystem=strict, PrivateTmp, and CAP_NET_BIND_SERVICE for binding privileged ports without full root.

Dashboard

The web dashboard provides:

• Overview — Total events, unique attackers, active services, threat distribution
• Live Feed — Real-time event stream via Server-Sent Events
• Attack Map — Geographic visualization of attacker origins
• Timeline — Configurable time-series charts of attack activity
• Attacker Profiles — Detailed view per IP: events, credentials tried, sessions, threat assessment
• Credentials — Most commonly attempted username/password combinations
• Alerts — Unacknowledged high-severity events

Testing

pip install -r requirements-dev.txt
python -m pytest tests/ -v

93 tests covering database operations, authentication, crypto, network utilities, payload capture, filesystem emulation, and service behavior.

Architecture

honeypot.py          Main orchestrator — starts services, dashboard, geo resolver
services/
  base.py            BaseService — connection handling, event recording, alerting
  fakefs.py          Shared fake filesystem for interactive shells
  ssh.py             SSH with interactive shell, pipes, sudo, honeytokens
  http.py            HTTP/HTTPS with login forms, SQL injection detection
  mysql.py           MySQL with 7 databases, user tables, API keys
  redis.py           Redis with 16 pre-seeded keys
  ...                (21 services total)
web/
  server.py          Pure asyncio HTTPS server with SSE
  api.py             REST API endpoints
  auth.py            Session-based authentication
  templates/         Dashboard SPA
utils/
  alerting.py        Webhook + syslog alert dispatch
  capture.py         Payload capture with SHA-256
  crypto.py          TLS certificate generation
  network.py         Rate limiting, connection tracking
database.py          SQLite with WAL mode
geo_lookup.py        GeoIP resolution with background worker
config.py            Centralized configuration

Design Principles

• Passive observation — listen, log, never engage or retaliate
• Capture everything — full payload dumps for post-incident analysis
• Minimal fingerprint — services mimic real software just enough to elicit attacker behavior
• Safe isolation — never bridges to real services or networks
• Security-first — no real credentials, all data is fake bait

License

MIT