Documentation about attack vectors and what options affect them

[glibg10b]

Describe the feature README.md, the wiki or hcxdumptool -h should explain which attacks are done by hcxdumptool, as well as which command-line options affect them.

Current behavior The behaviour of each option is well documented. However, it is hard to predict what attacks hcxdumptool will perform for a given set of options (and especially when no options are provided). For example, it's unclear which attacks are affected when passing --disable_beacon:

--disable_beacon          : disable internal BEACON
                             default: one BEACON/second to wildcard SSID

Expected behavior Some output borrowed from one of ZerBea's forum posts. Notice the list of affected attacks, which --help currently doesn't have for any options:

--disable_ap_attacks     : do not attack access points
                            affected: connected clients and client-less (PMKID) attack
--disable_client_attacks : do not attack clients
                            affected: ap-less (EAPOL 2/4 - M2) attack

In addition to this, the attack vectors themselves should be documented, along with the important parts of what they do (the things most likely to annoy your neighbours). Here's some low quality mock output:

attacks:
--------
client-less (PMKID) : nicely asks an AP for M1
m4 - retry          : requests m2/m3, prevents client from reconnecting
deauthentication    : disconnects a client and captures the following authentication

[ZerBea]

By latest commit I've added an information about hcxdumptool's three attack vectors to README.md:

By default options hcxdumptool is running three attack vectors:
* connect to an ACCESS POINT to get a PMKID (turn off by --attemptapmax)
* disconnect a CLIENT from an associated ACCESS POINT to get a complete handshake (M1M2M3M4) and a PMKID (turn off by --attemptapmax)
* allow a CLIENT to connect to hcxdumptool to get a challenge (M1M2) or an EAP-ID (turn off by --attemptclientmax)

Neither hcxdumptool nor hcxtools are designed to be used by beginners (README.md Requirements section):

Requirements
-------------
* Knowledge of radio technology.
* Knowledge of electromagnetic-wave engineering.
* Detailed knowledge of 802.11 protocol.
* Detailed knowledge of key derivation functions.
* Detailed knowledge of Linux.
* Detailed knowledge of filter procedures. (Berkeley Packet Filter, capture filter, display filter, etc.)

https://github.com/ZerBea/hcxdumptool/discussions/418

This knowledge is absolutely necessary to understand the additional options to control the transmission of single frames:

--disable_deauthentication: do not transmit DEAUTHENTICATION/DISASSOCIATION frames
--disable_proberequest    : do not transmit PROBEREQUEST frames
--disable_association     : do not AUTHENTICATE/ASSOCIATE
--disable_reassociation   : do not REASSOCIATE a CLIENT
--disable_beacon          : disable internal BEACON
                             default: one BEACON/second to wildcard SSID
--proberesponsetx=<digit> : transmit n PROBERESPONSEs from the ESSID ring buffer
                             default: 5
--essidlist=<file>        : initialize ESSID list with these ESSIDs

I've also added some information about the Berkeley Packet filter:

If you can't control the environment it is absolutely mandatory to set the [BPF](https://wiki.wireshark.org/CaptureFilters)!
The BPF can be used to select a target (or multible targets) or to protect devices.

This knowledge is also absolutely necessary to understand how to set a target or how to protect a device by BPF.

--bpfc=<filter>: compile Berkeley Packet Filter (BPF) and exit
                  $ hcxdumptool --bpfc="wlan addr3 112233445566" > filter.bpf
                  see man pcap-filter
--bpf=<file>   : input Berkeley Packet Filter (BPF) code (maximum 4096 instructions) in tcpdump decimal numbers format
                  see --help for more information

More information is here: https://github.com/ZerBea/hcxdumptool/discussions/420

Additional hcxdumptool print a warning if the BPF is unset.

BPF is unset! Make sure hcxdumptool is running in a 100% controlled environment!

[glibg10b]

This is perfect, thanks!

I'm well aware of BPFs, I just haven't had to time to learn how to write and use them.

While requiring knowledge about Linux and radio communcation is perfectly reasonable, I feel that beginners should be able to use hcxdumptool without knowledge of BPFs. These new commits give us idea of which attacks exist and how we can disable the noisiest attacks (without using --silent, which is overkill), so we can get familiar with hcxdumptool while we're learning BPFs without annoying our neighbours.

