Advanced Berkeley Packet Filters (BPF)

[ZerBea]

As described in earlier comments, the BPF is the most powerful (and fast) filter that "lives" in the Linux kernel.
It is possible to filter nearly everything by advanced filter code.

I started this discussion to publish some advanced BPF solutions here.

A MAC address (six bytes) consists of two parts, the OUI (first three bytes) and the NIC (last three bytes).
Sometimes you need to filter by OUI instead of the entire MAC address.

Here is an example how to filter wlan addr3 by OUI:
entire MAC ADDRESS: 112233445566
OUI: 112233
NIC: 445566
$ hcxdumptool --bpfc="wlan[16:2] == 0x1122 && wlan[18:1] == 0x33" > attack_oui.bpf

Here is an example how to filter wlan addr2 by OUI:
entire MAC ADDRESS: 112233445566
OUI: 112233
NIC: 445566
$ hcxdumptool --bpfc="wlan[10:2] == 0x1122 && wlan[12:1] == 0x33" > attack_oui.bpf

Here is an example how to filter wlan addr1 by OUI:
entire MAC ADDRESS: 112233445566
OUI: 112233
NIC: 445566
$ hcxdumptool --bpfc="wlan[4:2] == 0x1122 && wlan[6:1] == 0x33" > attack_oui.bpf

Beside hcxdumptool/hcxlabtool all this filters can be tested on the fly by tshark:

$ hcxdumptool -m INTERFACE_NAME -c 1a
$ tshark -i INTERFACE_NAME "wlan[16:2] == 0x1122 && wlan[18:1] == 0x33"

To monitor the filter on the fly it is possible to run hcxdumptool/hcxlabtool and tshark on the same interface:
open 2 terminals

in terminal 1
build BPF
$ hcxdumptool --bpfc="wlan[16:2] == 0x1122 && wlan[18:1] == 0x33" > attack_oui.bpf
run the attack
$ sudo hcxdumptool -i INTERFACE_NAME --bpf=attack_oui.bpf --rds=1

in terminal 2
run tshark to monitor the filter on the fly:
$ tshark -i INTERFACE_NAME -f "wlan[16:2] == 0x1122 && wlan[18:1] == 0x33"
or
store the entire filtered traffic to additional pcapng file:
$ tshark -i INTERFACE_NAME -f "wlan[16:2] == 0x1122 && wlan[18:1] == 0x33"

[ZerBea]

Here is an example how to filter target AP by wlan addr3 and to allow all PROBEREQUEST frames (directed and undirected) from CLIENTs:
MAC target AP: 112233445566
$ hcxdumptool --bpfc="wlan addr3 112233445566 || (wlan type mgt && subtype probe-req)" > attack_allow_pr.bpf

[ZerBea]

Here is an example how to filter out packets greater than n bytes.
$ hcxdumptool --bpfc="len <= 1024" > filter1024.bpf
We can set the filter to <= 1024 bytes, because this length include all mandatory packets required by hcxpcapngtool to convert the dump file to a hc22000 file.
That prevents that oversized or for the conversion process not needed packets reach the main packet loop of hcxdumptool.
As all filters before, this filter can be combined with other filter options.

[ZerBea]

No, that doesn't work.
Correct BPF is:
! type ctl subtype ack && ! type ctl subtype cts && len <= 1024

Please run your filter code and mine on the fly via tshark and you'll know what I mean.
$ sudo hcxdumptool -m INTERFACE_NAME -c crowded channel, e.g. 6a

My BPF == output as expected:
$ tshark -i INTERFACE_NAME -f "! type ctl subtype ack && ! type ctl subtype cts && len <= 1024"

Your BPF == nothing happens
$ tshark -i INTERFACE_NAME -f "len <= 1024 && ! type ctl subtype ack && ! type ctl subtype cts"

Is it possible to combine the filter code? Yes, but the rules must be followed. Unfortunately, some are not logical as tshark on the fly shows.

[strasharo]

Thanks for the clarification, indeed my interpretation gets no packets at all.

[ZerBea]

