HCXDUMPTOOL(1)

📦 version 7.1.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 HCXDUMPTOOL(1) 💖

okay bestie, buckle up, because this is hcxdumptool — the manual name is hcxdumptool — and it's a tool to capture packets from wlan devices. she's iconic, she's powerful, and she has OPINIONS. let's get into it 💅

✨ NAME ✨

hcxdumptool — tool to capture packets from wlan devices.

🌸 SYNOPSIS 🌸

hcxdumptool [OPTIONS]

🦋 DESCRIPTION 🦋

Tool to capture wpa handshake from Wi-Fi networks and run several tests to determine if Wi-Fi access points or clients are vulnerable to brute-force atacks.

like. she grabs handshakes and then runs a whole lil vibe check on the APs and clients to see if they're out here being weak to brute-force attacks. no cap. 😌

👑 OPTIONS 👑

okay so before we even get to the flags, there's a whole stack of house rules and I need you to read them, bestie, because breaking them is giving chaos:

  • press ctrl+c to terminate hcxdumptool
  • press GPIO button to terminate hcxdumptool — hardware modification is necessary, read more: https://github.com/ZerBea/hcxdumptool/tree/master/docs
  • do not set monitor mode by third party tools (iwconfig, iw, airmon-ng)
  • do not run hcxdumptool on logical (NETLINK) interfaces (monx, wlanxmon, prismx, ...) created by airmon-ng and iw
  • do not run hcxdumtool on virtual machines or emulators
  • do not run hcxdumptool in combination with tools (channel hopper), that take access to the interface (except: tshark, wireshark, tcpdump)
  • do not use tools like machcanger, because hcxdumptool run its own MAC space and will ignore this changes
  • stop all this services (e.g.: wpa_supplicant.service, NetworkManager.service) that take access to the interface

🎀 short options 🎀

  • -i <interface> — interface (monitor mode will be enabled by hcxdumptool). it is mandatory that the driver support ioctl() system calls, monitor mode and full packet injection!
  • -o <dump file> — output file in pcapng format. filename '-' outputs to stdout, '+' outputs to client including radiotap header (LINKTYPE_IEEE802_11_RADIOTAP)
  • -f <frames> — frames to save. it's a bitmask, bestie:
    • 0: clear default values
    • 1: MANAGEMENT frames (default)
    • 2: EAP and EAPOL frames (default)
    • 4: IPV4 frames
    • 8: IPV6 frames
    • 16: WEP encrypted frames
    • 32: WPA encrypted frames
    • 64: vendor defined frames (AWDL)

to clear default values use -f 0 first, followed by desired frame type (e.g. -f 0 -f 4)

  • -c <digit> — set frequency (2437,2462,5600,...) or channel (1,2,3, ...). default: auto frequency/auto band. maximum entries: 255. 0 - 1000 treated as channel; > 1000 treated as frequency in MHz. on 5GHz and 6Ghz it is recommended to use frequency instead of channel number because channel numbers are not longer unique. standard 802.11 channels (depend on device, driver and world regulatory domain): https://en.wikipedia.org/wiki/List_of_WLAN_channels
  • -s <digit> — set predefined scanlist. 0 = auto frequency/auto band (default):
    • 1 = 1,6,11,3,5,1,6,11,2,4,1,6,11,7,9,1,6,11,8,10,1,6,11,12,13 (optimized 2.4GHz)
    • 2 = 1,2,3,4,5,6,7,8,9,10,11,12,13 (standard 2.4 GHz)
    • 3 = 36,40,44,48,52,56,60,64,100,104,108,112,116,120,124,128,132,136,140,144,149,153,157,161,165 (standard 5GHz)
    • 4 = 1,2,3,4,5,6,7,8,9,10,11,12,13,36,40,44,48,52,56,60,64,100,104,108,112,116,120,124,128,132,136,140,144,149,153,157,161,165 (standard 2.4GHz/5GHz)
  • -t <seconds> — stay time on frequency before hopping to the next channel. default 4 seconds
  • -m <interface> — set monitor mode by ioctl() system call and quit
  • -I — show WLAN interfaces and quit
  • -C — show available device channels and quit. if no frequencies are available, interface is probably in use or doesn't support monitor mode. if additional frequencies are available, firmware, driver and regulatory domain is probably patched
  • -h — show this help
  • -v — show version

