Addition of example.md

[Jake-Grafton]

This commit contains a new document that showcases an example attack on a test AP that I own.

[ZerBea]

Looking good so far, thanks.

But the usage of the BPF is misleading.

This are simple BPF's

Target: 00c0cab035be
simple BPF to attack this target: "wlan addr3 00c0cab035be"
simple BPF to protect this target: "not wlan addr3 00c0cab035be"

This is a an advanced BPF, because it allows hcxdumptool to interact on BROADCAST MACs.
advanced BPF to attack this target and to allow to handle BROADCAST frames: "wlan addr3 00c0cab035be or wlan addr3 ffffffffffff"

While this BPF is useless:

The full command to create a BPF to _protect_ 00c0cab035be would be as follows:
hcxdumptool --bpfc="not wlan addr3 00c0cab035be or wlan addr3 ffffffffffff" >> protect.bpf

"not wlan addr3 00c0cab035be" == this MAC will be filtered out and all other MACs are allowed - that include the BROADCAST MAC ffffffffffff - so, no need to add "or wlan addr3 ffffffffffff"

Please note:
hcxdumptool use BLOCK ACK frames to detect connected CLIENTs. This frames do not have an addr3.
Using this attack filter "wlan addr3 00c0cab035be" they are filtered out.
To include them to an attack filter: "wlan addr1 00c0cab035be or wlan addr2 00c0cab035be or wlan addr3 00c0cab035be"

Not merged because usage of the BPF is misleading.

BTW:
The filters mentioned above are very basic examples.
To code complex filters, it is mandatory to understand them:
https://www.scribbr.com/working-with-sources/boolean-operators/

[Jake-Grafton]

Ok, I understand. I'll change the content so it is actually correct.
I'm slightly confused as the output of hcxdumptool --help and hcxdumptool -h do not mention wlan addr 1, wlan addr 2, or wlan addr 3.
Do you want me to update the hcxdumptool --help/-h so it'll include wlan addr 1-3 or do you want to do that?

[ZerBea]

Great. After the change I'll merge it.

I'm slightly confused as the output of hcxdumptool --help and hcxdumptool -h do not mention wlan addr 1, wlan addr 2, or wlan addr 3.

As your documentation include a basic example, the help menu of hcxdumptool only contain a basic example too. Everything else would blow it up.

To code advanced filters, it is absolutely mandatory to understand 802.11 and Bolean Operators.
This is mentioned in README.md requirements section;
- Detailed knowledge of 802.11 protocol.

[ZerBea]

https://networkengineering.stackexchange.com/questions/25100/four-layer-2-addresses-in-802-11-frame-header

[ZerBea]

Some tools use command line options to filter a BSSID (--bssid=11:22:33:44:55:66).
That's not really flexible.
hcxdumptool allows to apply a BPF. That is extreme fast (running in kernel space) and allows to filter nearly everything (by MACs on addr1, 2, 3, 4 as well as frames by types or by content) - without changing hcxdumptools source code!

This is the royal class as tshark, Wireshark and tcpdump do it.

[Jake-Grafton]

@ZerBea
The requested changes have been made. :)

[ZerBea]

Now its fine. Thanks. Merged.

[Jake-Grafton]

@ZerBea
I just tried to use hcxdumptool --bpfc="not wlan addr 3 112233445566" (112233445566 is a placeholder MAC) and hcxdumptool threw an error stating that it couldn't compile the BPF.
Ex:

~ $ hcxdumptool --bpfc="not wlan addr 3 e45f0166cd50"
failed to compile BPF

Using hcxdumptool --bpfc="not wlan addr3 112233445566", I get a compiled BPF.

[ZerBea]

BTW:
I've added "Detailed knowledge of Bolean Operators" to requirements section of README.md.

Correct is "wlan addx" and not "wlan addr x" - that was an ugly copy and paste error.

[Jake-Grafton]

I'll open another pull request with fixed BPF syntax. Gimme a few.