hcxdumptool Documentation

hcxdumptool is an analysis toolkit designed for capturing wireless traffic in the modern pcapng format. It does not perform cracking or conversion itself. Instead, it is part of a multi-tool pipeline:

1. Capture: Use hcxdumptool to capture raw traffic.
2. Convert: Use hcxpcapngtool (from hcxtools) to convert pcapng files into formats readable by Hashcat or JtR.
3. Filter/Process: Use hcxhashtool, hcxpsktool, or hcxeiutool (from hcxtools) to filter hashes or generate wordlists.
4. Crack: Use Hashcat or JtR to recover the PSK from the processed hashes.

hcxdumptool -> hcxpcapngtool -> hcxhashtool (additional hcxpsktool/hcxeiutool) -> Hashcat or JtR

By default, hcxdumptool utilizes three attack vectors:

1. Connecting to an Access Point to get a PMKID (disable via --associationmax=0).
2. Disconnecting a client from an AP to get a handshake (M1M2M3M4) and PMKID (disable via --disable_disassociation).
3. Allowing a client to connect to hcxdumptool (OSI layer 2 attack) to get a challenge (M1M2) or an EAP-ID (disable via --m2max=0).

Safety and Control

hcxdumptool should only be used in a 100% controlled environment. If you cannot control the environment, it is mandatory to set a Berkeley Packet Filter (BPF) to select specific targets or protect other devices.

A typical attack workflow using this toolset follows this pipeline:

1. Capture: Use hcxdumptool to capture wireless frames.
2. Convert: Use hcxtools (specifically hcxpcapngtool, hcxhashtool, or hcxpsktool) to convert the capture into a format suitable for cracking.
3. Crack: Use hashcat or john to perform the password cracking.
4. Analyze: Optionally upload results to wpa-sec for weak password analysis.

To manually terminate the process using the hardware modification:

1. Press and hold the push button for at least 10 seconds.
2. Wait for the LED to turn on (the LED also turns on automatically when hcxdumptool terminates).
3. Once the LED is on, you can safely turn off the Raspberry Pi and disconnect its power supply.

Use the converted files to perform a dictionary attack.

Using Hashcat: It is recommended to use a separate pot file to avoid overwriting existing results.

hashcat -m 22000 --potfile-path=hashcat.wpa.pot testap.hc22000 wordlist

Using John the Ripper:

john --pot=john.wpa.pot -w wordlist --format=wpapsk-opencl testap.john

To check if a captured password is weak, you can upload the .pcapng dump to the Distributed WPA PSK auditor (wpa-sec) via their web interface or using the wlancap2wpasec tool:

wlancap2wpasec dump_file_name.pcapng

Once a capture is complete, use hcxpcapngtool to convert the .pcapng file into a format compatible with cracking tools.

For Hashcat (Mode 22000):

hcxpcapngtool -o testap.hc22000 testap.pcapng

For John the Ripper:

hcxpcapngtool --john testap.john testap.pcapng

Troubleshooting Conversion: hcxpcapngtool may throw errors if:

• The capture is too short or incomplete.
• The file format is outdated.
• Too many DEAUTHENTICATION/DISASSOCIATION frames were detected.
• The capture file was cleaned.
• No undirected PROBEREQUESTs were detected.
• Too few M1 frames were detected.

While available via package managers, it is highly recommended to clone and build from source to ensure you have the latest version. Ensure all dependencies (like libpcap and libpcap-dev) are installed before compiling.

Clone and Compile

git clone https://github.com/ZerBea/hcxdumptool.git
cd hcxdumptool
make -j $(nproc)

Install

To install to /usr/bin:

make install (as super user)

To install to /usr/local/bin:

make install PREFIX=/usr/local (as super user)

Headless Optimization

If running on a headless system (e.g., Raspberry Pi), remove -DSTATUSOUT from the Makefile before compiling. This prevents the status display from being compiled, saving CPU cycles and preventing errors.

Creating a Berkeley Packet Filter (BPF) is mandatory to instruct hcxdumptool to either attack or ignore specific addresses.

To attack a specific MAC address (e.g., ccce1edc3bee) including its probe requests, generate a BPF file using the --bpfc flag:

hcxdumptool --bpfc="wlan addr1 ccce1edc3bee or wlan addr2 ccce1edc3bee or wlan addr3 ccce1edc3bee or type mgt subtype probereq" > attack.bpf

To protect an address (ensure hcxdumptool ignores it), use the not operator:

hcxdumptool --bpfc="not wlan addr3 ccce1edc3bee" > protect.bpf

Note: Do not filter undirected PROBEREQUEST frames, as they may contain PreSharedKeys.

After creating a BPF, run hcxdumptool with root/sudo privileges. You can adjust the invasiveness of the attack using various flags:

• Basic attack: Specify interface, channel, BPF, and output file.
• Non-responsive to clients: Use --proberesponsetx=0 to prevent responding to client probe requests.
• Disable disassociation: Use --disable_disassociation to prevent the tool from sending disassociation frames to clients.

Example commands:

# Standard attack
sudo hcxdumptool -i wlan0 -c 11a --bpf=attack.bpf -w testap.pcapng

# Attack without responding to clients
sudo hcxdumptool -i wlan0 --rds=3 -c 11a --proberesponsetx=0 --bpf=attack.bpf -w testap.pcapng

# Attack without responding to clients AND without disassociating clients
sudo hcxdumptool -i wlan0 --rds=3 -c 11a --proberesponsetx=0 --disable_disassociation --bpf=attack.bpf -w testap.pcapng