Tutorial: MAC labelling

Introduction

The macRecorder plugin labels MAC addresses according to Manufacturer and Ethertypes. Since 0.8.9lmw2 the MAC manufacturer and ethertype protocol labelling is compiled into one file.

Preparation

First, restore T2 into a pristine state by removing all unnecessary or older plugins from the plugin folder ~/.tranalyzer/plugins and compile the following plugins:

$ t2build -e
Are you sure you want to empty the plugin folder '/home/wurst/.tranalyzer/plugins' (y/N)? y
Plugin folder emptied
$ t2build tranalyzer2 basicFlow tcpStates macRecorder txtSink
...
BUILD SUCCESSFUL

If you did not create a separate data and results directory yet, please do it now in another bash window, that facilitates your workflow:

$ mkdir ~/data ~/results
$

The anonymized sample PCAP used in this tutorial can be downloaded here: faf-exercise.pcap Please extract it under your data folder. Now you are all set for T2 MAC label experiments.

macRecorder plugin

Move to the macRecorder plugin and look into it

$ macRecorder
$ ls
autogen.sh  build  CMakeLists.txt  configure.ac  COPYING  default.config  doc   macEthlbl_HL.txt.bz2  Makefile.am  meson.build  src  t2plconf  tests  utils
$

The macEthlbl_HL.txt.bz2 contains the mac and ethertype label txt file, which will be converted to a compressed binary during compilation according the configuration in macRecorder.h. Let’s have a look at the main configuration file

$ cd src
$ ls
macLbl.c  macLbl.h  macRecorder.c  macRecorder.h  Makefile.am
$ vi macRecorder.h

The MR_MAC_FMT constant controls the output format of MAC addresses. In order to rapidly produce a rapid plot an integer or a hex number on the x-axis is better computable than the default ‘:’ notation. The MR_NPAIRS constant denotes whether MAC pairs are unique or not. The number of MAC pairs to be printed is defined by MR_MAX_MAC. MR_MACLBL controls the manufacturer/ethtype labeling.

As macRecorder was already emonstrated in the default configuration, set it here to long names 3 using t2conf, recompile the plugin with the -f option as the binary macEthlbl_HLP.bin file has to be rebuilt. Then run T2 on the pcap.

$ t2conf macRecorder -D MR_MACLBL=3 && t2build -f macRecorder
...
$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
================================================================================
Tranalyzer 0.8.14 (Anteater), Tarantula. PID: 54800
================================================================================
[INF] Creating flows for L2, IPv4, IPv6
Active plugins:
    01: basicFlow, 0.8.14
    02: macRecorder, 0.8.14
    03: tcpStates, 0.8.14
    04: txtSink, 0.8.14
[INF] IPv4 Ver: 5, Rev: 16122020, Range Mode: 0, subnet ranges loaded: 406105 (406.11 K)
[INF] IPv6 Ver: 5, Rev: 17122020, Range Mode: 0, subnet ranges loaded: 51345 (51.34 K)
[INF] macRecorder: 84110 (84.11 K) full org name records loaded
Processing file: /home/wurst/data/faf-exercise.pcap
...
$

The macRecorder notifies you that he loaded a number of records in a certain configuration. If this does not match your macRecorder config, then he will complain and demand a recompile with the -f option.

In the flow file you will notice that the srcMacLbl_dstMacLbl column now contains the full company name including the country of the manufacturer. If a protocol is detected no country is assigned.

$ head -n 10 faf-exercise_flows.txt | tcol
%dir  flowInd  flowStat            timeFirst          timeLast           duration  numHdrDesc  numHdrs  hdrDesc       srcMac             dstMac             ethType  ethVlanID  srcIP           srcIPCC  srcIPOrg                       srcPort  dstIP           dstIPCC  dstIPOrg                       dstPort  l4Proto  macStat  macPairs  srcMac_dstMac_numP                      srcMacLbl_dstMacLbl           tcpStatesAFlags
A     1        0x0400000000004000  1258544215.037210  1258544215.372742  0.335532  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1258     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_6   "Dell Inc,US"_"Apple Inc,US"  0x00
B     1        0x0400000000004001  1258544215.202900  1258544215.537951  0.335051  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1258     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_7   "Apple Inc,US"_"Dell Inc,US"  0x00
A     2        0x0400000000004000  1258544216.385370  1258544216.723144  0.337774  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1259     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   "Dell Inc,US"_"Apple Inc,US"  0x00
B     2        0x0400000000004001  1258544216.551313  1258544216.888595  0.337282  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1259     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   "Apple Inc,US"_"Dell Inc,US"  0x00
A     3        0x0400000000004000  1258544216.908284  1258544217.008468  0.100184  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1260     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_18  "Dell Inc,US"_"Apple Inc,US"  0x00
B     3        0x0400000000004001  1258544216.915576  1258544217.008019  0.092443  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              198.189.255.75  us       "California State University"  80       192.168.1.104   07       "Private network"              1260     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_73  "Apple Inc,US"_"Dell Inc,US"  0x00
A     4        0x0400000000004000  1258544217.003718  1258544217.348506  0.344788  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1261     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   "Dell Inc,US"_"Apple Inc,US"  0x00
B     4        0x0400000000004001  1258544217.169421  1258544217.513942  0.344521  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1261     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   "Apple Inc,US"_"Dell Inc,US"  0x00
A     5        0x0400000000004000  1258544217.349751  1258544217.413719  0.063968  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1262     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_9   "Dell Inc,US"_"Apple Inc,US"  0x00

