Summary Statistics

Measuring aspects of network traffic is an extremely common task in Zeek. Zeek provides data structures which make this very easy as well in simplistic cases such as size limited trace file processing. In real-world deployments though, there are difficulties that arise from clusterization (many processes sniffing traffic) and unbounded data sets (traffic never stops). The Summary Statistics (otherwise referred to as SumStats) framework aims to define a mechanism for consuming unbounded data sets and making them measurable in practice on large clustered and non-clustered Zeek deployments.


The Sumstat processing flow is broken into three pieces. Observations, where some aspect of an event is observed and fed into the Sumstats framework. Reducers, where observations are collected and measured, typically by taking some sort of summary statistic measurement like average or variance (among others). Sumstats, where reducers have an epoch (time interval) that their measurements are performed over along with callbacks for monitoring thresholds or viewing the collected and measured data.



A single point of data. Observations have a few components of their own. They are part of an arbitrarily named observation stream, they have a key that is something the observation is about, and the actual observation itself.


Calculations are applied to an observation stream here to reduce the full unbounded set of observations down to a smaller representation. Results are collected within each reducer per-key so care must be taken to keep the total number of keys tracked down to a reasonable level.


The final definition of a Sumstat where one or more reducers is collected over an interval, also known as an epoch. Thresholding can be applied here along with a callback in the event that a threshold is crossed. Additionally, a callback can be provided to access each result (per-key) at the end of each epoch.


These examples may seem very simple to an experienced Zeek script developer and they’re intended to look that way. Keep in mind that these scripts will work on small single process Zeek instances as well as large many-worker clusters. The complications from dealing with flow based load balancing can be ignored by developers writing scripts that use Sumstats due to its built-in cluster transparency.

Printing the number of connections

Sumstats provides a simple way of approaching the problem of trying to count the number of connections over a given time interval. Here is a script with inline documentation that does this with the Sumstats framework:

 1@load base/frameworks/sumstats
 3event connection_established(c: connection)
 4    {
 5    # Make an observation!
 6    # This observation is global so the key is empty.
 7    # Each established connection counts as one so the observation is always 1.
 8    SumStats::observe("conn established", 
 9                      SumStats::Key(), 
10                      SumStats::Observation($num=1));
11    }
13event zeek_init()
14    {
15    # Create the reducer.
16    # The reducer attaches to the "conn established" observation stream
17    # and uses the summing calculation on the observations.
18    local r1 = SumStats::Reducer($stream="conn established", 
19                                 $apply=set(SumStats::SUM));
21    # Create the final sumstat.
22    # We give it an arbitrary name and make it collect data every minute.
23    # The reducer is then attached and a $epoch_result callback is given 
24    # to finally do something with the data collected.
25    SumStats::create([$name = "counting connections",
26                      $epoch = 1min,
27                      $reducers = set(r1),
28                      $epoch_result(ts: time, key: SumStats::Key, result: SumStats::Result) =
29                        {
30                        # This is the body of the callback that is called when a single 
31                        # result has been collected.  We are just printing the total number
32                        # of connections that were seen.  The $sum field is provided as a 
33                        # double type value so we need to use %f as the format specifier.
34                        print fmt("Number of connections established: %.0f", result["conn established"]$sum);
35                        }]);
36    }

When run on a sample PCAP file from the Zeek test suite, the following output is created:

$ zeek -r workshop_2011_browse.trace sumstats-countconns.zeek
Number of connections established: 6

Toy scan detection

Taking the previous example even further, we can implement a simple detection to demonstrate the thresholding functionality. This example is a toy to demonstrate how thresholding works in Sumstats and is not meant to be a real-world functional example, that is left to the policy/misc/scan.zeek script that is included with Zeek.

 1@load base/frameworks/sumstats
 3# We use the connection_attempt event to limit our observations to those
 4# which were attempted and not successful.
 5event connection_attempt(c: connection)
 6    {
 7    # Make an observation!
 8    # This observation is about the host attempting the connection.
 9    # Each established connection counts as one so the observation is always 1.
10    SumStats::observe("conn attempted", 
11                      SumStats::Key($host=c$id$orig_h), 
12                      SumStats::Observation($num=1));
13    }
15event zeek_init()
16    {
17    # Create the reducer.
18    # The reducer attaches to the "conn attempted" observation stream
19    # and uses the summing calculation on the observations. Keep
20    # in mind that there will be one result per key (connection originator).
21    local r1 = SumStats::Reducer($stream="conn attempted", 
22                                 $apply=set(SumStats::SUM));
24    # Create the final sumstat.
25    # This is slightly different from the last example since we're providing
26    # a callback to calculate a value to check against the threshold with 
27    # $threshold_val.  The actual threshold itself is provided with $threshold.
28    # Another callback is provided for when a key crosses the threshold.
29    SumStats::create([$name = "finding scanners",
30                      $epoch = 5min,
31                      $reducers = set(r1),
32                      # Provide a threshold.
33                      $threshold = 5.0,
34                      # Provide a callback to calculate a value from the result
35                      # to check against the threshold field.
36                      $threshold_val(key: SumStats::Key, result: SumStats::Result) =
37                        {
38                        return result["conn attempted"]$sum;
39                        },
40                      # Provide a callback for when a key crosses the threshold.
41                      $threshold_crossed(key: SumStats::Key, result: SumStats::Result) =
42                        {
43                        print fmt("%s attempted %.0f or more connections", key$host, result["conn attempted"]$sum);
44                        }]);
45    }

Let’s see if there are any hosts that crossed the threshold in a PCAP file containing a host running nmap:

$ zeek -r nmap-vsn.trace sumstats-toy-scan.zeek attempted 5 or more connections

It seems the host running nmap was detected!