hcxdumptool

https://github.com/zerbea/hcxdumptool
Admin
hcxdumptool is a capture and penetration testing tool designed to capture packets from WLAN devices...
Tokens:29,951
Snippets:411
Trust Score:8.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install hcxdumptool

Source: https://github.com/zerbea/hcxdumptool/blob/master/README.md

Install the compiled binary to system directories with superuser privileges.

```bash
make install (as super user)
```

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

--------------------------------

### Build and Install hcxdumptool

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/00-overview.md

Standard compilation and installation commands for Linux systems using the provided Makefile.

```bash
make -j $(nproc)
make install PREFIX=/usr/local
```

--------------------------------

### Capture Output Examples

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Sample output logs from running hcxdumptool in different modes.

```text
running rds mode 1, 2, 3

CHA|  LAST  |EA123P|   MAC-CL   |   MAC-AP   |ESSID          (SCAN:  2462/11)
---+--------+------+------------+------------+--------------------------------
 11|08:43:02|ep+++ |1246d6xxxxxx|ccce1exxxxxx|AP_7272
^C
1361 Packet(s) captured by kernel
0 Packet(s) dropped by kernel
exit on sigterm
```

```text
running rds mode 4

TIME     TYPE  MAC_CLIENT   MAC_AP       ESSID
08:47:15 M12   dce1a9xxxxxx dc15c8xxxxxx AP_7272
08:47:27 PMKID 500ee4xxxxxx 5004b8xxxxxx AP_7273
^C
1361 Packet(s) captured by kernel
0 Packet(s) dropped by kernel
exit on sigterm
```

--------------------------------

### Hashcat output example

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Example output showing a successful recovery of WPA passwords during a dictionary attack.

```text
hashcat (v7.1.2-382-g2d71af371) starting

CUDA API (CUDA 13.1)
====================
* Device #01: NVIDIA GeForce RTX 4080, 15701/15945 MB, 76MCU

OpenCL API (OpenCL 3.0 CUDA 13.1.112) - Platform #1 [NVIDIA Corporation]
========================================================================
* Device #02: NVIDIA GeForce RTX 4080, skipped

Minimum password length supported by kernel: 8
Maximum password length supported by kernel: 63
Minimum salt length supported by kernel: 0
Maximum salt length supported by kernel: 256

Hashes: 2 digests; 2 unique digests, 1 unique salts
Bitmaps: 16 bits, 65536 entries, 0x0000ffff mask, 262144 bytes, 5/13 rotates
Rules: 1

Optimizers applied:
* Zero-Byte
* Single-Salt
* Slow-Hash-SIMD-LOOP

Watchdog: Temperature abort trigger set to 90c

Host memory allocated for this attack: 4406 MB (57159 MB free)

Dictionary cache built:
* Filename..: wordlist
* Passwords.: 2856483
* Bytes.....: 31389246
* Keyspace..: 2856483
* Speed.....: 605 MiB/s
* Runtime...: 0.05s

452977dd851b12891cdac3b767cdf42e:ccce1edc3bee:ced2f3e34efc:AP_7272:12345678
7d47aae049369991cd38f22d27da218b:ccce1edc3bee:1246d6b3d1c3:AP_7272:12345678
                                                          
Session..........: hashcat
Status...........: Cracked
Hash.Mode........: 22000 (WPA-PBKDF2-PMKID+EAPOL)
Hash.Target......: testap.hc22000
Time.Started.....: Thu Jan 22 08:52:26 2026 (0 secs)
Time.Estimated...: Thu Jan 22 08:52:26 2026 (0 secs)
Kernel.Feature...: Pure Kernel (password length 8-63 bytes)
Guess.Base.......: File (wordlist)
Guess.Queue......: 1/1 (100.00%)
Speed.#01........:  1496.8 kH/s (8.84ms) @ Accel:4 Loops:512 Thr:384 Vec:1
Recovered........: 2/2 (100.00%) Digests (total), 2/2 (100.00%) Digests (new)
Progress.........: 116741/2856483 (4.09%)
Rejected.........: 5/116741 (0.00%)
Restore.Point....: 0/2856483 (0.00%)
Restore.Sub.#01..: Salt:0 Amplifier:0-1 Iteration:1-3
Candidate.Engine.: Device Generator
Candidates.#01...: $HEX[2020202020202020] -> 20217238
Hardware.Mon.#01.: Temp: 31c Fan:  0% Util:  0% Core:2865MHz Mem:10801MHz Bus:16

Started: Thu Jan 22 08:52:24 2026
Stopped: Thu Jan 22 08:52:28 2026
```

--------------------------------

### PCAPNG Block Layout Example

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/05-pcapng-format.md

Illustrates the typical sequence of blocks in a PCAPNG file, including headers, interface descriptions, custom blocks, and packet blocks.