The MAC labeling list resides in macRecorder/utils/macEthlbl_HL.txt. An extract of this file is shown below.

Similar to the IP subnet4/6HL files now ranges of MAC addresses can be labeled. The ranges can be non CIDR, the mask is currently redundant. It just denotes the MAC range, nevertheless, ranges can be non CIDR. The lower 4 octets code the ethType, normally 0000.

Protocols which code into MAC and ethertype can thus be searched in detail, as depicted for the CDP,VTP,STP, … case. The column bef fulfills a similar function as in the IP subnet file, except for the latter it denotes not only the end of a range but also a block of same MAC, but different ethertype.

$ macRecorder
$ vi macEthlbl_HL.txt
#macEType               mask    bef     shortCorp       corporation
0x0000000000000000      24      0       XEROXCORP,US    XEROX CORPORATION,US
0x000000FFFFFF0000      24      1       XEROXCORP,US    XEROX CORPORATION,US
0x0000010000000000      24      0       XEROXCORP,US    XEROX CORPORATION,US
0x000001FFFFFF0000      24      1       XEROXCORP,US    XEROX CORPORATION,US
0x0000020000000000      24      0       XEROXCORP,US    XEROX CORPORATION,US
0x000002FFFFFF0000      24      1       XEROXCORP,US    XEROX CORPORATION,US
...
0x0019E30000000000      24      0       AppleInc,US     Apple Inc,US
0x0019E3FFFFFF0000      24      1       AppleInc,US     Apple Inc,US
...
0x000BDB0000000000      24      0       DellInc,US      Dell Inc,US
0x000BDBFFFFFF0000      24      1       DellInc,US      Dell Inc,US
...
0xFCFFAA0000000000      24      0       IeeeRegis,US    Ieee Registration Authority,US
0xFCFFAAFFFFFF0000      24      1       IeeeRegis,US    Ieee Registration Authority,US
0x01000C0000000000      48      0       ISL     Inter Switch Link
0x01000CCCCCCC0104      48      0       PAgP    Port Aggregation Protocol
0x01000CCCCCCC0111      48      0       UDLD    Unidirectional Link Detection
0x01000CCCCCCC2000      48      0       CDP     Cisco Discovery Protocol
0x01000CCCCCCC2003      48      0       VTP     VLAN Trunk
0x01000CCCCCCC2004      48      0       DTP     Dynamic Trunk
0x01000CCCCCCD010B      48      0       PVSTP+  Per-Vlan Spanning Tree Protocol+
0x01000CCCCCCD0802      48      0       CSSTP   Cisco Shared Spanning Tree Protocol
0x01000CCDCDCD200A      48      0       STPUplink       STP Uplink Fast
0x01000CCDCDCE010C      48      0       VLANBridg       VLAN Bridge
0x01005e0000000000      24      0       IPv4Multi       IPv4-Multicast
0x01005effffff0000      24      1       IPv4Multi       IPv4-Multicast
...

As an admin you like to distinguish your machines even when DHCP is sometimes changing the IP per computer, or you like to ban certain HW from your network. E.g. you have special Apple or Intel computers you like to highlight in your flows in a human readable way. So define your own MAC labels.

Open your HL file and add the following records at the end. Make sure that the columns are separated by TABS!!

$ vi macEthlbl_HL.txt
...
0x0019E3E75D230000      48      0       Nudel,DE     Nudelfurtz @ Lab, Munich,DE
0x000BDB4F6B100000      48      0       Kacke,DE     Kacke @ Toilet, Government,DE

Close the file and recompile macRecorder using the -f option to produce a new macEthlbl_HLP.bin file. Then rerun T2 on the same pcap.

$ t2build -f macRecorder
...
$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
...
$

Open the flow file and you will see that the flows are now tagged with your text.

