esp32-sniffer is ESP32 firmware that passively captures 802.11 PROBE REQUEST frames from smartphones and ships parsed metadata over MQTT, built for authorized monitoring research.
| Tool | ETS-PoliTO/esp32-sniffer — ESP32 firmware that captures and parses PROBE REQUEST frames from nearby smartphones and publishes results to a server via MQTT |
| Category | Wi-Fi monitoring firmware for embedded hardware (ESP32, ESP-IDF, C) |
| Primary Use | Building an authorized 802.11 monitoring node to study how client devices broadcast PROBE REQUEST metadata such as MAC addresses, probed SSIDs and RSSI in your own lab or assessed environment |
| Safe Use | Intended for authorized security assessments, academic research and controlled lab deployments on networks and devices you own or have written permission to monitor; in most jurisdictions passive Wi-Fi sniffing of third parties is legally restricted |
| Telemetry Note | The firmware itself only listens and never transmits spoofed frames, but it associates to a configured WIFI_SSID and connects out to an MQTT broker on BROKER_ADDR:BROKER_PORT, both observable on the monitored network; defenders can detect probe-request harvesting via WIDS analytics on unusual client behavior |
esp32-sniffer is an academic firmware project from the ETS-PoliTO organization at Politecnico di Torino, written in C on top of Espressif's ESP-IDF framework and tested against the ESP-WROOM-32 module with esp-idf v3.2. The repository currently sits at 329 stars and is released under GPL-3.0, which makes it freely auditable end to end — an important property when you are deploying a radio-capture device, because you want to know exactly what leaves the sensor. The README is unusually thorough for a student project: it documents the two-task architecture, the full build pipeline, the Kconfig configuration surface and the companion server and GUI that complete the tracking pipeline.
The firmware targets one specific and well-documented behavior of the 802.11 protocol: when a smartphone has Wi-Fi enabled but is not associated, it broadcasts PROBE REQUEST frames across channel frequencies asking whether known networks are nearby. The ESP32 device listens for these frames and extracts structured metadata from each one. Per the README, the fields harvested from every sniffed packet are the transmitting device's MAC address, the probed SSID, a Timestamp, the Received Signal Strength Indicator (RSSI), the Sequence Number (SN) and the HT Capabilities information element. That is a compact but potent telemetry set — MAC plus RSSI across several sensors is the classic input for device presence and rough positioning.
Internally the firmware is organized around two FreeRTOS tasks that the README calls the Sniffer Task and the Wi-Fi Task. The Sniffer Task lives in monitor mode, captures PROBE REQUEST frames and persists the parsed records to a file on flash. Once per minute the Wi-Fi Task drains that store and forwards the batch to the upstream ETS-Server, with a lock guarding the critical section around file I/O so the two threads do not corrupt shared state. This producer-consumer split is the standard pattern when your radio can only do one thing at a time and you cannot afford to drop frames while the uplink is busy.
The clever bit is the radio configuration. The ESP32 runs in WIFI_MODE_APSTA mode, creating both a soft access point and a station control block simultaneously. Because the station side can associate to an infrastructure network while the promiscuous interface keeps listening, the device can sniff and upload at the same time without losing packet information during transmission windows. For anyone building distributed sensor meshes on cheap hardware, this dual-role trick is the most reusable idea in the codebase.
Storage is handled by SPIFFS, the SPI Flash File System, whose partition geometry — base address, size, logical block and page sizes — is exposed through make menuconfig under the /main/Kconfig.projbuild file. SPIFFS brings wear leveling and consistency checks, which matters on flash media that is written once a minute indefinitely. The configuration menu also carries the operational variables: ESP32_ID for sensor identification, WIFI_SSID and WIFI_PASS for the uplink network, BROKER_ADDR, BROKER_PSW and BROKER_PORT for the MQTT broker, plus CHANNEL and SNIFFING_TIME to control where and how long the radio listens. The Kconfig structure is extensible, and the README shows how to add custom menu/endmenu blocks with your own variables.
Transport uses the esp-mqtt library, so the sensor speaks standard MQTT to the broker rather than some bespoke protocol — a sensible choice that lets you point the firmware at your own broker infrastructure during an authorized deployment. An MD5 hash function is applied to sniffed packets to derive a unique identifier per record, which avoids pushing raw frames upstream and gives the server a deduplication key. The complete system is deliberately modular: the firmware is this repo, the processing backend lives in ETS-PoliTO/ETS-Server, and visualization — real-time device location and appearance frequency — lives in ETS-PoliTO/GUI-Application. A public presentation PDF and a YouTube demo linked from the README walk through the full chain.
Getting the firmware onto a device is the standard legacy ESP-IDF v3.x workflow. You clone esp-idf recursively, check out release/v3.2, export IDF_PATH and the toolchain bin directory, then build the project with make menuconfig to set the serial port and make all && make flash to compile and flash. Logs are available via make monitor. The README notes the environment section may be outdated and points to Espressif's current documentation for the modern idf.py workflow, which is honest and worth heeding if you are on a recent toolchain — expect some friction porting a v3.2-era project forward.
From a documentation-quality standpoint, the README does something few hobby projects bother with: it grounds the parser in the standard. It includes the field layout of a PROBE REQUEST as defined by IEEE 802.11-2012, alongside a Wireshark capture annotated with bit offsets for each information element. That makes the project genuinely useful as a teaching artifact for understanding management frames, not just as a deployable sensor. Anyone learning 802.11 frame anatomy can read the firmware against the annotated diagram and see exactly which bit ranges feed which extracted fields.
Where this fits in an authorized workflow is straightforward: it is a low-cost, low-footprint presence-detection node for physical security assessments, Wi-Fi device-inventory exercises in your own facilities, or academic research into probe-request privacy leakage — a topic that led mobile OS vendors to randomized MAC addresses precisely because of tools like this. What it is not is an attack tool: the firmware never transmits spoofed frames, never responds to probes, and never attempts to associate with the devices it observes. The privacy sensitivity is real, though — probed SSID strings historically leaked a device's location history — so legal review before deployment outside a lab is not optional in most jurisdictions.
For defenders, the existence and popularity of this firmware is itself a signal. Probe-request harvesting is passive and therefore largely invisible to the devices being observed, but the sensor's backhaul is detectable: it joins your network with credentials in WIFI_PASS and opens persistent MQTT sessions to an external BROKER_ADDR. Rogue-device hunting on corporate Wi-Fi should include cheap embedded clients exhibiting that pattern. More constructively, studying this repo teaches blue teams what metadata their fleet broadcasts and strengthens the case for enforcing MAC randomization and suppressing directed probes via MDM policy.
The project's age shows — the esp-idf v3.2 pin is several major versions behind — and the commit cadence suggests a completed course project rather than an actively maintained tool. That said, the architecture is small, readable and permissively licensed, which makes it an excellent skeleton to fork: swap MQTT for TLS-secured transport, modernize to idf.py and v5.x, or extend the parser to additional information elements. As a compact, honest, well-documented example of embedded Wi-Fi monitoring, esp32-sniffer earns its place on the shortlist for anyone experimenting with authorized wireless telemetry on a budget.
ETS-PoliTO/esp32-sniffer.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.