```text
[Section Header Block]
  - Comment: "hcxdumptool v7.1.2"
  - Hardware: "Raspberry Pi Zero"
  - OS: "Linux"
  - User Application: "hcxdumptool"
  
[Interface Description Block]
  - Interface Name: "wlan0"
  - MAC Address: 00:11:22:33:44:55
  - Timestamp Resolution: nanosecond
  
[Custom Block] (optional PMKID)
  - MAC AP: 00:11:22:33:44:55
  - PMKID: [32 bytes extracted]
  
[Enhanced Packet Block] (Beacon)
  - Packet data + Radiotap header
  - Timestamp: [capture time]
  
[Enhanced Packet Block] (Probe Response)
  - Packet data + Radiotap header
  
[Custom Block] (M1 handshake)
  - MAC AP: 00:11:22:33:44:55
  - MAC Client: 00:aa:bb:cc:dd:ee
  - A-Nonce: [32 bytes]
  - Replay Counter: [8 bytes]
  
[Enhanced Packet Block] (EAPOL M1)
  - Packet data with handshake
  - Custom options embedded
  
[Custom Block] (M2 handshake)
  - MAC AP: 00:11:22:33:44:55
  - MAC Client: 00:aa:bb:cc:dd:ee
  - S-Nonce: [32 bytes]
  - Replay Counter: [8 bytes]
  
[Enhanced Packet Block] (EAPOL M2)
  - Packet data with handshake
  
[Custom Block] (GPS)
  - NMEA: "$GPRMC,..."
  
... additional packets and metadata ...
```

--------------------------------

### Example TSV output format

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Tab-separated values with headers as generated by the tool.

```text
timestamp	latitude	longitude	altitude	speed	rssi	channel	essid
2026-09-03T10:15:32	48.1207	11.5167	545	2.24	-45	6	TestNetwork
```

--------------------------------

### hcxpcapngtool output summary

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Example output generated by hcxpcapngtool after processing a capture file.

```text
hcxpcapngtool 7.0.1-41-g6412f87 reading from testap.pcapng...

summary capture file
--------------------
file name................................: testap.pcapng
version (pcapng).........................: 1.0
operating system.........................: Linux 6.18.5-arch1-1
application..............................: hcxdumptool 7.0.1-46-g96125ac
interface name...........................: wlp48s0f4u2u4
interface vendor.........................: 74da38
openSSL version..........................: 1.0
weak candidate...........................: 12345678
MAC ACCESS POINT.........................: 000e221bc298 (incremented on every new client)
MAC CLIENT...............................: 90b4dd7b81dd
REPLAYCOUNT..............................: 65021
ANONCE...................................: b78dc26402ab03f5941cbd90a85909d2bfcb8a433e630144a31bd00eb9ed3984
SNONCE...................................: ed0baac00e561183ca05efac8e7552c0df03b00ceec0d815e0e02bf867c2c0f8
timestamp minimum (timestamp)............: 22.01.2026 07:49:45 (1769068185)
timestamp maximum (timestamp)............: 22.01.2026 07:50:08 (1769068208)
duration of the dump tool (seconds)......: 22
used capture interfaces..................: 1
link layer header type...................: DLT_IEEE802_11_RADIO (127)
endianness (capture system)..............: little endian
packets inside...........................: 53
packets received on 2.4 GHz..............: 53
ESSID (total unique).....................: 2
BEACON (total)...........................: 1
BEACON on 2.4 GHz channel (from IE_TAG)..: 11 
PROBEREQUEST (undirected)................: 1
PROBEREQUEST (directed)..................: 1
PROBERESPONSE (total)....................: 1
AUTHENTICATION (total)...................: 1
AUTHENTICATION (OPEN SYSTEM).............: 1
EAPOL messages (total)...................: 47
EAPOL RSN messages.......................: 47
EAPOLTIME gap (measured maximum msec)....: 41
EAPOL ANONCE error corrections (NC)......: not detected
EAPOL M1 messages (total)................: 44
EAPOL M2 messages (total)................: 1
EAPOL M3 messages (total)................: 1
EAPOL M4 messages (total)................: 1
EAPOL M4 messages (zeroed NONCE).........: 1
EAPOL pairs (total)......................: 2
EAPOL pairs written to old format JtR....: 1 (RC checked)
EAPOL M12E2 (challenge - ANONCE from M1).: 1
EAPOL M32E2 (authorized - ANONCE from M3): 1

frequency statistics from radiotap header (frequency: received packets)
-----------------------------------------------------------------------
 2462: 53

session summary
---------------
processed pcapng files................: 1
```

--------------------------------

### hcxpcapngtool output summary

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Example output generated by hcxpcapngtool after processing a capture file.