$ head -n 10 ~/data/faf-exercise_flows.txt | tcol
%dir  flowInd  flowStat            timeFirst          timeLast           duration  numHdrDesc  numHdrs  hdrDesc       srcMac             dstMac             ethType  ethVlanID  srcIP           srcIPCC  srcIPOrg                       srcPort  dstIP           dstIPCC  dstIPOrg                       dstPort  l4Proto  macStat  macPairs  srcMac_dstMac_numP                      srcMacLbl_dstMacLbl                                            tcpStates
A     1        0x0400000000004000  1258544215.037210  1258544215.372742  0.335532  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1258     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_6   "Kacke @ Toilet, Government,DE"_"Nudelfurtz @ Lab, Munich,DE"  0x00
B     1        0x0400000000004001  1258544215.202900  1258544215.537951  0.335051  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1258     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_7   "Nudelfurtz @ Lab, Munich,DE"_"Kacke @ Toilet, Government,DE"  0x00
A     2        0x0400000000004000  1258544216.385370  1258544216.723144  0.337774  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1259     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   "Kacke @ Toilet, Government,DE"_"Nudelfurtz @ Lab, Munich,DE"  0x00
B     2        0x0400000000004001  1258544216.551313  1258544216.888595  0.337282  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1259     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   "Nudelfurtz @ Lab, Munich,DE"_"Kacke @ Toilet, Government,DE"  0x00
A     3        0x0400000000004000  1258544216.908284  1258544217.008468  0.100184  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1260     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_18  "Kacke @ Toilet, Government,DE"_"Nudelfurtz @ Lab, Munich,DE"  0x00
B     3        0x0400000000004001  1258544216.915576  1258544217.008019  0.092443  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              198.189.255.75  us       "California State University"  80       192.168.1.104   07       "Private network"              1260     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_73  "Nudelfurtz @ Lab, Munich,DE"_"Kacke @ Toilet, Government,DE"  0x00
A     4        0x0400000000004000  1258544217.003718  1258544217.348506  0.344788  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1261     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   "Kacke @ Toilet, Government,DE"_"Nudelfurtz @ Lab, Munich,DE"  0x00
B     4        0x0400000000004001  1258544217.169421  1258544217.513942  0.344521  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1261     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   "Nudelfurtz @ Lab, Munich,DE"_"Kacke @ Toilet, Government,DE"  0x00
A     5        0x0400000000004000  1258544217.349751  1258544217.413719  0.063968  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1262     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_9   "Kacke @ Toilet, Government,DE"_"Nudelfurtz @ Lab, Munich,DE"  0x00

When you switch back to short names:

$ t2conf macRecorder -D MR_MACLBL=2 && t2build -f macRecorder
.
$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
...
$

You will see your short name definition:

$ head -n 10 ~/data/faf-exercise_flows.txt | tcol
%dir  flowInd  flowStat            timeFirst          timeLast           duration  numHdrDesc  numHdrs  hdrDesc       srcMac             dstMac             ethType  ethVlanID  srcIP           srcIPCC  srcIPOrg                       srcPort  dstIP           dstIPCC  dstIPOrg                       dstPort  l4Proto  macStat  macPairs  srcMac_dstMac_numP                      srcMacLbl_dstMacLbl  tcpStates
A     1        0x0400000000004000  1258544215.037210  1258544215.372742  0.335532  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1258     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_6   Kacke,DE_Nudel,DE    0x00
B     1        0x0400000000004001  1258544215.202900  1258544215.537951  0.335051  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1258     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_7   Nudel,DE_Kacke,DE    0x00
A     2        0x0400000000004000  1258544216.385370  1258544216.723144  0.337774  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1259     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   Kacke,DE_Nudel,DE    0x00
B     2        0x0400000000004001  1258544216.551313  1258544216.888595  0.337282  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1259     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   Nudel,DE_Kacke,DE    0x00
A     3        0x0400000000004000  1258544216.908284  1258544217.008468  0.100184  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1260     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_18  Kacke,DE_Nudel,DE    0x00
B     3        0x0400000000004001  1258544216.915576  1258544217.008019  0.092443  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              198.189.255.75  us       "California State University"  80       192.168.1.104   07       "Private network"              1260     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_73  Nudel,DE_Kacke,DE    0x00
A     4        0x0400000000004000  1258544217.003718  1258544217.348506  0.344788  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1261     77.67.44.206    gb       "Akamai Technologies"          80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_5   Kacke,DE_Nudel,DE    0x00
B     4        0x0400000000004001  1258544217.169421  1258544217.513942  0.344521  1           3        eth:ipv4:tcp  00:19:e3:e7:5d:23  00:0b:db:4f:6b:10  0x0800              77.67.44.206    gb       "Akamai Technologies"          80       192.168.1.104   07       "Private network"              1261     6        0x00     1         00:19:e3:e7:5d:23_00:0b:db:4f:6b:10_4   Nudel,DE_Kacke,DE    0x00
A     5        0x0400000000004000  1258544217.349751  1258544217.413719  0.063968  1           3        eth:ipv4:tcp  00:0b:db:4f:6b:10  00:19:e3:e7:5d:23  0x0800              192.168.1.104   07       "Private network"              1262     198.189.255.75  us       "California State University"  80       6        0x00     1         00:0b:db:4f:6b:10_00:19:e3:e7:5d:23_9   Kacke,DE_Nudel,DE    0x00

If you want to change the length of the short and long names in the .bin file open the src/macLbl.h which contains the definition from where to read the binary mac label file and the maximal length of the label.

$ vi src/macLbl.h

As an exercise set MR_MACLBL=1 to numerical output, recompile, rerun T2 and look at the result in flow file. The index corresponds to the line number in macEthlbl_HLP.txt.

Otherwise don’t forget to restore the default macEthLbl_HLP files, if you don’t want to keep your changes, other wise move it to another name. Reset MR_MACLBL=2 and recompile with t2build -f:

$ macRecorder
$ rm macEthlbl_HL.txt
$ t2conf macRecorder -D MR_MACLBL=2 && t2build -f macRecoder
..
$

Have fun!