T-Dongle Honeypot (CyberPot)

Category: Embedded Systems / Cybersecurity / Network Intrusion Detection / Honeypot
Platform: LilyGO T-Dongle S3 (ESP32-S3)
Framework: Arduino via PlatformIO | C++
Status: Active — Production Ready

---

Project Overview

T-Dongle Honeypot (branded on-device as CyberPot) is a fully functional network security honeypot and Network Intrusion Detection System (NIDS) embedded into the ultra-compact LilyGO T-Dongle S3 — a USB-stick-sized ESP32-S3 device with a small colour display and an APA102 RGB LED.

The device joins a WiFi network, enters a 60-second learning phase to memorise all legitimate devices on the network (via ARP table analysis), then arms itself and monitors for any new, unauthorised devices that appear. When an intrusion is detected — via ARP scan, direct SSH connection, or direct Telnet connection — the device immediately:

1. Triggers a visual alarm (flashing red display, strobing LED)
2. Sends an automated email alert via the Resend API
3. Presents fake service banners to probe/mislead the attacker
4. Waits for manual operator review and dismissal

The design philosophy combines active network scanning (ARP sweeping), passive service monitoring (SSH/Telnet sockets), and behavioral learning to create a comprehensive intrusion detection system in a device smaller than a USB thumb drive.

---

Core Systems

1. NIDS Learning Phase (60 Seconds)

On boot, the device enters a 60-second Learning Mode:

• The display shows "LEARNING" in yellow text with cyan shield icons
• The ARP sweeper runs continuously (see below)
• Every MAC address discovered during this period is automatically added to the knownMACs whitelist
• At the 60-second mark, learning mode deactivates, the display switches to "SECURE" in green, and the NIDS arms itself

2. Ultra-Fast ARP Network Sweeper

The heart of the NIDS engine — executes every 20ms (50 times per second):

1. Sends a UDP packet to the next sequential IP address in the local subnet (e.g., 192.168.1.X)
2. This forces the ESP32's lwIP network stack to broadcast an ARP Request for that IP
3. After triggering the ARP, reads the entire ARP table via etharp_get_entry() (lwIP internal API)
4. Any IP that responded (i.e., has an ARP entry) is extracted with its MAC address
5. The discovered MAC is passed to processDiscoveredDevice() for learning or intrusion checking
6. Cycles through all 254 host addresses — completes a full subnet sweep in approximately 5 seconds

This technique achieves remarkably fast network scanning using only the embedded lwIP stack — no external scanning libraries required.

3. Intrusion Classification Engine

processDiscoveredDevice() handles the core logic:

Learning Mode:

• New MACs are logged and added to the whitelist automatically
• Known MACs are silently ignored

Armed Mode:

• Known MACs are silently ignored
• Unknown MACs trigger the full intrusion response sequence
• The operator can whitelist the intruder on alarm dismissal (long press) or simply reset without whitelisting (short press)

4. SSH/Telnet Honeypot Sockets

The device runs two server sockets simultaneously:

Port 22 (SSH Honeypot):

• Accepts incoming TCP connections
• Sends a convincing fake SSH banner: SSH-2.0-OpenSSH_8.9p1 Ubuntu-3
• Immediately disconnects after banner delivery
• Triggers intrusion alert and email for untrusted source IPs

Port 23 (Telnet Honeypot):

• Accepts incoming TCP connections
• Sends a convincing fake Telnet banner: Ubuntu 22.04 LTS\r\nLogin:
• Immediately disconnects after banner delivery
• Triggers intrusion alert and email for untrusted source IPs

Both services maintain a trusted IP whitelist — repeated connections from the same trusted source are silently dropped without triggering alerts.

5. Email Alert System (Resend API)

When an intrusion is detected (ARP or socket-based):

• An HTTPS POST request is made to the Resend email API
• A formatted HTML email is sent to the configured recipient address
• Email subject: "CyberPot Intrusion Detected"
• Email body contains the attacker's IP address or MAC address
• Configured via constants in source: resendApiKey, emailTo, emailFrom

---

Visual Alarm System

Secure State

• Display shows "SECURE" in green text
• "CyberPot" subtitle in neon pink
• Cyan shield icons on both sides
• APA102 RGB LED smoothly cycles through orange → green → cyan → pink (beatsin8 animation at 15 BPM)
• Current device IP address shown at bottom

Learning State

• Display shows "LEARNING" in yellow text
• Same shield and badge layout as secure state
• LED animation continues normally

NIDS Intrusion Alert (Unknown MAC)

• Screen clears and draws red border
• "UNAUTHORIZED" in white text
• "DEVICE DETECTED" in neon pink
• Detected MAC address displayed
• Display and LED flash alternately red/black at 200ms intervals (5Hz strobe)
• Operator intervention required:
  • Short press (< 1 second): Reset alarm, MAC NOT whitelisted (will alert again)
  • Long press (> 1 second): Reset alarm, MAC permanently whitelisted

SSH/Telnet Intrusion Alert

• Same flashing red display as NIDS alert
• Shows "INTRUSION" and "ATTACKER IP" with the source IP address
• Same LED strobe pattern
• Same short/long press whitelist mechanism

---

Technical Architecture

Component	Detail
MCU	ESP32-S3
Display	Small TFT (T-Dongle S3 landscape, 160x80)
Display Library	TFT_eSPI
LED	APA102 RGB LED on GPIO 40 (DI) + 39 (CI)
LED Library	FastLED
WiFi	WPA2 station mode (configured SSID/password)
ARP Scanner	lwIP etharp_get_entry() + UDP probe trigger
Honeypot Ports	WiFiServer on ports 22 (SSH) and 23 (Telnet)
Email Alerts	Resend API (HTTPS POST)
HTTP Client	Arduino HTTPClient
Button	GPIO 0 — physical interrupt for alarm dismissal

---

Hardware Specifications (T-Dongle S3)

The LilyGO T-Dongle S3 is a USB-stick form factor device:

Spec	Detail
MCU	ESP32-S3
Display	Small colour TFT (SPI-connected)
LED	APA102 (SPI — DI/CI protocol)
Backlight Control	GPIO 38 (ACTIVE LOW on T-Dongle)
Display Rotation	Landscape 3 (flipped)
Physical Button	GPIO 0 — boot/user button
Form Factor	USB thumb drive / dongle

---

Configuration

The following constants must be set in the source before flashing:

Constant	Description
resendApiKey	Resend.com API key for email delivery
emailTo	Recipient email address for alerts
emailFrom	Sender email address (must be verified in Resend)
ssid	WiFi network name to join
password	WiFi network password

---

Operational Flow

Boot
  └── WiFi Connect
        └── Learning Phase (60 seconds)
              └── ARP Sweeper (every 20ms): discover + whitelist all MACs
                    └── Armed Phase
                          ├── ARP Sweeper (every 20ms): detect unknown MACs
                          │     └── Unknown MAC → Email Alert + Visual Alarm + Whitelist prompt
                          ├── SSH Server (port 22): accept + banner + disconnect
                          │     └── Untrusted IP → Email Alert + Visual Alarm
                          └── Telnet Server (port 23): accept + banner + disconnect
                                └── Untrusted IP → Email Alert + Visual Alarm

---

Use Cases

• Home network intrusion detection — alerts when an unknown device joins your WiFi
• Network security research — honeypot service for studying attacker behaviour
• Small business perimeter monitoring — compact, discreet device plugged into any USB port
• Security education — demonstrates ARP scanning, honeypot concepts, and IDS principles
• Penetration testing labs — detect unauthorised devices on isolated test networks
• Physical security — deploy at remote network locations for low-cost, low-footprint monitoring