Tutorial: Plugin end report

When all data is processed or T2 is interrupted by ^C or a signal, then the end report is printed. 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. We do not need flow output, so no SinkPlugin is needed.

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

Compiling the basicFlow took now a bit longer, because t2 had to rebuild the subnetfiles for geolocation. ‘t2build -e’ also removes the subnetfile. You can also use a rm, which does not remove the old subnetfile:

$ rm ~/.tranalyzer/plugins/*.so
$ t2build tranalyzer2

Then the compilation will be considerable faster, as the subnetfile already exists.

If you didn’t read the tutorials before, here is the basis plugin which we will extend: tcpWin

The annonymized sample pcap can be downloaded here: annoloc2.pcap. Please extract it under your data folder, if you not already have. Now you are all set for end report programming.

Implementing the end report

If your plugin wants to contribute to the end report, then global variables and a pluginReport callback have to be added. So open tcpWin.c in an editor and add two global variables after the tcpWinFlows definition. Look for the <– markers.

Then add Then add in the onFlowTerminate callback the lines marked by <– to aggregate stat and winThCnt of all flows.

Now add the plugin callback e.g. at the end of the file. There we print the status and the aggregated winThCnt. Note, that the core can be configured to display hex numbers small or captial. To be consistent with that option, you should use the B2T_PRIX instead of the normal PRIx8 or %02x constant. So you do not need to worry about these nitty gritty things anymore. Important for you in the function T2_FPLOG is the name of your plugin: tcpWin, so you can identify your ouptut in the end report, then the C format of your output, and the variables, actually like a normal printf.

Recompile tcpWin and execute T2

$ t2build tcpWin
...
$ t2 -r ~/data/annoloc2.pcap
================================================================================
Tranalyzer 0.8.2 (Anteater), Tarantula. PID: 30750
================================================================================
[INF] Creating flows for L2, IPv4, IPv6
Active plugins:
    01: tcpWin, 0.8.2
Processing file: /home/wurst/data/annoloc2.pcap
Link layer type: Ethernet [EN10MB/1]
Dump start: 1022171701.691172 sec (Thu 23 May 2002 16:35:01 GMT)
[WRN] snapL2Length: 54 - snapL3Length: 40 - IP length in header: 1500
Dump stop : 1022171726.640398 sec (Thu 23 May 2002 16:35:26 GMT)
Total dump duration: 24.949226 sec
Finished processing. Elapsed time: 0.445618 sec
Finished unloading flow memory. Time: 0.450443 sec
Percentage completed: 100.00%
Number of processed packets: 1219015 (1.22 M)
Number of processed bytes: 64082726 (64.08 M)
Number of raw bytes: 844642686 (844.64 M)
Number of pcap bytes: 83586990 (83.59 M)
Number of IPv4 packets: 1218588 (1.22 M) [99.96%]
Number of IPv6 packets: 180 [0.01%]
Number of A packets: 564228 (564.23 K) [46.29%]
Number of B packets: 654787 (654.79 K) [53.71%]
Number of A bytes: 29447896 (29.45 M) [45.95%]
Number of B bytes: 34634830 (34.63 M) [54.05%]
Average A packet load: 52.19
Average B packet load: 52.89
--------------------------------------------------------------------------------
tcpWin: Aggregated status flags: 0x01
tcpWin: Number of tcp winsize packets below threshold 1: 2415 [0.25%]
--------------------------------------------------------------------------------
Headers count: min: 2, max: 4, average: 3.01
Number of GRE packets: 20 [0.00%]
Number of IGMP packets: 12 [0.00%]
Number of ICMP packets: 3059 (3.06 K) [0.25%]
Number of ICMPv6 packets: 11 [0.00%]
Number of TCP packets: 948743 (948.74 K) [77.83%]
Number of UDP packets: 266900 (266.90 K) [21.89%]
Number of IPv4 fragmented packets: 2284 (2.28 K) [0.19%]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Number of processed   flows: 17102 (17.10 K)
Number of processed A flows: 9721 (9.72 K) [56.84%]
Number of processed B flows: 7381 (7.38 K) [43.16%]
Number of request     flows: 9678 (9.68 K) [56.59%]
Number of reply       flows: 7424 (7.42 K) [43.41%]
Total   A/B    flow asymmetry: 0.14
Total req/rply flow asymmetry: 0.13
Number of processed   packets/flows: 71.28
Number of processed A packets/flows: 58.04
Number of processed B packets/flows: 88.71
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.05 (22.61 K)
Number of processed   B packets/s: 26244.78 (26.24 K)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Number of average processed flows/s: 685.47
Average full raw bandwidth: 270835712 b/s (270.84 Mb/s)
Average snapped bandwidth : 20548206 b/s (20.55 Mb/s)
Average full bandwidth : 270445248 b/s (270.45 Mb/s)
Max number of flows in memory: 17102 (17.10 K) [6.52%]
Memory usage: 0.02 GB [0.03%]
Aggregate flow status: 0x000018fa0202d044
[WRN] L3 SnapLength < Length in IP header
[WRN] L4 header snapped
[WRN] Consecutive duplicate IP ID
[WRN] IPv4/6 fragmentation header packet missing
[WRN] IPv4/6 packet fragmentation sequence not finished
[INF] IPv4
[INF] IPv6
[INF] IPv4/6 fragmentation
[INF] IPv4/6 in IPv4/6
[INF] GRE encapsulation
[INF] SSDP/UPnP flows
[INF] Ethernet flows
[INF] ARP flows
$

You will notice your end report output starting with tcpWin. Wasn’t so difficult, right?

Now try the T2_FPLOG_NUMP function, which produces a more comprehensive output is produced. The normalization factor must be supplied as a second variable. Just add the “<–” marked line in pluginReport callback.

Recompile tcpWin and execute T2

$ t2build tcpWin
...
$ t2 -r ~/data/annoloc2.pcap
...
--------------------------------------------------------------------------------
tcpWin: Aggregated status flags: 0x01
tcpWin: Number of tcp winsize packets below threshold 1: 2415 [0.25%]
tcpWin: Number of tcp winsize packets below threshold: 2415 (2.42 K) [0.25%]
--------------------------------------------------------------------------------
...
$

Note that large numbers are now better conceivable. You can add any output you want by adding more T2_FPLOG functions. Just add the code from the other tutorials. Have fun!