to improve the usability

[v74863]

Hi ZerBea

Let me suggest two ideas to improve the usability of hcxdumptool.

I think it would be nice:
to create an FAQ (Frequently Asked Questions) on hcxdumptool
(instead of answering the same questions over and over again)

to split the built-in help into two parts
-h brief help with most common options and examples of typical attacks
--help full help

With best wishes,
V.

[ZerBea]

That is a good idea and it can be added easily:

to split the built-in help into two parts
-h brief help with most common options and examples of typical attacks
--help full help

But that:

...to create an FAQ (Frequently Asked Questions) on hcxdumptool
(instead of answering the same questions over and over again)

will not work:
I opened discussions -> but I get the same issue reports over and over
The same applies to README.md and changelog -> it looks like only a few users read it

But I give it a try (discussions) too - same procedure like the driver tests in discussions.

[ZerBea]

Let's see if it is working as expected
#368 (comment)

[v74863]

Vielen Dank for the quick response.

One more idea:
to prevent numerous questions why the old-style options don't work with the newest hcxdumptool
you can detect these options and then output to the screen something like this:
"The options you specified are no longer supported in hcxdumptool.
Please see below."
Then you can display a brief help with usage examples.

[ZerBea]

I'm not sure, because the option list is already long:

#define HCX_BPF				1
#define HCX_DISABLE_DEAUTHENTICATION	2
#define HCX_DISABLE_PROBEREQUEST	3
#define HCX_DISABLE_ASSOCIATION		4
#define HCX_DISABLE_REASSOCIATION	5
#define HCX_BEACONTX_MAX		6
#define HCX_PROBERESPONSETX_MAX		7
#define HCX_GPIO_BUTTON			8
#define HCX_GPIO_STATUSLED		9
#define HCX_TOT				10
#define HCX_ERROR_MAX			11
#define HCX_WATCHDOG_MAX		12
#define HCX_ATTEMPT_CLIENT_MAX		13
#define HCX_ATTEMPT_AP_MAX		14
#define HCX_ON_SIGTERM			15
#define HCX_ON_TOT			16
#define HCX_ON_GPIOBUTTON		17
#define HCX_ON_WATCHDOG			18
#define HCX_EXIT_ON_EAPOL		19
#define HCX_ON_ERROR			20
#define HCX_ESSIDLIST			21
#define HCX_NMEA0183			22
#define HCX_GPSD			23
#define HCX_NMEA0183_OUT		24
#define HCX_NMEA0183_PCAPNG		25
#define HCX_RCASCAN			26
#define HCX_RD_SORT			27
#define HCX_IFNAME			'i'
#define HCX_PCAPNGNAME			'w'
#define HCX_INTERFACE_INFO		'I'
#define HCX_SET_MONITORMODE		'm'
#define HCX_SET_MONITORMODE_PASSIVE	'p'
#define HCX_SET_SCANLIST_FROM_USER_CH	'c'
#define HCX_SET_SCANLIST_FROM_USER_FREQ	'f'
#define HCX_SET_SCANLIST_FROM_INTERFACE	'F'
#define HCX_SHOW_INTERFACE_LIST		'L'
#define HCX_SHOW_INTERFACE_LIST_SHORT	'l'
#define HCX_HOLD_TIME			't'
#define HCX_HELP			'h'
#define HCX_VERSION			'v'

[v74863]

I think the brief help should be just a clear concise example of an attack that an average user can perform.
For example,

hcxdumptool -h

hcxdumptool 6.3.2 (C) 2023 ZeroBeat

  Let's say

222222222222 : MAC address of your target Access Point
1a           : channel of your target AP
wlan1        : name of INTERFACE to be used
dump.pcapng  : name of file to which packets are written
5 minutes    : duration of attack


  To attack this single AP, enter the commands

sudo hcxdumptool -m wlan1
sudo tcpdump -i wlan1 wlan addr1 222222222222 or wlan addr2 222222222222 or wlan addr3 222222222222 -ddd > attack.bpf
sudo hcxdumptool -i wlan1 -w dump.pcapng -c 1a --bpf=attack.bpf --tot=5


  To show additional help, enter

hcxdumptool --help


Welcome to https://github.com/ZerBea/hcxdumptool/discussions

[ZerBea]