[ZerBea]

I agree, but neither hcxtools nor hcxdumptool nor hcxlabtool is designed to be used by beginners. It is absolutely mandatory to know 802.11. This is the entry level to hcxdumptool. It is mandatory to know which 802.11 frames are used to do an AUTHENTICATION followed by a 4 way handshake. With this knowledge (and only with this knowledge) you understand the options.

802.11 basic knowledge: Authentication: https://documentation.meraki.com/MR/Wi-Fi_Basics_and_Best_Practices/802.11_Association_Process_Explained 4way handshake: https://networklessons.com/cisco/ccnp-encor-350-401/wpa-and-wpa2-4-way-handshake

I don't want to reinvent the wheel. All this basic knowledge is well explained in www. A simple duckduckgo search will show this information: https://duckduckgo.com/?q=802.11+authentication&t=ffab&ia=web https://duckduckgo.com/?q=802.11+4way+handshake&t=ffab&ia=web

All the frames (mentioned above) are mandatory to get access to a WPA1/2/2kv3 network.

If you know this, it is easy to understand hcxdumptool's options and the explanation in -h is more than enough, e.g. --disable_association: --disable_association : do not AUTHENTICATE/ASSOCIATE The authentication and association is the first step to do a 4way handshake. If you disable it you will not get a PMKID!

hcxdumptool is an interactive tool that acts as a CLIENT (to request information from an AP like a PMKID) acts as an AP (to request information from a CLIENT) That is far more than injecting stupid deauthentication frames to get a 4way handshake.

That means, in all three attack vectors the frames which are transmitted are the same(!). Only the 802.11 address changes! https://howiwifi.com/2020/07/13/802-11-frame-types-and-formats/

Beside the options, hcxdumptool can be completely controlled by the BPF:

filter by addresses -> hcxdumptool dos not respond to addresses that are filtered out
filter by frame types -> hcxdumptool dos not respond to frames that are filtered out

[ZerBea]

BTW: You are referencing to an old version of hcxdumptool. I've removed several of the options you have mentioned above (a.g. silent).

[glibg10b]

I have a basic understanding of the 4-way handshake, including how the PTK is calculated and used. But it's hard to be motivated to get a comprehensive understanding of 802.11i when my end goal is just to use hcxdumptool. I am working on it by reading 802.11 Wireless Networks: The Definitive Guide, though, and I suspect that puts me far ahead of many users of this tool (mostly the Kali crowd).

The Pentoo repository where I got the package is using 6.2.7. Thanks to the simplicity of ebuilds in Gentoo, I was simply able to rename a local copy of hcxdumptool-6.2.7.ebuild to hcxdumptool-6.3.4.ebuild to get the newest release. I might make a PR there later.

[ZerBea]

6.2.7 is very old. It depend on deprecated Wireless Extensions (WEXT) Starting with wifi7 (on actual Linux kernels) the WEXT are completely deprecated. They have been replaced by NETLINK. If you run a kernel >= 6.3, dmesg should print a warning if a tool still uses WEXT! Starting with v6.3.0 hcxdumptool has followed and WEXT are removed in favor of NETLINK.

hcxdumptool is a little bit different to other tools: At first start we don't know what's going on on a channel, so, by default it request all available information. If a user don't want this, it is mandatory to disable this this:

attack a single target -> set BPF to filter the target
go stealth -> do not transmit DEAUTHENTICATION frames which can be detected
get PMKID -> connect to the target AP

This behavior (impact of a filter or an option) can always be monitored by tshark/Wireshark (if running in parallel with hcxdumptool).

[ZerBea]

You're well aware of BPF's, so it's easy to use hcxdumptool: get target information (BSSID and operating channel) set BPF to filter target BSSID (MAC addr 3) and broadcast mac run hcxdumptool: $ hcxdumptool -i INTERFACE --bpf=target.bpfc -w test.pcapng -c OPERATING_CHANNEL If the target AP is in range and supports PMKID caching, you'll get a PMKID If a CLIENT is connected to the target AP and both are in range you'll get a 4way handshake