courses

wificap — a receive-only 802.11 capture appliance

Firmware for the Waveshare ESP32-C5-LCD-1.47. It surveys both bands, parks on one channel, detects WPA2 four-way handshakes live on its own screen, and writes pcap-with-radiotap to a microSD card that Wireshark and aircrack-ng read without conversion.

Built as a lecture demonstration for CS410/510 IoT Security. The page that explains what it is for is wificap.html.

It only ever receives

The radio is brought up in WIFI_MODE_NULL: no station interface, no soft-AP, nothing that can associate, probe, or transmit. There is no deauthentication command and no injection path, deliberately. A classroom demonstration that deauthenticates a network to force a handshake is touching networks belonging to everyone in the building, and the demonstration stops being one you can run in front of people.

The cost is honest: you capture a handshake when a device happens to join the network, not when you want one. See “Showing a handshake on demand” below.

Why not ESP32 Marauder

Marauder is the obvious tool and it does support the ESP32-C5 as a first-class target as of v1.20.0. It cannot run on this board:

If you want Marauder, use a C5-DevKitC-1 or a Seeed XIAO ESP32-C5, both of which are listed targets with 8 MB. This firmware exists because the board with the screen is the one that makes a good demo.

Build and flash

Needs ESP-IDF v5.5 or newer. The ESP32-C5 is a preview target before v5.5 and dual-band promiscuous receive is not something to run on preview support.

. $IDF_PATH/export.sh
idf.py set-target esp32c5
idf.py build
idf.py -p /dev/ttyACM0 flash

The BSP and LVGL are pulled from the ESP Component Registry; nothing is vendored. Insert a FAT32 microSD card before powering up.

Driving it

Commands go over the USB serial/JTAG console at 115200. Every reply is one line beginning with a tag — OK, ERR, STAT, AP, HS, FILE — so the console is equally usable by a person and by a script.

command what it does
survey hop the channel plan, collect BSSIDs. Writes nothing.
aps list access points seen, with channel, RSSI and SSID
park <ch> stop on one channel. This is the capture mode.
target <bssid> filter to one BSSID and park on its channel
notarget clear the filter
rec hs write management + EAPOL frames to the card
rec all write everything the filter passed
rec off stop and close the file
hs handshake progress per station pair
stat one machine-readable status line
ls / get <f> / rm <f> list, download, delete captures
selftest check the EAPOL parser and state machine

Survey first, then park

This is the one thing the firmware is really teaching, so it is worth stating plainly: channel hopping and handshake capture are mutually exclusive. A sweep of 28 channels puts you on any given channel about 3.5% of the time, while a four-way handshake completes in a few milliseconds. Sweeping to find the target and then parking is not a convenience, it is the only way the capture can work.

survey                 # let it run ~20 s
aps                    # pick a target
target aa:bb:cc:dd:ee:ff
rec hs

The host tool

host/wificap.py drives the same console from a laptop and pulls captures over the USB cable, so a demo does not end with ejecting a card and hunting for an adapter.

./wificap.py survey --seconds 20
./wificap.py watch --target aa:bb:cc:dd:ee:ff --record hs
./wificap.py pull -o ./captures

pull verifies a CRC32 computed on the board against one computed on the host. A serial transfer that silently drops a chunk produces a pcap that opens cleanly and is subtly wrong, which is worse than one that fails loudly.

What lands on the card

Classic pcap, link type 127 (IEEE802_11_RADIOTAP). The radiotap header carries channel frequency, RSSI and noise floor, so per-frame signal strength survives into the analysis — without it the capture is bare 802.11 frames and every RSSI is lost.

Beacons are recorded even in rec hs mode, because the SSID is an input to the PMK and a capture holding a handshake but no beacon has no SSID in it.

Two things worth knowing:

Showing a handshake on demand

You cannot schedule someone else’s device to reconnect, and this firmware will not force one. Two honest options:

  1. Bring your own AP and client. Toggle Wi-Fi off and on on a phone associated to a WPA2-PSK network you control. That is a real handshake and the banner lights up.
  2. selftest. Runs synthetic M1–M4 frames through the same classifier and state machine the live path uses, and reports what each was classified as. It touches neither the radio nor the capture file, and removes its synthetic pair afterwards so it cannot be mistaken for evidence.
> selftest
OK selftest M1=1 M2=2 M3=3 M4=4 state=f

Reading the screen

WIFICAP  plan 28/28  sw 10          uptime, free heap
5 GHz                               band
153                                 channel — the big number
                                    ap / eapol / wrote / drop counters, right
112 f/s  ████████░░░░░░░░            how busy this channel is
████████████████░░░░░░░░            dwell progress (amber when parked)
▇▇▁▃▅▇▁▁▃▅▇▇▁▃▅▇▁▁▃▅▇▇▁▃▅▇▁▁        per-channel heat strip
PARK rec:hs a5c340 PSU-IoT          mode, recording, target
HS a5c340>f42912 12-- +PMKID        the handshake line

The heat strip is one cell per planned channel: white is where the radio is now, dark red is a channel the radio refused — which is not the same as a quiet channel, and the two are indistinguishable in a capture.

The handshake line latches. It stays after the event, because the point is that someone can glance over a minute later and still see it caught something.

drop is the counter to watch. It counts frames lost because the SD writer fell behind, and a capture that silently drops frames looks exactly like a quiet channel.

Why M1+M2 is already enough

An offline dictionary attack needs the two nonces and one MIC over a known EAPOL body. M1 carries the ANonce, M2 carries the SNonce and a MIC — so M1+M2 is sufficient, and so is M2+M3. Waiting for all four is a mistake people make because the handshake has four messages; M4 is frequently lost to a retry. The firmware flags a pair as crackable on that basis, not on seeing all four.

Memory

This board has ~148 KiB of usable DRAM and no PSRAM. The LVGL frame buffer, the Wi-Fi driver’s rx pools, the capture ring, FatFS and the console REPL all compete for it. Raising any one of them without lowering another does not produce a warning — it produces ESP_ERR_NO_MEM from esp_wifi_init() at boot, and a reboot loop whose only visible symptom is a flashing screen.

The knobs, in idf.py menuconfig under “wificap”, and in sdkconfig.defaults:

setting default note
WCAP_RING_BYTES 16384 raise if drop moves, memory permitting
WCAP_SNAPLEN 512 full beacon and full EAPOL-Key
BSP_DISPLAY_LVGL_BUF_HEIGHT 40 80 costs 25 KB more and starves the radio
ESP_WIFI_DYNAMIC_RX_BUFFER_NUM 32  

Layout

main/
  main.c       startup, task creation, the receive-only posture
  capture.c    promiscuous callback, EAPOL parsing, handshake state, selftest
  scan.c       radio bring-up, channel-plan probing, survey/park scheduler
  pcap.c       SD mount, radiotap + pcap writer task
  ui.c         the screen
  console.c    the command interface
host/
  wificap.py   host-side driver and capture downloader

Capturing a handshake from a network you do not administer is interception. Use your own access point and your own client. The firmware’s refusal to transmit limits what it can do to you; it does not decide what you point it at.