```text
hcxpcapngtool 7.0.1-41-g6412f87 reading from testap.pcapng...

summary capture file
--------------------
file name................................: testap.pcapng
version (pcapng).........................: 1.0
operating system.........................: Linux 6.18.5-arch1-1
application..............................: hcxdumptool 7.0.1-46-g96125ac
interface name...........................: wlp48s0f4u2u4
interface vendor.........................: 74da38
openSSL version..........................: 1.0
weak candidate...........................: 12345678
MAC ACCESS POINT.........................: 000e221bc298 (incremented on every new client)
MAC CLIENT...............................: 90b4dd7b81dd
REPLAYCOUNT..............................: 65021
ANONCE...................................: b78dc26402ab03f5941cbd90a85909d2bfcb8a433e630144a31bd00eb9ed3984
SNONCE...................................: ed0baac00e561183ca05efac8e7552c0df03b00ceec0d815e0e02bf867c2c0f8
timestamp minimum (timestamp)............: 22.01.2026 07:49:45 (1769068185)
timestamp maximum (timestamp)............: 22.01.2026 07:50:08 (1769068208)
duration of the dump tool (seconds)......: 22
used capture interfaces..................: 1
link layer header type...................: DLT_IEEE802_11_RADIO (127)
endianness (capture system)..............: little endian
packets inside...........................: 53
packets received on 2.4 GHz..............: 53
ESSID (total unique).....................: 2
BEACON (total)...........................: 1
BEACON on 2.4 GHz channel (from IE_TAG)..: 11 
PROBEREQUEST (undirected)................: 1
PROBEREQUEST (directed)..................: 1
PROBERESPONSE (total)....................: 1
AUTHENTICATION (total)...................: 1
AUTHENTICATION (OPEN SYSTEM).............: 1
EAPOL messages (total)...................: 47
EAPOL RSN messages.......................: 47
EAPOLTIME gap (measured maximum msec)....: 41
EAPOL ANONCE error corrections (NC)......: not detected
EAPOL M1 messages (total)................: 44
EAPOL M2 messages (total)................: 1
EAPOL M3 messages (total)................: 1
EAPOL M4 messages (total)................: 1
EAPOL M4 messages (zeroed NONCE).........: 1
EAPOL pairs (total)......................: 2
EAPOL pairs (best).......................: 1
EAPOL pairs written to 22000 hash file...: 1 (RC checked)
EAPOL M32E2 (authorized - ANONCE from M3): 1

frequency statistics from radiotap header (frequency: received packets)
-----------------------------------------------------------------------
 2462: 53

session summary
---------------
processed pcapng files................: 1
```

--------------------------------

### Headless Raspberry Pi Setup

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Configures automated capture with watchdog timers and error handling for unattended operation. The system is set to reboot automatically upon timeout, watchdog trigger, or error threshold.

```bash
sudo hcxdumptool -i wlan0 -F \
  --tot=60 \
  --ontot=reboot \
  --watchdogmax=120 \
  --onwatchdog=reboot \
  --errormax=50 \
  --onerror=reboot \
  --daemonize \
  -w /var/log/hcx.pcapng
```

--------------------------------

### Capture packets with interface and output file

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Basic command to start packet capture on a specific interface and save to a PCAPNG file.

```bash
hcxdumptool -i wlan0 -w output.pcapng
```

```bash
hcxdumptool -i wlan0 -w capture.pcapng
```

--------------------------------

### Configure Automatic Recovery

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Example of using the watchdog timer to automatically reboot the system if packet reception stops.

```bash
hcxdumptool -i wlan0 \
  --watchdogmax=120 \
  --onwatchdog=reboot \
  -w output.pcapng
```

--------------------------------

### BPF beacon filter rule

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Example content for a BPF filter file to capture only beacon frames.

```text
type mgt subtype beacon
```

--------------------------------

### Example NMEA output format

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Raw NMEA 0183 sentences as generated by the tool.

```text
$GPRMC,123519,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A
$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47
$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*30
```

--------------------------------

### Test BPF Filter

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Verify the filter logic using tshark before starting the attack.

```bash
tshark -i INTERFACE_NAME -f "wlan addr1 ccce1edc3bee or wlan addr2 ccce1edc3bee or wlan addr3 ccce1edc3bee or type mgt subtype probereq"
```

--------------------------------

### Valid BPF Filter Strings

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Examples of valid BPF filter strings for use with the --bpfc option.

```bash
# Minimal valid
"ip"

# Target specific AP
"wlan addr3 00:11:22:33:44:55"

# Beacon frames only
"type mgt subtype beacon"
```

--------------------------------

### Display help and version information

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Commands to retrieve help documentation or version details.

```bash
hcxnmealog -h
```

```bash
hcxnmealog -H
```