🌈 long options 🌈

  • --do_rcascan — show radio channel assignment (scan for target access points). this can be used to test that ioctl() calls and packet injection is working. if you got no HIT, packet injection is possible not working. also it can be used to get information about the target and to determine that the target is in range. use this mode to collect data for the filter list. run this mode at least for 2 minutes to save all received raw packets. use option -o. default scanlist: channel 1 ...13
  • --rcascan_max=digit> — show only n highest ranking lines. default: 256 lines
  • --rcascan_order=digit> — rcascan sorting order: 0 = sort by PROBERESPONSE count (default), 1 = sort by BEACON count, 2 = sort by CHANNEL
  • --do_targetscan=<MAC_AP> — same as do_rcascan - hide all networks, except target. format: 112233445566, 11:22:33:44:55:66, 11-22-33-44-55-66
  • --reason_code=<digit> — deauthentication reason code. recommended codes:
    • 1 WLAN_REASON_UNSPECIFIED
    • 2 WLAN_REASON_PREV_AUTH_NOT_VALID
    • 4 WLAN_REASON_DISASSOC_DUE_TO_INACTIVITY
    • 5 WLAN_REASON_DISASSOC_AP_BUSY
    • 6 WLAN_REASON_CLASS2_FRAME_FROM_NONAUTH_STA
    • 7 WLAN_REASON_CLASS3_FRAME_FROM_NONASSOC_STA (default)
    • 9 WLAN_REASON_STA_REQ_ASSOC_WITHOUT_AUTH
  • --disable_client_attacks — do not attack clients. affected: ap-less (EAPOL 2/4 - M2) attack
  • --stop_client_m2_attacks=<digit> — stop attacks against CLIENTS after 10 M2 frames received. affected: ap-less (EAPOL 2/4 - M2) attack. require hcxpcangtool --all option
  • --disable_ap_attacks — do not attack access points. affected: connected clients and client-less (PMKID) attack
  • --stop_ap_attacks=<digit> — stop attacks against ACCESS POINTs if <n> BEACONs received. default: stop after 600 BEACONs
  • --resume_ap_attacks=<digit> — resume attacks against ACCESS POINTs after <n> BEACONs received. default: 864000 BEACONs
  • --disable_deauthentication — do not send deauthentication or disassociation frames. affected: conntected clients
  • --silent — do not transmit! hcxdumptool is acting like a passive dumper. expect possible packet loss
  • --eapoltimeout=<digit> — set EAPOL TIMEOUT (microseconds). default: 20000 usec
  • --eapoleaptimeout=<digit> — set EAPOL EAP TIMEOUT (microseconds) over entire request sequence. default: 2500000 usec
  • --bpfc=<file> — input kernel space Berkeley Packet Filter (BPF) code. affected: incoming and outgoing traffic - that include rca scan. steps to create a BPF (it only has to be done once): set hcxdumptool monitormode
$ hcxdumptool -m <interface>

create BPF to protect a MAC

$ tcpdump -i <interface> not wlan addr1 11:22:33:44:55:66 and not wlan addr2 11:22:33:44:55:66 -ddd > protect.bpf

recommended to protect own devices or create BPF to attack a MAC

$ tcpdump -i <interface> wlan addr1 11:22:33:44:55:66 or wlan addr2 11:22:33:44:55:66 -ddd > attack.bpf

it is strongly recommended to allow all PROBEREQUEST frames (wlan_type mgt && wlan_subtype probe-req). see man pcap-filter for a list of all filter options. to use the BPF code

$ hcxdumptool -i <interface> --bpfc=attack.bpf ...
notice: this is a protect/attack, a capture and a display filter
  • --filtermode=<digit> — user space filter mode for filter list. mandatory in combination with --filterlist_ap and/or --filterlist_client. affected: only outgoing traffic. notice: hcxdumptool act as passive dumper and it will capture the whole traffic on the channel.
    • 0: ignore filter list (default)
    • 1: use filter list as protection list - do not interact with ACCESS POINTs and CLIENTs from this list
    • 2: use filter list as target list - only interact with ACCESS POINTs and CLIENTs from this list

not recommended, because some useful frames could be filtered out. using a filter list doesn't have an affect on rca scan. only for testing useful - devices to be protected should be added to BPF.

