Wwriteups.

Tutorial

ESP32 HARNESS: Firmware Pentesting on the ESP32

A practical tutorial for building and deploying a custom ESP32 pentesting firmware for 2.4 GHz wireless auditing, RF reconnaissance, and on-device forensics.

  • #esp32
  • #firmware
  • #pentesting
  • #iot
  • #wireless

Why the ESP32

The ESP32 is the most widely deployed microcontroller with built-in Wi-Fi and Bluetooth. Its $3-5 BOM cost means it’s everywhere: smart plugs, sensors, payment terminals, and industrial controllers. Its ubiquity also makes it a prime target for wireless attacks.

The ESP32-HARNESS firmware turns an off-the-shelf ESP32 dev board into a purpose-built wireless auditing tool.

What you need

  • ESP32-WROOM-32 dev board (or any ESP32 variant with at least 4 MB flash)
  • USB-UART bridge (built into most dev boards)
  • esptool and idf.py from Espressif’s ESP-IDF framework

Flashing the firmware

git clone https://github.com/ykrishhh/ESP32-HARNESS
cd ESP32-HARNESS
idf.py set-target esp32
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

The firmware boots into an interactive shell over UART at 115200 baud.

Core capabilities

2.4 GHz spectral scanning

The radio is put into promiscuous mode to capture 802.11 beacons, probe requests, and data frames without associating to a network. The output is a real-time map of nearby APs, clients, and channel utilization.

# Example: scan all channels for 5 seconds per channel
channel_hop(1, 13, dwell=5000)
dump_scan()  # JSON output: SSID, BSSID, RSSI, channel, encryption

RF24 reconnaissance

When fitted with an NRF24L01+ module, the firmware can sniff, replay, and brute-force Nordic Semiconductor RF24 pipes, the protocol used by many wireless mice, keyboards, and consumer IoT bridges.

On-device forensics

The firmware exposes a FAT filesystem over USB mass storage when the board is plugged in. Captured packets, scan results, and logs are written directly to flash and can be pulled off without additional tooling.

Practical use case: rogue AP detection

Deploy ESP32-HARNESS units at building perimeters. Each unit scans 2.4 GHz channels and reports beacon frames to a central collector. The collector cross-references observed SSIDs against an approved list and alerts on lookalike SSIDs (e.g. "Corp-Guest" vs "Corp-Guestt").

Building from source

The firmware is written in C with the ESP-IDF framework. The main loop lives in main/app_main.c and implements a state machine with three states: SCAN, SNIFF, and LOG. Adding a new radio mode means adding a new state.

app_main.c
├── scan_init()       — configure WiFi in promiscuous mode
├── sniffer_task()    — callback on each received frame
├── log_write()       — write to flash-backed ring buffer
└── cmd_handler()     — UART command parser

References