```bash
hcxnmealog -v
```

--------------------------------

### Create a Minimal PCAPNG File in C

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/05-pcapng-format.md

Demonstrates the structure of Section Header, Interface Description, and Enhanced Packet Blocks for a valid PCAPNG file.

```c
// Write Section Header Block
shb.block_type = 0x0a0d0d0a;
shb.byte_order_magic = 0x1a2b3c4d;  // Little-endian
shb.major_version = 1;
shb.minor_version = 0;
shb.total_length = 28 + 4;  // No options
write_block(&shb);

// Write Interface Description Block
idb.block_type = 0x00000001;
idb.linktype = 127;  // Radiotap
idb.snaplen = 0x400;
idb.total_length = 20 + 4;
write_block(&idb);

// Write packet
epb.block_type = 0x00000006;
epb.interface_id = 0;
epb.timestamp_high = time_sec;
epb.timestamp_low = time_nsec;
epb.cap_len = packet_len;
epb.org_len = packet_len;
epb.total_length = 28 + packet_len + padding + 4;
write_block(&epb);
```

--------------------------------

### Run initial WiFi capture commands

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/README.md

Use these commands to identify available network interfaces and initiate a passive packet capture session.

```bash
# List available WiFi interfaces
sudo hcxdumptool -l

# Passive capture (no attacks)
sudo hcxdumptool -i wlan0 -m -F -w capture.pcapng
```

--------------------------------

### Display interface information

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Commands to inspect interface capabilities and list available hardware.

```bash
hcxdumptool -i wlan0 -I
```

```bash
hcxdumptool -L
```

```bash
hcxdumptool -l
```

--------------------------------

### Apply BPF from File

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Reads BPF rules from a specified file.

```bash
hcxdumptool -i wlan0 --bpf filter.bpf -w output.pcapng
```

```text
wlan addr1 ccce1edc3bee or wlan addr2 ccce1edc3bee or wlan addr3 ccce1edc3bee
```

--------------------------------

### Check Driver Capabilities and Set Monitor Mode

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to inspect supported interface modes and manually configure an interface to monitor mode.

```bash
# Check driver capabilities
iw list | grep -A5 "Supported interface modes"

# Manually set monitor mode
sudo iw dev wlan0 set type monitor
```

--------------------------------

### John the Ripper execution output

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Example output showing the progress and results of a John the Ripper cracking session.

```text
$ john -w wordlist --format=wpapsk-opencl testap.john
Device 1: NVIDIA GeForce RTX 4080
Using default input encoding: UTF-8
Loaded 2 password hashes with no different salts (wpapsk-opencl, WPA/WPA2/PMF/PMKID PSK [PBKDF2-SHA1 HMAC-SHA256/AES-CMAC OpenCL])
Note: Passwords longer than 21 [worst case UTF-8] to 63 [ASCII] rejected
Note: Minimum length forced to 8 by format
LWS=32 GWS=77824 (2432 blocks) 
Proceeding with wordlist:/usr/share/john/password.lst
Press 'q' or Ctrl-C to abort, 'h' for help, almost any other key for status
12345678         (AP_7272)     
12345678         (AP_7272)     
2g 0:00:00:00 DONE (2026-01-22 10:03) 13.33g/s 518826p/s 518826c/s 1037KC/s Dev#1:48°C password..lilwayne6
Use the "--show" option to display all of the cracked passwords reliably
Session completed
```

--------------------------------

### General Workflow Overview

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

The standard pipeline for processing captured data.

```text
hcxdumptool -> hcxtools (hcxpcapngtool, hcxhashtool, hcxpsktool) -> hashcat or john -> upload to wpa-sec for a further weak password analysis
```

--------------------------------

### Configure GPIO button action

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Sets the action to perform when a configured GPIO button is pressed.

```bash
hcxdumptool -i wlan0 --ongpiobutton=poweroff -w output.pcapng
```

--------------------------------

### Verify Network Interfaces

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to list available network interfaces and wireless devices for troubleshooting interface-related errors.

```bash
# Check available interfaces
ip link show
# Or with wireless focus
iw dev
```

--------------------------------

### Enable Debug Build

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Instructions for compiling with debug symbols and analyzing the resulting log file.

```bash
# Edit Makefile to enable DEBUG
make clean
CFLAGS="-g -DHCXDEBUG" make

# Run with debug output
sudo ./hcxdumptool -i wlan0 -w output.pcapng 2>debug.log

# Analyze debug log
grep -i "error\|fail\|warning" debug.log
```

--------------------------------

### Typical hcxdumptool workflow

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/README.md

The standard pipeline for processing captured data from raw pcapng files to hash cracking tools.

```text
hcxdumptool → .pcapng → hcxpcapngtool → .22000 → Hashcat/JtR
```

