courses

wifi24 — watching 2.4 GHz, and capturing only what you can read

Two tools that answer two different questions about the same band.

  question hardware
wifi24_scan.py where is the energy? HackRF (One or Pro)
wifi24_capture.py what are the frames? USB Wi-Fi card with monitor mode

The split is not arbitrary. A HackRF cannot demodulate 802.11 — an OFDM burst is 20 MHz wide and a sweeping SDR revisits each slice of the band only a few hundred times a second, so nothing coherent survives. What a sweep gives you is the shape of the band: which channels are loaded, which are idle, and where the non-Wi-Fi interference sits. A commodity Wi-Fi card, by contrast, demodulates 802.11 perfectly well and hears nothing else.

Use the HackRF to decide where to point the Wi-Fi card.

wifi24_scan.py — channel activity

$ ./wifi24_scan.py
2.4 GHz channel activity - noise floor  -58.4 dBm - busy = mean 6 dB over floor - sweep 6
 ch   MHz  occupancy                             mean    peak  recent
  1* 2412  ###########                          -47.6   -42.0                          :+::-: <
  2  2417  ###########                          -47.6   -42.0                          ::::=: <
  3  2422  #########                            -49.4   -43.9                          ::::+: <
  4  2427  #######                              -50.8   -45.5                          .:::%. <
  5  2432  ######                               -51.9   -47.4                          .:::%. <
  6* 2437  ########                             -50.1   -43.5                          #:::%: <
  7  2442  ###########                          -47.3   -40.1                          #:::%: <
  8  2447  #########################            -32.8   -23.5                          #:::%* <
  9  2452  ###########################          -30.9   -22.8                          #:::%# <
 10  2457  ###########################          -30.9   -22.8                          *::.%# <
 11* 2462  ###########################          -31.0   -22.8                          =::.*# <
 12  2467  ##########################           -31.4   -22.8                          =::.+* <
 13  2472  ######################               -35.5   -26.0                          ::-:++ <
 14  2484  ######################               -35.4   -26.0                          ::-:++ <
* = non-overlapping channel. Energy only; no frames are decoded.

Reading it:

Neighbouring channels rise and fall together, and that is physics rather than a bug: a 20 MHz channel plus guard bands is about 22 MHz wide, so channels 5 MHz apart share most of their spectrum. Channel 9 being loud necessarily lights up 8, 10, 11, and 12. This is the entire reason 1/6/11 is the standard plan, and it means you should read the display as a hump with a centre rather than as fourteen independent numbers.

What this measures is energy, not access points. The two come apart badly, and a student who compares this display against an AP census will think the tool is broken. On the band above there were 58 BSSes, every one of them on channel 1, 6, or 11 — 15, 12, and 31 respectively — and the energy peak was nowhere near the most populated channel. One laptop associated a few centimetres from the antenna outweighs thirty-one access points across a building, because received power falls off with the square of distance while an AP count does not fall off at all. Use the sweep to find where the energy is, which is what tells you about interference and where a capture will be productive. Use iw dev <iface> scan or nmcli device wifi list if the question is how many networks are on a channel.

A few things that are not Wi-Fi also show up here, which is half the point:

Useful flags:

$ ./wifi24_scan.py --once                  # one reading, no screen clearing
$ ./wifi24_scan.py --sweeps 20             # stop after 20 sweeps
$ ./wifi24_scan.py --lna 32 --vga 30 --amp # more gain for weak/distant signals
$ ./wifi24_scan.py --bin-hz 250000         # finer bins, slower sweep
$ ./wifi24_scan.py --min-mhz 2400 --max-mhz 2500 --threshold 10

Turning gain up raises the noise floor too; the scanner measures the floor each sweep, so the bars stay meaningful, but a signal already well above the floor will not look stronger.

If everything reads as busy, decide which of two things you are looking at. Usually the band is genuinely crowded and the fix is --threshold 10 or more. But if the peak column is up around −10 to −20 dBm, something is transmitting very close to the antenna and the front end is compressing, which smears energy across the whole sweep and makes every channel look loud. Then the fix is less gain, not a higher threshold — --lna 0 --vga 0 is a useful sanity check, and if the broad hump collapses, that is what you were seeing. Move the antenna away from your own adapters before trusting any reading.

