Honeypot Module¶
Network service honeypot and monitoring system. Emulates fake TCP services (SSH, Telnet, HTTP, FTP) to detect and log attacker activity, with WiFi and network anomaly monitoring.
Configuration
Enable in idf.py menuconfig → Espilon Bot Configuration → Modules → Honeypot Module
Config flag: CONFIG_MODULE_HONEYPOT
Overview¶
The Honeypot module turns the ESP32 into a decoy device that attracts and logs unauthorized access attempts. All interactions are reported to the C2 server in real-time.
┌──────────────────────────────────────────────────┐
│ Honeypot Module │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Fake TCP Services │ │
│ │ ┌────┐ ┌──────┐ ┌────┐ ┌───┐ │ │
│ │ │SSH │ │Telnet│ │HTTP│ │FTP│ │ │
│ │ │:22 │ │:23 │ │:80 │ │:21│ │ │
│ │ └────┘ └──────┘ └────┘ └───┘ │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ WiFi Monitor │ │ Net Monitor │ │
│ │ (rogue APs, │ │ (ARP spoof, │ │
│ │ deauth) │ │ port scans) │ │
│ └───────────────┘ └───────────────┘ │
│ │
│ NVS: "hp_cfg" (banners, thresholds) │
│ Events → C2 via "HP|..." prefix │
└──────────────────────────────────────────────────┘
Key Features¶
- Fake services: SSH, Telnet, HTTP, FTP with realistic banners
- Configurable banners: Customize service responses via NVS
- WiFi monitoring: Detect rogue APs, deauthentication attacks
- Network monitoring: ARP spoofing detection, port scan alerts
- Real-time reporting: All events streamed to C2 with attacker fingerprint
- Low resource: Lightweight TCP listeners, minimal RAM usage
Files¶
| File | Description |
|---|---|
cmd_honeypot.c / .h |
Command handlers and registration |
hp_tcp_services.c / .h |
TCP service manager (start/stop listeners) |
hp_wifi_monitor.c / .h |
WiFi promiscuous mode monitoring |
hp_net_monitor.c / .h |
Network traffic anomaly detection |
hp_config.c / .h |
NVS persistence (namespace hp_cfg) |
services/svc_ssh.c |
SSH service emulation |
services/svc_telnet.c |
Telnet service emulation |
services/svc_http.c |
HTTP service emulation |
services/svc_ftp.c |
FTP service emulation |
services/svc_common.h |
Shared service utilities |
Commands¶
hp_svc¶
Start, stop, or check status of a honeypot service.
Syntax:
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
service |
string | Yes | Service name: ssh, telnet, http, ftp |
action |
string | Yes | Action: start, stop, status |
Example:
c2:> send esp001 hp_svc ssh start
# SSH honeypot started on port 22
c2:> send esp001 hp_svc ssh status
# ssh: running, port=22, connections=3, last_activity=12s ago
hp_wifi¶
Start or stop the WiFi monitor. Detects rogue access points and deauthentication attacks in the area.
Syntax:
Events reported:
- Rogue AP detection (new BSSID, SSID cloning)
- Deauthentication frame floods
- Unusual probe request patterns
hp_net¶
Start or stop the network monitor. Detects ARP spoofing, port scanning, and other anomalies.
Syntax:
Events reported:
- ARP spoofing (MAC/IP mismatch)
- Port scan detection (multiple ports from single source)
- Unusual traffic patterns
hp_config_set¶
Set a honeypot configuration value.
Syntax:
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | Config type: banner, threshold |
key |
string | Yes | Config key (e.g., ssh, telnet, scan_rate) |
value |
string | Yes | Config value |
Examples:
# Customize SSH banner
c2:> send esp001 hp_config_set banner ssh "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.1"
# Set port scan detection threshold
c2:> send esp001 hp_config_set threshold scan_rate 10
hp_config_get¶
Get a specific configuration value.
Syntax:
hp_config_list¶
List all configuration values, optionally filtered by type.
Syntax:
hp_config_reset¶
Reset all configuration to factory defaults.
Syntax:
hp_status¶
Show the overall honeypot status: which services are running, monitor states, and event counts.
Syntax:
Response:
services: ssh=running telnet=stopped http=running ftp=stopped
wifi_monitor=on net_monitor=on
events: ssh_attempts=42 http_requests=15 arp_alerts=3
Event Format¶
Honeypot events are streamed to C2 using the HP| prefix in AGENT_DATA messages:
Event types:
| Type | Description |
|---|---|
SSH_CONN |
SSH connection attempt |
SSH_AUTH |
SSH authentication attempt (username/password) |
TELNET_CONN |
Telnet connection |
TELNET_CMD |
Command entered in telnet session |
HTTP_REQ |
HTTP request (method, path, user-agent) |
FTP_CONN |
FTP connection attempt |
FTP_AUTH |
FTP login attempt |
WIFI_ROGUE |
Rogue AP detected |
WIFI_DEAUTH |
Deauthentication flood detected |
NET_ARP_SPOOF |
ARP spoofing detected |
NET_PORTSCAN |
Port scan detected |
Usage Examples¶
Deploy SSH + HTTP Honeypot¶
# Start services
c2:> send esp001 hp_svc ssh start
c2:> send esp001 hp_svc http start
# Customize banners to match target environment
c2:> send esp001 hp_config_set banner ssh "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4"
c2:> send esp001 hp_config_set banner http "Apache/2.4.41 (Ubuntu)"
# Enable monitoring
c2:> send esp001 hp_wifi start
c2:> send esp001 hp_net start
# Check status
c2:> send esp001 hp_status
WiFi Security Monitoring¶
# Monitor for rogue APs and deauth attacks
c2:> send esp001 hp_wifi start
# Events stream to C2:
# HP|WIFI_DEAUTH|1708001234|AA:BB:CC:DD:EE:FF|count=50 target=FF:FF:FF:FF:FF:FF
# HP|WIFI_ROGUE|1708001240|11:22:33:44:55:66|ssid=CorpWiFi channel=6
NVS Storage¶
Namespace: hp_cfg
| Key | Type | Description |
|---|---|---|
banner_ssh |
string | SSH version banner |
banner_telnet |
string | Telnet welcome message |
banner_http |
string | HTTP server header |
banner_ftp |
string | FTP welcome banner |
thresh_* |
i32 | Detection thresholds |