--------------------------------

### Clone the hcxdumptool repository

Source: https://github.com/zerbea/hcxdumptool/blob/master/README.md

Use git to download the source code from the official repository.

```bash
git clone https://github.com/ZerBea/hcxdumptool.git
cd hcxdumptool
```

--------------------------------

### List and Verify Serial Devices

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to identify available serial devices and verify user permissions for access.

```bash
# List serial devices
ls -la /dev/tty*

# Check permissions
sudo -l  # for serial access
```

--------------------------------

### Verify root access

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Check current user privileges to ensure the tool has necessary permissions.

```bash
sudo id
```

--------------------------------

### Verify interface state

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Check the status and configuration of the wireless interface.

```bash
iw dev wlan0 info
```

--------------------------------

### Compile BPF from Command Line

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Compiles a BPF filter string directly from the command line, requiring libpcap support.

```bash
hcxdumptool -i wlan0 --bpfc="wlan addr1 00:11:22:33:44:55" -w output.pcapng
```

```bash
"wlan addr3 00:11:22:33:44:55"           # Target specific AP
"not wlan addr3 00:11:22:33:44:55"       # Exclude specific AP
"type mgt subtype beacon"                 # Beacons only
"type mgt subtype probereq"               # Probe requests only
```

--------------------------------

### Initial Network Discovery

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Perform an interactive scan to identify nearby access points and their signal characteristics without initiating attacks.

```bash
# View available interfaces
sudo hcxdumptool -l

# Interactive scan with range check
sudo hcxdumptool -i wlan0 \
  --rcascan=active \
  --rds=5 \
  -F \
  -t 10
```

--------------------------------

### Check System Resources

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to monitor system health, including memory, disk, CPU, and interface errors.

```bash
# Memory usage
free -h

# Disk space
df -h

# CPU load
top -bn1 | head -10

# Network interface errors
ethtool -S wlan0 | grep -i err
```

--------------------------------

### GPS-Enabled Capture Configuration

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/04-configuration.md

Runs hcxdumptool with GPS support alongside hcxnmealog for NMEA data logging.

```bash
hcxdumptool -i wlan0 -w capture.pcapng -F &
hcxnmealog -i wlan0 -d /dev/ttyUSB0 -n gps.nmea -t gps.tsv
```

--------------------------------

### Basic GPS Logging

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Capture GPS NMEA sentences at default 9600 baud.

```bash
hcxnmealog -d /dev/ttyUSB0 -n gps_output.nmea
```

--------------------------------

### Output BPF Compilation Format

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Displays the BPF compilation format for debugging purposes.

```bash
hcxdumptool --bpfd=2 --bpfc="type mgt subtype beacon"
```

--------------------------------

### Create BPF Filters

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Generate BPF files to either target or protect specific MAC addresses.

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

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

--------------------------------

### Troubleshoot Output File Errors

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to diagnose disk space, directory existence, and write permissions for output files.

```bash
# Check disk space
df -h /path/to/output

# Verify directory
ls -ld /path/to/output/

# Ensure write permission
touch /path/to/output/test.txt
```

--------------------------------

### Perform a GPS-enabled site survey

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/README.md

Run simultaneous processes for WiFi packet capture and GPS coordinate logging.

```bash
# Terminal 1: WiFi capture
sudo hcxdumptool -i wlan0 -F -w survey.pcapng &

# Terminal 2: GPS logging
sudo hcxnmealog -i wlan0 -d /dev/ttyUSB0 -n gps.nmea -t gps.tsv
```

--------------------------------

### Execute hcxdumptool Attack

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Run the capture tool with various invasive levels using the generated BPF.

```bash
sudo hcxdumptool -i wlan0 -c 11a --bpf=attack.bpf -w testap.pcapng

or (do not respond to CLIENTs)
sudo hcxdumptool -i wlan0 --rds=3 -c 11a --proberesponsetx=0 --bpf=attack.bpf -w testap.pcapng

or (do not DISASSOCIATE CLIENTs)
sudo hcxdumptool -i wlan0 --rds=3 -c 11a --disable_disassociation --bpf=attack.bpf -w testap.pcapng

or (do not respond to CLIENTs and do not DISASSOCIATE CLIENTs)
sudo hcxdumptool -i wlan0 --rds=3 -c 11a --proberesponsetx=0 --disable_disassociation --bpf=attack.bpf -w testap.pcapng
```

--------------------------------

### Resolve Capture Issues

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Manually configure monitor mode and restart the capture process.

```bash
# Manually set monitor mode
sudo iw dev wlan0 set type monitor
sudo ip link set wlan0 up

# Restart hcxdumptool
sudo hcxdumptool -i wlan0 -m -w test.pcapng
```

--------------------------------