--min-mhz/--max-mhz do not land where you ask. hackrf_sweep rounds the range up to a multiple of its 20 MHz tile width, so -f 2400:2450 really sweeps to 2460. Channels the sweep only clipped the edge of are marked rather than given a number, because a mean over a sliver of a channel means nothing:

$ ./wifi24_scan.py --once --min-mhz 2400 --max-mhz 2450
...
  9  2452  (only 86% of this channel was swept)   -62.2   -54.4
 10  2457  (only 64% of this channel was swept)   -61.7   -54.4
 11* 2462  (only 41% of this channel was swept)   -63.3   -59.0
 12  2467  (only 18% of this channel was swept)   -65.5   -61.7
Channels marked as partly swept fall outside --min-mhz/--max-mhz; widen the range to read them.

A narrower range does buy you better time resolution, though: the sweep revisits each channel more often, so short bursts are likelier to be caught. A full-band sweep and a 2400–2450 sweep taken minutes apart read the same channel 18 dB apart for this reason.

wifi24_capture.py — capture only what you can read

One rule: a frame is written to the output only if it is unencrypted, or if it is encrypted and your keys decrypted it. Everything else is discarded.

A monitor-mode card hears every frame in the air, and the standard tools write all of it to disk. Keeping ciphertext you cannot read gains you nothing analytically and leaves you holding other people’s traffic. So this tool throws it away, and proves it did.

The gate

Two complementary display filters, both evaluated with your keys loaded:

permit  wlan.fc.protected == 0 || (wlan.fc.protected == 1 && llc)
forbid  wlan.fc.protected == 1 && !llc

The Protected Frame bit in the frame control field says whether the payload is encrypted. An LLC header only becomes visible above an encrypted frame when decryption succeeded — so protected && llc means “encrypted, and we read it”. tshark -Y filters what -w writes, not merely what is displayed, so the rejected frames are never copied into the output file at all.

Then the tool re-runs the forbid filter against the finished file as a post-condition. If it matches even one frame, the output is shredded instead of handed back. The intermediate raw capture — which does contain everything the card heard — lives in a 0700 directory and is shredded before exit.

Worked example: no keys at all

With no keys, only management, control, and genuinely open traffic survive.

$ ./wifi24_capture.py -i wlan1 -d 30 -w gated.pcapng
wifi24_capture: no keys given - only unencrypted frames (management, control, open networks) will be kept.
capturing 30s on wlan1...
heard    11058 frames
kept      9769 unencrypted or successfully decrypted -> gated.pcapng
dropped   1289 encrypted and unreadable, discarded

Check the claim yourself rather than trusting the summary:

$ tshark -r gated.pcapng -Y 'wlan.fc.protected == 1 && !llc' -T fields -e frame.number | wc -l
0

That is the whole contract, verifiable in one line.

Worked example: a network whose passphrase you know

$ ./wifi24_capture.py -i mon0 -c 1 -d 60 -w lab.pcapng \
      --key wpa-pwd:'correct horse battery staple:PSU-IoT'

Key formats, repeatable with multiple --key:

format meaning
wpa-pwd:<passphrase>[:<ssid>] passphrase, optionally bound to one SSID
wpa-psk:<64 hex digits> precomputed pairwise master key
wep:<hex digits> WEP key

--key puts your passphrase on a command line, where other users can read it. This is a real exposure on a shared machine, not a theoretical one. While the tool runs, the key is in its own argv and then in tshark’s:

$ tr '\0' '\n' < /proc/$(pgrep -f wifi24_capture.py)/cmdline | grep wpa-pwd
wpa-pwd:correct horse battery staple:PSU-IoT
$ stat -c '%a' /proc/$(pgrep -f wifi24_capture.py)/cmdline
444

/proc/<pid> is world-readable unless /proc is mounted with hidepid=2, and yama.ptrace_scope does not cover this — it restricts debugger attachment, not reading cmdline. Your shell history is a second copy. On the lab machines, assume any passphrase you pass this way is readable by everyone logged in, and use a throwaway network key for coursework.

Binding the passphrase to an SSID is worth doing: without it, Wireshark tries the passphrase against every network it sees.