notice: this filter option will let hcxdumptool protect or attack a target - it is neither a capture nor a display filter
  • --filterlist_ap=<file or MAC> — ACCESS POINT MAC or MAC filter list. format: 112233445566, 11:22:33:44:55:66, 11-22-33-44-55-66 # comment. maximum entries 256. run first --do_rcascan to retrieve information about the target
  • --filterlist_ap_vendor=<file> — ACCESS POINT VENDOR filter list by VENDOR. format: 112233, 11:22:33, 11-22-33 # comment. maximum entries 256. run first --do_rcascan to retrieve information about the target
  • --filterlist_client=<file or MAC> — CLIENT MAC or MAC filter list. format: 112233445566, 11:22:33:44:55:66, 11-22-33-44-55-66 # comment. maximum entries 256. due to MAC randomization of the CLIENT, it does not always work!
  • --filterlist_client_VENDOR=<file> — CLIENT VENDOR filter list. format: 112233, 11:22:33, 11-22-33 # comment. maximum entries 256. due to MAC randomization of the CLIENT, it does not always work!
  • --weakcandidate=<password> — use this pre shared key (8...63 characters) for weak candidate alert. will be saved to pcapng to inform hcxpcaptool. default: 12345678
  • --essidlist=<file> — transmit beacons from this ESSID list. maximum total entries: 256 ESSIDs
  • --essidlist_wpaent=<file> — transmit WPA-Enterprise-only beacons from this ESSID list. maximum total entries: 256 ESSIDs

and bestie, that's just part one — there's more coming, don't go anywhere 💜

  • --active_beacon — blast out a beacon built from the ESSIDs we collected plus whatever's in essidlist, once every 10000000 nsec. affects: ap-less ✨
  • --flood_beacon — send a beacon back for every beacon you receive. affects: ap-less 🦋
  • --all_m2 — accept literally every connection attempt that comes from a CLIENT. affects: CLIENTs. ⚠️ warning: this can stop a CLIENT from being able to establish a connection to an assigned ACCESS POINT. so like, careful bestie.
  • --infinity — stop a CLIENT from ever establishing a connection to an assigned ACCESS POINT. affects: ACCESS POINTs and CLIENTs 💀
  • --beaconparams=<TLVs> — update or add Information Elements in all reactive and essidlist beacons. max 50 IEs as TLV hex string. tag id 0 (ESSID) gets ignored 🙈, tag id 3 (channel) gets overwritten, multiple IEs with the same tag id all get added, and the default IE is overwritten by the first one.
  • --wpaent — turn on announcement of WPA-Enterprise in beacons and probe responses, on top of WPA-PSK. 👑
  • --eapreq=[<mode>:]<type><data>[:<term>],... — send max. 20 subsequent EAP requests after the initial EAP ID request, hex string starting with EAP Type. the mode prefix decides the layer the request is exclusively send on: T: = only if any TLS tunnel is up, ignored otherwise. the response is terminated with: :F = EAP Failure, :S = EAP Success, :I = EAP ERP Initiate, :F = EAP ERP Finish, :D = Deauthentication, :T = TLS shutdown, :- = no packet. default behavior is terminating all responses with a EAP Failure, and after the last one the client is deauthenticated. 😭
  • --eapreq_follownak — jump to the Auth Type requested by the client in a Legacy Nak response, if that type is available in the remaining request sequence. 🐇
  • --eaptlstun — activate TLS tunnel negotiation and Phase 2 EAP requests when requesting PEAP. using --eapreq requires --eap_server_cert and --eap_server_key. 🔐
  • --eap_server_cert=<server.pem> — EAP TLS tunnel Server cert PEM file. 📜
  • --eap_server_key=<server.key> — EAP TLS tunnel Server private key file. 🗝️
  • --use_gps_device=<device> — use GPS device /dev/ttyACM0, /dev/ttyUSB0, ... NMEA 0183 $GPGGA $GPGGA 🛰️
  • --use_gpsd — use GPSD device, NMEA 0183 $GPGGA, $GPRMC.
  • --nmea=<file> — save the track to file. format: NMEA 0183 $GPGGA, $GPRMC, $GPWPL. to convert it to gpx, use GPSBabel:
gpsbabel -i nmea -f hcxdumptool.nmea -o gpx -F file.gpx