### Capture NMEA data with interface correlation

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Run the tool with a specified network interface, GPS device path, and output file.

```bash
hcxnmealog -i wlan0 -d /dev/ttyUSB0 -n gps.nmea
```

--------------------------------

### Monitor system resources

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Check disk space and memory availability to rule out resource-related failures.

```bash
df -h && free -h
```

--------------------------------

### Run hcxnmealog and hcxdumptool in parallel

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Execute these commands in separate terminal sessions to log GPS data while performing packet capture.

```bash
# Terminal 1: GPS + WiFi logging
sudo hcxnmealog -i wlan0 -d /dev/ttyUSB0 -n gps.nmea -t gps.tsv

# Terminal 2: Parallel packet capture
sudo hcxdumptool -i wlan0 -w packets.pcapng -F --tot=60
```

--------------------------------

### Check Interface Status

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Commands to verify interface details, monitor mode status, and driver capabilities.

```bash
# View interface details
ip link show wlan0

# Check monitor mode
iw dev wlan0 info

# View driver capabilities
iw list | head -50
```

--------------------------------

### Compile hcxdumptool

Source: https://github.com/zerbea/hcxdumptool/blob/master/README.md

Compile the source code using make with parallel processing enabled.

```bash
make -j $(nproc)
```

--------------------------------

### Configure rogue AP client limit

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Sets the maximum number of clients allowed to connect to the rogue AP for M1M2 challenge capture.

```bash
hcxdumptool -i wlan0 --m2max=10 -w output.pcapng
```

--------------------------------

### Configure Active Monitor Mode

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Sets the interface to active monitor mode with full frame injection enabled.

```bash
hcxdumptool -i wlan0 -A -w capture.pcapng
```

--------------------------------

### Configure GPIO status LED pin

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Specifies the GPIO pin number for the status LED output.

```bash
hcxdumptool -i wlan0 --gpio_statusled=27 -w output.pcapng
```

--------------------------------

### Configure unattended Raspberry Pi operation

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/README.md

Run hcxdumptool in daemon mode with automated watchdog and timeout triggers for long-term field deployment.

```bash
sudo hcxdumptool -i wlan0 -F \
  --tot=480 \
  --ontot=poweroff \
  --watchdogmax=300 \
  --onwatchdog=reboot \
  --daemonize \
  -w /mnt/usb/capture.pcapng
```

--------------------------------

### Define interface_t structure

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/03-types.md

Configures WiFi interface state, capabilities, and hardware details. Includes flags for netlink support, monitor mode, and interface status.

```c
typedef struct __attribute__((__packed__))
{
 int index;                          // Interface index
 int wiphy;                          // Physical device number
 u64 wdev;                           // Wireless device ID
 u8 type;                            // Type flags (see below)
#define IF_HAS_NETLINK      0x01     // Has netlink support
#define IF_HAS_MONITOR      0x02     // Has monitor mode
#define IF_HAS_MONITOR_ACTIVE 0x04   // Has active monitor mode
#define IF_HAS_NLMON        0x03     // netlink + monitor (0x01|0x02)
#define IF_HAS_NLMON_ACTIVE 0x07     // Full support (0x01|0x02|0x04)
#define IF_IS_SHARED        0x08     // Interface shared with others
 u8 status;                          // Status flags (see below)
#define IF_STAT_MONITOR     0x01     // Currently in monitor mode
#define IF_STAT_UP          0x02     // Interface is up
#define IF_STAT_OK          0x03     // OK status (UP + MONITOR)
 u8 hwmac[6];                        // Hardware MAC address
 u8 vimac[6];                        // Virtual MAC address
 char name[IFNAMSIZ + 1];            // Interface name (16 bytes)
 char driver[32];                    // Driver name
 size_t i;                           // Index for frequency list
 frequencylist_t *frequencylist;     // Pointer to frequency list
} interface_t;
```

--------------------------------

### Manual Recovery Procedures

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Steps to stop, restart, or reset the interface to managed mode when capture fails.

```bash
# Kill any running instance
sudo pkill hcxdumptool

# Verify interface is down/up
sudo ip link set wlan0 down
sleep 1
sudo ip link set wlan0 up

# Restart capture
sudo hcxdumptool -i wlan0 -w output.pcapng
```

```bash
# Set to managed mode
sudo iw dev wlan0 set type managed

# Kill NetworkManager if interfering
sudo systemctl stop NetworkManager

# Re-enable capture
sudo hcxdumptool -i wlan0 -A -w output.pcapng
```

--------------------------------

### 64-bit Option Format Structure

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/05-pcapng-format.md

Specific structure for options containing 64-bit values, using a fixed length of 8 bytes.

```c
typedef struct __attribute__((__packed__))
{
 u16 option_code;        // 0xf29c (example: RC)
 u16 option_length;      // 8 (for 64-bit)
 u64 option_value;       // 64-bit value
}
```