Decrypting WPA/WPA2 unicast traffic also needs the four-way handshake for each station, because the per-session keys are derived from it. Start the capture before the client associates, or wait out a rekey. Without the handshake the frames stay encrypted and this tool will correctly refuse to keep them — which looks like a failure but is the tool working.

Verified against a WPA2-PSK network on 2026-11-02, capturing the client’s reassociation so the handshake landed inside the window. All four EAPOL frames were captured, and with the passphrase bound to the SSID:

raw           total= 7258  protected=  88  decrypted=  81  forbidden=7
gated output  total= 7251  protected=  81  decrypted=  81  forbidden=0

The 81 decrypted frames dissect as mDNS, ARP, DHCP, LLMNR, IGMPv3, and ICMPv6 — upper-layer protocols you cannot get out of CCMP ciphertext without correct keys. 75 were group-addressed (decrypted with the GTK) and 6 unicast (the PTK), so both key types work. The gate kept exactly the frames it could read and dropped the 7 it could not, which were other stations whose handshakes were not in the capture.

That run recovered almost no unicast payload, because the client was on a Wi-Fi 7 link the capture card could not demodulate — see the PHY-generation trap below. Repeating it with the client on an HT (802.11n) link, so that capture card and client were the same PHY generation, recovered the payload in full:

decrypted frame protocols:  193 TCP, 177 ICMP, 96 MDNS, 95 DNS, 27 ARP,
                             22 ICMPv6, 14 HTTP, 12 LLMNR, 4 IGMPv3, 3 DHCP

Including complete HTTP request/response pairs lifted out of CCMP:

$ tshark -r gated.pcapng $KEYOPTS -Y http \
      -T fields -e ip.src -e ip.dst -e http.request.method -e http.host \
      -e http.request.uri -e http.response.code -e http.server
172.19.100.176  104.21.4.210    GET  httpforever.com  /
104.21.4.210    172.19.100.176                        /   200  cloudflare

Two things must both be true, and they fail independently. The handshake gets you the keys; the adapter still has to demodulate the frames. A capture can have a perfect four-way handshake, correct keys, and still yield no payload at all.

Getting an interface

The kernel will not change an interface’s type while it is up, so bring it down first:

$ iw dev                          # what exists, and what mode it is in
$ sudo ip link set wlan1 down
$ sudo iw dev wlan1 set type monitor
$ sudo ip link set wlan1 up
$ sudo iw dev wlan1 set monitor otherbss control
$ sudo iw dev wlan1 set channel 6

Those last two lines are different commands and both matter. set type changes the mode; set monitor <flag> sets the RX filter flags — otherbss for frames belonging to BSSes you are not associated with, control for control frames. Without otherbss some drivers hand up only management and broadcast traffic. Note that set monitor works only on an interface that is already of type monitor; run against a managed interface it fails with Invalid argument.

Alternatively, leave wlan1 alone and add a second, monitor-mode interface on the same phy — monitor is a software interface mode, so it can always be added:

$ sudo iw phy phy11 interface add mon0 type monitor
$ sudo ip link set mon0 up
$ sudo iw dev mon0 set channel 6

Take the interface away from NetworkManager first. Otherwise NM and wpa_supplicant keep scanning on it and retune the card out from under you — a capture that should sit on channel 6 comes back with frames from all over 2.4 and 5 GHz, and a frame count a couple of orders of magnitude too low:

$ nmcli device set wlan1 managed no        # polkit; no sudo needed
$ nmcli device set wlan1 managed yes       # put it back when you are done

dumpcap -I will also put a managed interface into monitor mode for you. The tool detects an interface that is already in monitor mode and omits -I, because asking for it again can fail. -I does not set a channel, though, so on its own it gives you whatever channel the card was last on.

Capturing without root needs the capabilities Wireshark’s own installer sets:

$ sudo setcap cap_net_raw,cap_net_admin+eip "$(command -v dumpcap)"
$ sudo usermod -aG wireshark "$USER"        # log out and back in

Setting a channel still needs root. If -c fails, the tool prints the exact sudo iw command and carries on using whatever channel the card is on.

Other flags

$ ./wifi24_capture.py -i mon0 -c 6 -d 30 -w out.pcapng --dry-run   # show the commands
$ ./wifi24_capture.py -i mon0 -d 30 -w out.pcapng --keep-raw all.pcapng