to display the track, open file.gpx with viking. 🗺️

  • --gpio_button=<digit> — Raspberry Pi GPIO pin number of button (2...27). default = GPIO not in use. 🍓
  • --gpio_statusled=<digit> — Raspberry Pi GPIO number of status LED (2...27). default = GPIO not in use. 💡
  • --gpio_statusled_intervall=<digit> — Raspberry Pi GPIO LED flash intervall. default = flash every 5 seconds. ✨
  • --tot=<digit> — enable the timeout timer in minutes (minimum = 2 minutes). hcxdumptool will terminate if tot is reached (EXIT code = 2). for a successful attack tot > 120 minutes is recommended. ⏳
  • --error_max=<digit> — terminate hcxdumptool if the error maximum is reached. default: 100 errors. 💀
  • --reboot — once hcxdumptool terminated, reboot the system. 🔄
  • --poweroff — once hcxdumptool terminated, power off the system. 🔌
  • --enable_status=<digit> — enable real-time display (waterfall), only incoming traffic. each message is displayed only once, at the first occurrence, to avoid spamming the real-time display. bitmask: 0: no status (default), 1: EAPOL, 2: ASSOCIATION and REASSOCIATION, 4: AUTHENTICATION, 8: BEACON and PROBERESPONSE, 16: ROGUE AP, 32: GPS (once a minute), 64: internal status (once a minute), 128: run as server, 256: run as client, 512: EAP, 1024: EAP NAK. characters < 0x20 && > 0x7e are replaced by .. example: show everything but don't run as server or client (1+2+4+8+16 = 31), show only EAPOL and ASSOCIATION and REASSOCIATION (1+2 = 3). 👀
  • --ip=<IP address> — define IP address for server / client (default: 224.0.0.255) multicast, localhost or client unicast IP address on both sides. 🌐
  • --server_port=<digit> — define port for server status output (1...65535) : default IP: 224.0.0.255 : default port: 60123. 📡
  • --client_port=<digit> — define port for client status read (1...65535) default IP: 224.0.0.255 default port: 60123. 📥
  • --check_driver — run several tests to determine that the driver supports all(!) required ioctl() system calls. the driver must support monitor mode and full packet injection, otherwise hcxdumptool will not work as expected. 🧪
  • --check_injection — run antenna test and packet injection test to determine that the driver supports full packet injection. packet injection will not work as expected if the Wireless Regulatory Domain is unset. 📶
  • --force_interface — ignore all ioctl() warnings and the error counter. allow hcxdumptool to run on a virtual NETLINK monitor interface. ⚠️ warning: packet injection and/or channel change may not work as expected. you have been warned: do not report issues! 🙅
  • --example — show abbreviations and example command lines. 💅
  • --help — show this help. 🫶
  • --version — show version. 🏷️
Make sure that the Wireless Regulatory Domain is not unset! 🌍

Run hcxdumptool -i interface --do_rcascan for at least 30 seconds, to get information about the target! 🔍

Do not edit, merge or convert this pcapng files, because it will remove optional comment fields! 🙈 It is much better to run gzip to compress the files. Wireshark, tshark and hcxpcapngtool will understand this, as well as wpa-sec.stanev.org. ✨

If hcxdumptool captured your password from WiFi traffic, you should check all your devices immediately! 😭

If you use GPS, make sure GPS device is inserted and has a GPS FIX, before you start hcxdumptool! 🛰️

Recommended tools to show additional 802.11 fields or to decrypt WiFi traffic: Wireshark and/or tshark. 🦈

Recommended tool to convert hashes to formats that hashcat and JtR understand: hcxpcapngtool. 🔥

Recommended tool to get possible PSKs from pcapng file: hcxpcapngtool. 🔑

Important notice: Using filter options, could cause that some useful frames are filtered out! In that case hcxpcapngtool will show a warning that this frames are missing! 📢

Use SIGHUB with care, because it will impact pselect(). 💀

💖 AUTHOR 💖

Written by ZeroBeat <zerobeat@gmx.de>. 👑

This manual page was written by Paulo Roberto Alves de Oliveira (aka kretcheu) <kretcheu@gmail.com> for the Debian project (but may be used by others). 🫶

Copyright 2000-2021 ZeroBeat. 💜

License MIT. 📜

okay that's the whole thing bestie, we ate and left no crumbs 💅 this was HCXDUMPTOOL version 6.2.5, dated Dec 2021 — go forth and slay responsibly, mwah 🎀✨🦋

📦 where this page comes from