🛡️ HID Keystroke Injector Detector — ESP32

⚠️ Support / Errors? If you encounter any issues, bugs, or compilation errors, please contact: 📧 contact@morariuandreiraul.com I'll do my best to help you as quickly as possible.

---

📖 Overview

HID Keystroke Injector Detector is an open-source security tool built for the ESP32 family. It monitors keyboard traffic in real-time and detects HID injection attacks — also known as BadUSB, Rubber Ducky, or keystroke injection attacks — by analyzing the timing between keystrokes.

A normal human types at 40–80 WPM (~200–400 ms between keystrokes). HID injectors can type thousands of characters per second (1–10 ms intervals). This tool flags that anomaly, triggers alerts, and logs the event with timestamp to a web dashboard.

---

✅ Supported Boards

Board	USB HID Monitor	PS/2 Monitor	Status
ESP32 WROOM-32	❌ (no USB host)	✅ Via GPIO	✅ Fully supported
ESP32-S2	✅ Native USB OTG	✅ Via GPIO	✅ Fully supported
ESP32-S3	✅ Native USB OTG	✅ Via GPIO	✅ Fully supported
ESP32-C3	❌	✅ Via GPIO	✅ Supported (no USB)
ESP32-C6	❌	✅ Via GPIO	✅ Supported (no USB)

Note: For USB HID monitoring (detect Rubber Ducky plugged directly into USB), you need an ESP32-S2 or ESP32-S3. For PS/2 keyboard interception, all ESP32 variants work.

---

🔧 Features

• 🔍 Real-time keystroke timing analysis — detects superhuman typing speed
• 🌐 Built-in web dashboard — view alerts and logs from any browser on your network
• 🔔 Multi-channel alerts — LED blink, serial output, and web notification
• 🕐 NTP time sync — timestamps every event with real date/time
• 🔒 Password-protected dashboard — basic auth on the web interface
• 📊 Event log — last 50 events stored in memory with timestamps
• ⚙️ Configurable sensitivity — adjust detection thresholds in config.h
• 🔌 PS/2 keyboard interception — interrupt-driven, no missed keystrokes
• 💻 USB HID Host — on ESP32-S2/S3 with native USB OTG

---

📁 Project Structure

HID-Keystroke-Injector-Detector/
├── README.md                   ← You are here
├── .gitignore                  ← Protects your config.h from being published
├── HID_Detector/
│   ├── HID_Detector.ino        ← Main Arduino sketch (open this in Arduino IDE)
│   ├── config.h.example        ← ⬅️ COPY THIS to config.h and fill in your data
│   ├── ps2_reader.h            ← PS/2 keyboard interrupt reader
│   ├── detector.h              ← Attack detection logic
│   ├── web_interface.h         ← Embedded web dashboard HTML/CSS/JS
│   └── alerts.h                ← Alert system (LED, Serial, WiFi)
└── docs/
    └── WIRING.md               ← Wiring diagram and hardware guide

---

⚡ Quick Start

1. Requirements

Software:

• Arduino IDE 2.x (Windows 8/10/11 & Linux supported)
• ESP32 board package by Espressif (see below)

Libraries (install via Arduino Library Manager):

• ArduinoJson by Benoit Blanchon (version 6.x or 7.x)
• ESP32Time by Felix Biego
• (ESP32-S2/S3 only) USB Host Shield Library 2.0 or use built-in ESP-IDF USB

---

2. Install Arduino IDE

Windows (8, 10, 11):

1. Download from arduino.cc/en/software
2. Run the .exe installer and follow the steps
3. Launch Arduino IDE

Linux (Ubuntu/Debian):

# Option A: Snap (recommended)
sudo snap install arduino

# Option B: AppImage
wget https://downloads.arduino.cc/arduino-ide/arduino-ide_latest_Linux_64bit.AppImage
chmod +x arduino-ide_*.AppImage
./arduino-ide_*.AppImage

---

3. Add ESP32 Board Package