--keep-raw saves the unfiltered capture and therefore defeats the entire point of the tool. It exists for debugging the tool itself.

Scope

Capturing traffic on networks you do not operate, or have not been authorised to test, is unlawful in most jurisdictions regardless of what you can decrypt. These tools reduce what you collect; they do not grant you authority to collect it. Use them on your own networks, on the course lab network, or with written permission.

Receiving is passive and legal in the sense that matters for spectrum rules — neither tool transmits. The HackRF is capable of transmitting, and in this band you would be sharing an ISM allocation with everything above; don’t.

Requirements

Both tools were developed and tested against a HackRF Pro (board ID 5, firmware n_260404, API 1.11) and an RTL8814AU card, on libhackrf 2026.01.3.

Verified hardware

wifi24_scan.py was verified on 2026-11-02 against a HackRF Pro (board ID 5, firmware n_260404, API 1.11, hardware r1.2, libhackrf 2026.01.3), with hackrf_sweep’s flags and CSV field order checked against its own -h output. Exercised: --once, --sweeps, --bin-hz 500000, --min-mhz/--max-mhz, --threshold, and the gain range from --lna 0 --vga 0 to --lna 40 --vga 62 --amp. A bad --device and an out-of-range --bin-hz both now exit 1 with hackrf_sweep’s own message.

Note that hackrf_info warns There are 19 other devices on the same USB bus. You may have problems at high sample rates. The sweep is undemanding enough that this did not bite, but a loaded bus is worth ruling out before blaming the radio.

wifi24_capture.py was re-verified end to end on 2026-11-02 against an external RTL8814AU (USB 0bda:8813, in-kernel driver rtw88_8814au, firmware 33.6.0, kernel 7.3.1-cachyos). Thirty seconds on channel 11:

heard    11058 frames
kept      9769 unencrypted or successfully decrypted -> gated.pcapng
dropped   1289 encrypted and unreadable, discarded

All three frame types arrive. Of the 9769 frames kept, 4731 were management, 4928 control, and 110 data; the other 1289 data frames were encrypted and went out with the gate. So both otherbss and control are taking effect. The gate was checked against the raw capture rather than taken on trust: the raw held 1289 frames matching the forbidden filter, the gated output held 0, and exactly 1289 frames were removed. Every dropped frame was type 2 (data), which is what encrypted unicast looks like. This is the adapter to use for the capture exercise.

The PHY-generation trap: an 802.11ac card cannot see Wi-Fi 7

This is the one that will cost you an afternoon, and it is not a bug in anything. A capture card can only demodulate the PHY generations it implements. The RTL8814AU is 802.11ac: it does HT (Wi-Fi 4) and VHT (Wi-Fi 5), and it is deaf to HE (Wi-Fi 6) and EHT (Wi-Fi 7).

Management and broadcast traffic is transmitted at low legacy rates for backward compatibility, so it arrives regardless and everything looks fine. Unicast data goes out at the fastest rate the link negotiated. On a Wi-Fi 7 link, that means your payload is invisible:

$ iw dev wlan0 link | grep bitrate
tx bitrate: 286.7 MBit/s EHT-MCS 11 EHT-NSS 2      # 802.11be

A 45-second capture on that network, while the client was repeatedly loading a plain-HTTP page over it, returned 5583 frames of which 0 were HTTP, 0 were TCP, and 0 involved the client’s own IP address. The rate breakdown says why:

$ tshark -r raw.pcapng -T fields -e radiotap.mcs.index \
    | awk '{if($1=="")l++;else m++} END{print "legacy:",l+0," HT-MCS:",m+0}'
legacy: 5583  HT-MCS: 0

Not one high-rate frame. The decryption path was fine — verified separately above on the same network — and the capture was still useless for payload.

So check the link’s PHY before you trust a capture to contain data:

$ iw dev <client-iface> link | grep bitrate

EHT-MCS means Wi-Fi 7, HE-MCS Wi-Fi 6, VHT-MCS Wi-Fi 5, plain MCS Wi-Fi 4. If that outruns your capture card’s generation, you will get beacons and nothing else that matters.