--------------------------------

### Enable Realtime Scan Display with --rds

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Configures the real-time statistics output mode for the capture process.

```bash
hcxdumptool -i wlan0 --rds=3 -w output.pcapng
```

--------------------------------

### Inspect PCAPNG block structure

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/05-pcapng-format.md

Displays the first 50 lines of a PCAPNG file in hexadecimal format to analyze block headers.

```bash
hexdump -C capture.pcapng | head -50
```

--------------------------------

### Configure GPIO button pin

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Specifies the GPIO pin number for push button input.

```bash
hcxdumptool -i wlan0 --gpio_button=17 --ongpiobutton=reboot -w output.pcapng
```

--------------------------------

### Enable watchdog timer

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Sets a timeout period; the tool exits if no packets are received within this duration.

```bash
hcxdumptool -i wlan0 --watchdogmax=60 -w output.pcapng
```

--------------------------------

### WiFi-Correlated GPS Logging

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Correlate GPS positions with WiFi access points.

```bash
sudo hcxnmealog -i wlan0 -d /dev/ttyUSB0 \
  -n gps.nmea \
  -t gps_correlated.tsv
```

--------------------------------

### Headless operation with auto-exit

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Runs in the background with automated power management and watchdog reboot triggers.

```bash
sudo hcxdumptool -i wlan0 -F \
  --tot=30 \
  --ontot=poweroff \
  --watchdogmax=60 \
  --onwatchdog=reboot \
  --daemonize \
  -w /var/log/hcx.pcapng
```

--------------------------------

### Apply BPF filter to hcxnmealog

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Use a Berkeley Packet Filter file to restrict captured traffic.

```bash
hcxnmealog -i wlan0 -d /dev/ttyUSB0 --bpf filter.bpf -n gps.nmea
```

--------------------------------

### Configure Range Scanning with --rcascan

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Enables discovery mode for access points without capturing handshakes; incompatible with output file writing.

```bash
hcxdumptool -i wlan0 --rcascan=active -F --rds=1
```

--------------------------------

### Convert PCAPNG to Hashcat Format

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Use hcxpcapngtool to convert captured packets into Hashcat-compatible formats and verify capture contents.

```bash
# Process captured packets
hcxpcapngtool -i capture.pcapng -o hashes.22000

# Check what was captured
hcxpcapngtool -i capture.pcapng -c
```

--------------------------------

### Diagnose Device Disconnection

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Verify hardware connectivity and interface status.

```bash
# Check if interface disappeared
ip link show wlan0

# Check USB device
lsusb | grep -i wireless
```

--------------------------------

### Check driver logs

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Inspect the kernel log for hardware or driver-specific error messages.

```bash
dmesg | tail -20
```

--------------------------------

### Enable Full-Throughput Channel Mode with --ftc

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Forces capture on a specific channel, bypassing standard channel hopping to increase capture rate.

```bash
hcxdumptool -i wlan0 -c 6 --ftc -w output.pcapng
```

--------------------------------

### Configure watchdog exit action

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/01-hcxdumptool-cli.md

Sets the action to perform when the watchdog timer expires due to lack of packet reception.

```bash
hcxdumptool -i wlan0 --watchdogmax=120 --onwatchdog=reboot -w output.pcapng
```

--------------------------------

### Hashcat GPU Cracking Pipeline

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Complete workflow for capturing traffic, extracting hashes, and running a brute-force attack using Hashcat.

```bash
# Step 1: Capture
sudo hcxdumptool -i wlan0 -F --tot=30 -w survey.pcapng

# Step 2: Extract hashes
hcxpcapngtool -i survey.pcapng -o hashes.22000

# Step 3: Check format
head -1 hashes.22000 | cut -c1-20

# Step 4: Crack with GPU
hashcat -m 22000 -a 3 hashes.22000 '?d?d?d?d?d?d?d?d'

# Step 5: Check results
hashcat -m 22000 hashes.22000 --show
```

--------------------------------

### Execute Hashcat dictionary attack

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Run a dictionary attack against a WPA capture file using mode 22000 and a custom pot file path.

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

--------------------------------

### Incremental capture testing

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Progressively add complexity to capture commands to isolate configuration issues.

```bash
# Step 1: Basic capture
sudo hcxdumptool -i wlan0 -m -w test.pcapng -t 10

# Step 2: Add attack options
sudo hcxdumptool -i wlan0 -w test.pcapng -A -t 10

# Step 3: Add filtering
sudo hcxdumptool -i wlan0 --bpf=filter.bpf -w test.pcapng
```

--------------------------------

### Filtered WiFi + GPS

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Log GPS alongside beacon frames only.