1. Open Arduino IDE → File → Preferences
2. In Additional Boards Manager URLs, add:

   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   

3. Go to Tools → Board → Boards Manager
4. Search for esp32 → Install esp32 by Espressif Systems (version 2.x or 3.x)

---

4. Install Required Libraries

1. Go to Tools → Manage Libraries...
2. Search and install:
   • ArduinoJson (Benoit Blanchon)
   • ESP32Time (Felix Biego)

---

5. Configure Your Settings

⚠️ IMPORTANT: Never skip this step. Do NOT upload the sketch without a proper config.h.

# Navigate to the HID_Detector folder
# Copy the example config:
cp HID_Detector/config.h.example HID_Detector/config.h

Then open config.h in any text editor and fill in:

• Your WiFi SSID and password
• Your web dashboard password
• Your preferred pins (if different from defaults)
• Your timezone offset

The file config.h is listed in .gitignore — it will never be committed to Git.

---

6. Select Your Board

Go to Tools → Board → esp32 and select:

Your hardware	Board to select
ESP32 WROOM-32 / DevKit	ESP32 Dev Module
ESP32-S2	ESP32S2 Dev Module
ESP32-S3	ESP32S3 Dev Module
ESP32-C3	ESP32C3 Dev Module
ESP32-C6	ESP32C6 Dev Module

Then set: Tools → Upload Speed → 115200 and Tools → Port → COMx (Windows) or /dev/ttyUSBx (Linux).

---

7. Upload and Run

1. Open HID_Detector/HID_Detector.ino in Arduino IDE
2. Click Verify (✓) to compile
3. Click Upload (→) to flash your ESP32
4. Open Tools → Serial Monitor at 115200 baud
5. The ESP32 will print its IP address — open that IP in your browser

---

🌐 Web Dashboard

After connecting to WiFi, open http://<ESP32-IP-ADDRESS> in your browser.

Default credentials:

• Username: admin
• Password: (set in your config.h)

The dashboard shows:

• 🟢/🔴 Current threat status
• Keystrokes/second meter
• Event log with timestamps
• Alert history

---

🔌 Wiring

See docs/WIRING.md for full wiring diagrams.

Quick reference (ESP32 WROOM — PS/2 mode):

PS/2 Keyboard Connector   ESP32 WROOM
─────────────────────────────────────────
PIN 1 (DATA)         →   GPIO 5
PIN 3 (GND)          →   GND
PIN 4 (VCC +5V)      →   VIN (5V) or external 5V
PIN 5 (CLK)          →   GPIO 4

---

⚙️ Configuration Reference

All settings are in config.h (copied from config.h.example).

Setting	Description	Default
WIFI_SSID	Your WiFi network name	(required)
WIFI_PASSWORD	Your WiFi password	(required)
WEB_PASSWORD	Dashboard login password	(required)
KEYSTROKE_THRESHOLD_MS	Interval below which keystroke = suspicious	20 ms
BURST_COUNT_THRESHOLD	How many fast keystrokes trigger an alert	8
PS2_CLK_PIN	GPIO pin for PS/2 CLK	4
PS2_DATA_PIN	GPIO pin for PS/2 DATA	5
LED_ALERT_PIN	GPIO pin for alert LED	2
BUZZER_PIN	GPIO for buzzer (-1 to disable)	15
TIMEZONE_OFFSET	Hours offset from UTC	2 (Romania)
DETECTION_MODE	PS2, SERIAL, or USB	PS2

---

🛡️ Security Notes

• config.h is in .gitignore — your WiFi credentials are never published
• Change the default dashboard password in config.h before use
• The web dashboard uses HTTP Basic Auth — use on a trusted local network
• Do not expose the web dashboard port to the public internet

---

📜 License

MIT License — free to use, modify, and distribute with attribution.

---

🤝 Contributing

Pull requests and issues are welcome! For bugs or questions: 📧 contact@morariuandreiraul.com