That's going a little too far for me.
The simple help (-h) print an overview of all available (less or more common) options. That include a short explanation of what this option does.
The expanded help (--help) print an initial trouble shooting and some warnings.

This tools are aimed to experienced users. A user who really need such a detailed help will e.g. never understand a Berkeley Packet Filter or the 4way handshake (inclusive its EAPOL TIME OUT TIMERs or hashccat's NONCE ERROR CORRECTIONS (in case of a packet loss). Adding all this to a help menu will be a bottomless pit.
A real world example is here:
#375

Reading and understanding hcxdumptool's help menu should be the initial obstacle for a user to enter the royal class of penetrating a wireless network: https://www.cyberark.com/resources/threat-research-blog/cracking-wifi-at-scale-with-one-simple-trick
Understanding Linux and 802.11 is the first approach to dealing with Linux and 802.11 basics.

[v74863]

Let's look at it from a different angle.
All the real examples so far have happened with the traditional version of help.
Treat my version as a highly experimental.
We're open-minded, aren't we?
Give it a chance, ask people's opinion of it.
Of course, we all know that
Anything that can go wrong, will go wrong.
Anything that can be misinterpreted will be misinterpreted.
etc.

[ZerBea]

Partly already done, by latest commits:

$ hcxdumptool --help
Additional information:
-----------------------
get information about running services that have access to the device:
 $ sudo systemctl --type=service --state=running
stop all services that have access to the interface, e.g.:
 $ sudo systemctl stop NetworkManager.service
 $ sudo systemctl stop wpa_supplicant.service
run hcxdumptool
 $ hcxdumptool -i INTERFACENAME -w dumpfile.pcapng -F --rds=1
  i     : name of the interface to be used
  w     : name of file to which packets are written
  F     : use all available channels
  rds=1 : sort real time display by status (last PMKID/EAPOL on top)
press ctrl+c to terminate
press GPIO button to terminate
 hardware modification is necessary, read more:
 https://github.com/ZerBea/hcxdumptool/tree/master/docs
to store entire traffic, run <tshark -i <interface> -w allframes.pcapng> in parallel on the same interface
Important:
do not set monitor mode by third party tools (iwconfig, iw, airmon-ng)
do not use virtual interfaces (monx, wlanxmon, prismx, ...) created by airmon-ng and iw
do not use virtual machines or emulators
do not run other tools that take access to the interface in parallel (except: tshark, wireshark, tcpdump)
do not use tools to change MAC (like macchanger)
do not merge (pcapng) dump files, because this destroys assigned hash values!

To get a short overview == -h
Troubleshooting == --help

For most cases, this command line is more than enough:
$ hcxdumptool -i INTERFACENAME -w dumpfile.pcapng -F --rds=1
Even the simplest command line should do it:
$ hcxdumptool
Any other case requires appropriate expertise.

BTW:
I love Murphy's law - because it's always true.

[ZerBea]

BTW:
$ sudo tcpdump -i wlan1 wlan addr1 222222222222 or wlan addr2 222222222222 or wlan addr3 222222222222 -ddd > attack.bpf
This is just a theoretical example that we usually have three useful MAC addresses we can filter (to, from, BSSID - addr4 is not mandatory for most of the cases).
In reality, if the target is a single AP, it would look like this:
$ sudo tcpdump -i wlan1 wlan addr3 111111111111 or wlan addr3 ffffffffffff -ddd > attack.bpf
Because only one (addr3: BSSID) is makes sense in that special case. That include the BROADCAST MAC to get PSKs transmitted in the clear by the CLIENT.
And I can show you 20 or more different examples do perform exactly the same filter operation.

I'll say that none of this tools is addressed to be used by beginners. And experienced users know which options / combination of options should be used.
That is mentioned in README.md:
You might expect me to recommend that everyone should be using hcxdumptool/hcxtools. But the fact of the matter is, however, that hcxdumptool/hcxtools is NOT recommended to be used by unexperienced users or newbees.
If you are not familiar with Linux generally or if you do not have at least a basic level of knowledge as mentioned in section "Requirements", hcxdumptool/hcxtools is probably not what you are looking for.
However, if you have that knowledge hcxdumptool/hcxtools can do magic.

An expanded help would be like a twenty-part (or much more) encyclopedia.
The best help will fail if you don't know 802.11, Linux or the basics of Berkeley Packet Filter methods.