The fix is to make the client’s PHY one your capture card can hear. Either force the network down (an 802.11n-only AP setting is the usual lab answer), or put the client on an older adapter. Demonstrated by doing exactly that: an RTL8814AU used as the client negotiates MCS 15 on 2.4 GHz, because 802.11ac has no 2.4 GHz VHT, and an RTL8812AU monitoring that link captured 563 HT frames and recovered the full HTTP exchange. The same monitor against a Wi-Fi 7 client saw 0 HT frames.

Practical lab recipe: one adapter as the client, one as the monitor, both the same generation, and keep the course network off Wi-Fi 7 defaults.

Two interfaces on one Realtek phy

On rtw88_8812au and rtw88_8814au, iw phy phyN info reports interface combinations are not supported. The monitor interface is created happily and then cannot be brought up while the managed one exists:

$ sudo iw phy phy18 interface add mon0 type monitor     # succeeds
$ sudo ip link set mon0 up
command failed: Too many open files in system (-23)

-ENFILE here has nothing to do with file descriptors — /proc/sys/fs/file-nr showed 18 155 of 2 097 152 in use. It is the driver refusing a second interface. Delete the managed one first:

$ sudo ip link set wlan1 down && sudo iw dev wlan1 del
$ sudo ip link set mon0 up && sudo iw dev mon0 set channel 6 HT20

Prefer this over converting the managed interface in place. On the RTL8814AU, a wlan1 that NetworkManager had already associated, then converted with set type monitor, reported type monitor, the right channel, UP, LOWER_UP, carrier 1, and rx_errors 0, and delivered zero frames on every channel and width tried — surviving both a link bounce and a full USB re-enumeration. A freshly created monitor vif on the same phy captured immediately. Watch /sys/class/net/<iface>/statistics/rx_packets to tell the two apart without root:

$ cat /sys/class/net/mon0/statistics/rx_packets   # must climb; frozen means dead

Known-bad: MT7921AU, and “dropped 0” generally

wifi24_capture.py was re-verified on 2026-11-02 against an external MT7921AU adapter (USB 0e8d:7961, driver mt7921u, firmware ____010000-20260224110949, kernel 7.3.1-cachyos). Monitor mode, radiotap headers, the gate, and the fail-closed post-condition all work. Data frames do not.

Parked on channel 11 — the channel an associated interface on the same machine was actively passing traffic on, through an AP whose beacons this adapter logged 289 times in 30 seconds — the capture came back:

heard     2883 frames        2882 management, 1 data, 0 protected
dropped      0 encrypted and unreadable, discarded

Setting otherbss control changed nothing. The card hears the right AP on the right channel at good signal and still hands up essentially no unicast data, which is the “supports monitor mode but not promiscuous mode” failure: you get beacons, probe requests, and other broadcast/multicast traffic, and nothing else.

Power management is not the cause, which is worth saying because it is the usual suspect for mt7921 and the first thing the mailing-list threads suggest. Both knobs were already off and the radio never dozed:

$ sudo grep . /sys/kernel/debug/ieee80211/phy11/mt76/{deep-sleep,runtime-pm}
.../deep-sleep:0
.../runtime-pm:0
$ sudo cat /sys/kernel/debug/ieee80211/phy11/mt76/runtime_pm_stats
awake time:        1332018
doze time:               0
low power wakes:         0

That leaves the driver’s RX filtering. The RTL8814AU, on the same machine and the same channel the same afternoon, makes the comparison unambiguous:

One 30-second run on channel 11 from each, counting every frame the card handed up, gate included:

frames heard in 30 s MT7921AU RTL8814AU
management (type 0) 2 882 4 731
control (type 1) 0 4 928
data (type 2) 1 1 399
total 2 883 11 058
of which encrypted, dropped by the gate 0 1 289

The control-frame row alone is diagnostic: a channel busy enough to carry 4928 ACKs and RTS/CTS exchanges cannot plausibly have produced zero.

Do not use an MT7921 for the capture exercise. Use the RTL8814AU.

This matters because of how the failure looks. A dropped 0 line does not mean the gate is broken, and it does not mean the air was clean — on a busy channel it almost always means the adapter never handed you the encrypted frames in the first place. Sanity-check any capture before drawing conclusions from it:

$ tshark -r out.pcapng -T fields -e wlan.fc.type | sort | uniq -c

0 is management, 1 control, 2 data. A busy channel that yields only type-0 frames is an adapter problem, not a quiet network.