This is an example only. There is no need to set packet length, because it is hard coded to a snaplen of 1024 bytes due to performance reasons.
All packets that are not mandatory to recover the PSK are disregarded (e.g we don't want oversized data packets to be processed by hcxdumptools/hcxlabtools main packet loop.

[strasharo]

Ah, got it. So is it good to have ACK and CTS filter included by default in my filter for added performance?

[ZerBea]

ACK and CTS frames are not needed and they can be filterd out by BPF. This increase performance.

[ZerBea]

Here is an example how to filter unwanted ACK and CTS frames:
$ hcxdumptool --bpfc="! type ctl subtype ack && ! type ctl subtype cts" > filterackcts.bpf
That prevents that thousands of this control packets reach the main packet loop of hcxdumptool.
As all filters before, this filter can be combined with other filter options.

[ZerBea]

Starting with this commit I added a new option to hcxlabtool:

--bpfd=<mode>    : set output mode for compiled Berkeley Packet Filter (BPF)
                    default = 0
                    0 = compile BPF code as decimal numbers (readable by --bpf)
                    1 = compile BPF code as decimal numbers preceded with a count (readable by --bpf)
                    2 = compile BPF code as a C program fragment (readable by --bpf)
                    3 = compile BPF code as a ASM program
                    4 = compile BPF code as bpf_debug style
                    see man pcap-filter

This increase the compatibility with Linux BPF tools, bcc, bcc-tools and more.

The new option in detail:
This is the default output in hcxlabtool/hcxdumptool style

$ hcxlabtool --bpfc="wlan addr3 112233445566" --bpfd=0
48 0 0 3
100 0 0 8
7 0 0 0
48 0 0 2
76 0 0 0
2 0 0 0
7 0 0 0
80 0 0 0
84 0 0 12
21 5 0 4
64 0 0 18
21 0 3 860116326
72 0 0 16
21 0 1 4386
6 0 0 1024
6 0 0 0

This is the output in tcpdump style.

$ hcxlabtool --bpfc="wlan addr3 112233445566" --bpfd=1
16
48 0 0 3
100 0 0 8
7 0 0 0
48 0 0 2
76 0 0 0
2 0 0 0
7 0 0 0
80 0 0 0
84 0 0 12
21 5 0 4
64 0 0 18
21 0 3 860116326
72 0 0 16
21 0 1 4386
6 0 0 1024
6 0 0 0

This is C style and can be directly added to own C projects:

$ hcxlabtool --bpfc="wlan addr3 112233445566" --bpfd=2
{ 0x30, 0, 0, 0x00000003 },
{ 0x64, 0, 0, 0x00000008 },
{ 0x7, 0, 0, 0x00000000 },
{ 0x30, 0, 0, 0x00000002 },
{ 0x4c, 0, 0, 0x00000000 },
{ 0x2, 0, 0, 0x00000000 },
{ 0x7, 0, 0, 0x00000000 },
{ 0x50, 0, 0, 0x00000000 },
{ 0x54, 0, 0, 0x0000000c },
{ 0x15, 5, 0, 0x00000004 },
{ 0x40, 0, 0, 0x00000012 },
{ 0x15, 0, 3, 0x33445566 },
{ 0x48, 0, 0, 0x00000010 },
{ 0x15, 0, 1, 0x00001122 },
{ 0x6, 0, 0, 0x00000400 },
{ 0x6, 0, 0, 0x00000000 },

An example how to use that code is here:
https://www.kernel.org/doc/html/latest/networking/filter.html

This is ASM style (useful for debug purpose):

$ hcxlabtool --bpfc="wlan addr3 112233445566" --bpfd=3
(000) ldb      [3]
(001) lsh      #8
(002) tax      
(003) ldb      [2]
(004) or       x
(005) st       M[0]
(006) tax      
(007) ldb      [x + 0]
(008) and      #0xc
(009) jeq      #0x4             jt 15	jf 10
(010) ld       [x + 18]
(011) jeq      #0x33445566      jt 12	jf 15
(012) ldh      [x + 16]
(013) jeq      #0x1122          jt 14	jf 15
(014) ret      #1024
(015) ret      #0

This is bpf_dbg style. The code can be inserted directly into debugger:

$ hcxlabtool --bpfc="wlan addr3 112233445566" --bpfd=4
16,48 0 0 3,100 0 0 8,7 0 0 0,48 0 0 2,76 0 0 0,2 0 0 0,7 0 0 0,80 0 0 0,84 0 0 12,21 5 0 4,64 0 0 18,21 0 3 860116326,72 0 0 16,21 0 1 4386,6 0 0 1024,6 0 0 0

$ bpf_dbg
> load bpf 16,48 0 0 3,100 0 0 8,7 0 0 0,48 0 0 2,76 0 0 0,2 0 0 0,7 0 0 0,80 0 0 0,84 0 0 12,21 5 0 4,64 0 0 18,21 0 3 860116326,72 0 0 16,21 0 1 4386,6 0 0 1024,6 0 0 0

> dump
/* { op, jt, jf, k }, */
{ 0x30,  0,  0, 0x00000003 },
{ 0x64,  0,  0, 0x00000008 },
{ 0x07,  0,  0, 0000000000 },
{ 0x30,  0,  0, 0x00000002 },
{ 0x4c,  0,  0, 0000000000 },
{ 0x02,  0,  0, 0000000000 },
{ 0x07,  0,  0, 0000000000 },
{ 0x50,  0,  0, 0000000000 },
{ 0x54,  0,  0, 0x0000000c },
{ 0x15,  5,  0, 0x00000004 },
{ 0x40,  0,  0, 0x00000012 },
{ 0x15,  0,  3, 0x33445566 },
{ 0x48,  0,  0, 0x00000010 },
{ 0x15,  0,  1, 0x00001122 },
{ 0x06,  0,  0, 0x00000400 },
{ 0x06,  0,  0, 0000000000 },

> disassemble
l0:	ldb [3]
l1:	lsh #8
l2:	tax 
l3:	ldb [2]
l4:	or x
l5:	st M[0]
l6:	tax 
l7:	ldb [x+0]
l8:	and #0xc
l9:	jeq #0x4, l15, l10
l10:	ld [x+18]
l11:	jeq #0x33445566, l12, l15
l12:	ldh [x+16]
l13:	jeq #0x1122, l14, l15
l14:	ret #0x400
l15:	ret #0

This is a powerful instrument to identify problems inside your BPF.
More options (e.g. set break point, run on dump file), are here:
https://www.kernel.org/doc/html/latest/networking/filter.html

Option 2, option 3 and option 4 are "royal class" and definitely nothing for newbies.
Don't ask me to explain them, because it would fill entire books. This is far out of scope of a discussion section!
But if you're interested in learning BPF coding, this is a good starting point:
https://www.kernel.org/doc/html/latest/bpf/index.html