Tutorial: Plugin summary files

When all data is processed or T2 is interrupted by ^C or a signal, then the end report is printed. At the same time certain global information can be printed by your plugin. Before we start doing this, clean out your plugin .so directory if this is the first tutorial you follow. Then all unnecessary plugins should be deleted from the plugin folder ~/.tranalyzer/plugins and compile the core and basicFlow.

$ 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

I prepared a plugin which we will discuss in the following: tcpWinSD Copy it to the plugins folder of your t2 installation and unpack it:

$ cd tranayzer2-0.8.9/plugins
$ tar -xf tcpWinSD.tar.gz
$ source ../scripts/t2_aliases

The anonymized sample pcap can be downloaded here: annoloc2.pcap. Please extract it under your data folder: ~/data, if you haven’t already. Now you are all set for summary file programming.

Summary files

Every plugin can produce a summary of traffic content. Let’s generate a file which lists all IPs with their maximal winThCnts, so we could find the IP having the largest L4 trouble. In order to do so, we first of all need to define all necessary variables being global to the plugin.

So move to the tcpWinSD plugin and open tcpWinSD.c

$ source 
$ tcpWinSD
$ vi src/tcpWin.c

In order to produce just summary files no flowTermination callback is needed, you can do everything in a packet callback, but that is inefficient, as you go over the code in every packet. If it is possible, it is always good practice to move heavy processing to flowGeneration/Termination, as it is only called once per flow.

For the matter of simplicity we just have arrays and a global index as defined in the global section of the plugin.

Now go to the onFlowTerminate(...) callback. First we need the pointer to the flow structure. To show the principal we just do a linear search whether we already have the IP stored and check whether its counter is greater than the potential existing, then we store the new data. Yes, it can be more elegant, using a hash or a tree. We will discuss T2 support for that matter in tutorial block t2kunfu. Note that the following code is only for IPv4, as we want to start simple.

The onApplicationTerminate() callback not only serves to free flow memory but also to produce all kinds of global output into specialized files. The code below stores the IP and its count. Just add it after the free(...) command.

Now open tcpWin.h and add the maximal size of the global IP/window size count array and the appendix of the global file. Just add the lines marked by <-- (including the typedef gwz_t)

So you are all set. Note that we only select flows which contain more than 50 packets, to avoid small flow clutter. Compile and run t2:

$ t2build tcpWinSD
$ t2 -r ~/data/annoloc2.pcap -w ~/results
Number of processed   flows: 17086 (17.09 K)
Number of processed A flows: 9704 (9.70 K) [56.80%]
Number of processed B flows: 7382 (7.38 K) [43.20%]
Number of request     flows: 9661 (9.66 K) [56.54%]
Number of reply       flows: 7425 (7.42 K) [43.46%]
Total   A/B    flow asymmetry: 0.14
Total req/rply flow asymmetry: 0.13
Number of processed   packets/flows: 71.35
Number of processed A packets/flows: 58.14
Number of processed B packets/flows: 88.70
Number of processed total packets/s: 48859.83 (48.86 K)
Number of processed A+B   packets/s: 48859.83 (48.86 K)
Number of processed A     packets/s: 22615.01 (22.61 K)
Number of processed   B   packets/s: 26244.82 (26.24 K)

Open your results cmd window and look at what t2 produced

$ ls

So only the *_tcpwin.txt* file contains the summary of all IP and their counts being below the winSZ threshold. If you are interested in the IP with the worst connection sort the tcpwin file according to the 3rd column.

$ tawk -s '#' 't2sort(winRelThCnt)' annoloc2_tcpwin.txt
# IP	pktTcpCnt	winRelThCnt	72	1.000000	79	0.962025	429	0.489510	52	0.269231	251	0.247012	195	0.246154	205	0.229268	162	0.203704	315	0.196825	388	0.164948	95	0.157895	140	0.150000	197	0.142132	235	0.140426	194	0.123711	78	0.115385	74	0.094595	131	0.045802	340	0.041176	847	0.035419	133	0.030075	87	0.022989	111	0.018018	365	0.016438	62	0.016129	250	0.016000	72	0.013889	73	0.013699	843	0.011862	92	0.010870	2079	0.009620	114	0.008772	133	0.007519	957	0.005225	244	0.004098	249	0.004016	719	0.002782	415	0.002410	977	0.002047	538	0.001859	1081	0.001850	618	0.001618	670	0.001493	1134	0.000882	1332	0.000751	2309	0.000433

So in all packets the host asked the opposite IP to stop sending packets. If you increase CPWIN_MINPKTS what will happen?

Then add the destination address, does that change much? Look at the flow asymmetry. Why not improve the measure by adding the TCP WS option. These are your jobs now. Let yourself be inspired by the tcpFlags plugin of T2.

Have fun writing plugins!

The next tutorial will teach you geo-whois-labeling

See Also