---
name: "hcxdumptool"
section: "1"
platform: "linux"
package: "hcxdumptool"
version: "6.3.5-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/hcxdumptool"
---

# hcxdumptool(1)

tool to capture packets from wlan devices.

## 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.**

## OPTIONS

**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**

```
  bitmask:
  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**

  - **--active\_beacon**

    **: transmit beacon from collected ESSIDs and from essidlist once every 10000000 nsec** **affected: ap-less**

  - **--flood\_beacon**

    **: transmit beacon on every received beacon** **affected: ap-less**

  - **--all\_m2**

    **: accept all connection attempts from a CLIENT** **affected: CLIENTs** **warning: that can prevent that a CLIENT can establish a connection to an assigned ACCESS POINT**

  - **--infinity**

    **: prevent that a CLIENT can establish a connection to an assigned ACCESS POINT** **affected: ACCESS POINTs and CLIENTs**

  - **--beaconparams=\<TLVs\>**

    **: update or add Information Elements in all reactive and essidlist beacons** **maximum 50 IEs as TLV hex string, tag id 0 (ESSID) will be ignored, tag id 3 (channel) overwritten** **multiple IEs with same tag id are added, default IE is overwritten by the first**

  - **--wpaent**

    **: enable announcement of WPA-Enterprise in beacons and probe responses in addition to WPA-PSK**

  **--eapreq=\[\<mode\>:\]\<type\>\<data\>\[:\<term\>\],...** **send max. 20 subsequent EAP requests after initial EAP ID request, hex string starting with EAP Type** **mode prefix determines layer the request is exclusively send on:** **T: = only if any TLS tunnel is up, ignored otherwise** **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, after last one the client is deauthenticated**

  - **--eapreq\_follownak**

    **: jump to Auth Type requested by client in Legacy Nak response, if type available in 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 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 timeout timer in minutes (minimum = 2 minutes)** **hcxdumptool will terminate if tot reached (EXIT code = 2)** **for a successful attack tot \> 120 minutes recommended**

  - **--error\_max=\<digit\>**

    **: terminate hcxdumptool if error maximum reached** **default: 100 errors**

  - **--reboot**

    **: once hcxdumptool terminated, reboot system**

  - **--poweroff**

    **: once hcxdumptool terminated, power off 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 driver support 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 driver support full packet injection** **packet injection will not work as expected if the Wireless Regulatory Domain is unset**

- **--force\_interface**

  **: ignore all ioctl() warnings and 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

**Copyright 2000-2021 ZeroBeat.**

**License MIT.**