```bash
sudo hcxnmealog -i wlan0 -d /dev/ttyUSB0 \
  --bpf beacon_only.bpf \
  -n gps.nmea
```

--------------------------------

### Bluetooth GPS Device

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Use Bluetooth GPS device (requires rfcomm binding).

```bash
hcxnmealog -d /dev/rfcomm0 -b 9600 -n gps.nmea
```

--------------------------------

### Auto-Exit on Success Configuration

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/04-configuration.md

Sets automated exit conditions based on time, EAPOL count, and system signals.

```bash
hcxdumptool -i wlan0 \
  -w output.pcapng \
  --tot=60 \
  --exitoneapol=3 \
  --onsigterm=reboot \
  --ontot=poweroff
```

--------------------------------

### Define PCAPNG Option Header

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/03-types.md

The option_header_t provides a generic format for various option types.

```c
typedef struct __attribute__((__packed__))
{
 u16 option_code;        // Option code (depends on block type)
 u16 option_length;      // Option data length in bytes
 char option_data[1];    // Variable-length option data
} option_header_t;
```

--------------------------------

### Convert pcapng to hashcat format

Source: https://github.com/zerbea/hcxdumptool/blob/master/docs/example.md

Use this command to convert a captured pcapng file into a .hc22000 file for hashcat.

```bash
hcxpcapngtool -o testap.hc22000 testap.pcapng
```

--------------------------------

### Configure GPS device path

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Specify the serial port path for the GPS device.

```bash
hcxnmealog -d /dev/ttyUSB0 -n gps.nmea
```

--------------------------------

### Authentication Key Management (AKM_*)

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/02-hcxnmealog-cli.md

Constants representing authentication key management methods.

```text
AKM_8021X       = 0x00010000    // 802.1X authentication
AKM_PSK         = 0x00020000    // Pre-Shared Key
AKM_FT8021X     = 0x00040000    // FT 802.1X
AKM_FTPSK       = 0x00080000    // FT PSK
AKM_8021XSHA256 = 0x00100000    // 802.1X with SHA256
AKM_PSKSHA256   = 0x00200000    // PSK with SHA256
AKM_SAESHA256   = 0x00800000    // SAE-SHA256 (WPA3)
AKM_FTSAESHA256 = 0x01000000    // FT SAE-SHA256
AKM_UNKNOWN     = 0x80000000    // Unknown AKM
```

--------------------------------

### Configure watchdog for headless operation

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/06-errors-and-diagnostics.md

Set automatic recovery parameters for long-running or unattended operations.

```bash
--watchdogmax=120 --onwatchdog=reboot
```

--------------------------------

### Extract Weak Passwords

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Use hcxpsktool to identify weak password candidates and generate statistics from captured hashes.

```bash
# Find weak password candidates
hcxpsktool -i hashes.22000 -o weak_candidates.txt

# See most common patterns
hcxpsktool -i hashes.22000 -o candidates.txt --statistics
```

--------------------------------

### Automated Field Operation with GPS

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Execute a long-term survey script that captures WiFi traffic and logs GPS coordinates, including automated power management.

```bash
# Setup script
cat > fieldsurvey.sh <<'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
OUTPUT_DIR="/mnt/usb/surveys/$DATE"
mkdir -p "$OUTPUT_DIR"

# Start packet capture
sudo hcxdumptool -i wlan0 \
  -F -t 10 \
  --tot=480 \
  --ontot=poweroff \
  --watchdogmax=300 \
  --onwatchdog=reboot \
  -w "$OUTPUT_DIR/packets.pcapng" &

# Start GPS logging
sudo hcxnmealog -i wlan0 \
  -d /dev/ttyUSB0 \
  -b 9600 \
  -n "$OUTPUT_DIR/gps.nmea" \
  -t "$OUTPUT_DIR/gps.tsv"

wait
EOF

chmod +x fieldsurvey.sh
sudo ./fieldsurvey.sh
```

--------------------------------

### Diagnose Capture Issues

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/07-usage-examples.md

Verify monitor mode and driver support when packets are not being captured.

```bash
# Check interface is in monitor mode
iw dev wlan0 info

# Verify driver supports monitor mode
iw list | grep -A5 "Supported interface modes"

# Check for packet loss
tcpdump -i wlan0 -c 10 -v
```

--------------------------------

### Generic Option Header Structure

Source: https://github.com/zerbea/hcxdumptool/blob/master/_autodocs/05-pcapng-format.md

Defines the standard header for all options within a block, requiring 4-byte boundary padding for the data field.

```c
typedef struct __attribute__((__packed__))
{
 u16 option_code;        // Option code (e.g., 0xf29a)
 u16 option_length;      // Data length in bytes
 char option_data[1];    // Variable data (padded to 4-byte boundary)
}
```
Tokens:
Raw