Event Groups

Zeek supports enabling and disabling event and hook handlers at runtime through event groups. While named event groups, hook handlers are covered due to their structural similarity to event handlers as well.

Event and hook handlers can be part of multiple event groups. An event or hook handler is disabled if any of the groups it’s part of is disabled. Conversely, event and hook handlers are enabled when all groups they are part of are enabled. When Zeek starts, all event groups are implicitly enabled. An event or hook handler that is not part of any event group is always enabled.

Currently, two types of event groups exist: Attribute and module based.

Attribute Based Event Group

Attribute based event groups come into existence when an event or hook handler has a &group attribute. The value of the group attribute is a string identifying the group. There’s a single global namespace for attribute based event groups. Two event handlers in different files or modules, but with the same group attribute value, are part of the same group. Event and hook handlers can have more than one group attributes.

event_groups_attr_01.zeek

event http_request(c: connection, method: string, original_URI: string, unescaped_URI: string, version: string) &group="http-print-debugging"
    {
        print fmt("HTTP request: %s %s (%s->%s)", method, original_URI, c$id$orig_h, c$id$resp_h);
    }

event http_header(c: connection, is_orig: bool, original_name: string, name: string, value: string) &group="http-print-debugging"
    {
    if ( name != "USER-AGENT" && name != "SERVER" )
        return;

    local snd = is_orig ? c$id$orig_h : c$id$resp_h;
    local rcv = is_orig ? c$id$resp_h : c$id$orig_h;
    print fmt("HTTP header : %s=%s (%s->%s)", original_name, value, snd, rcv);
    }

event http_reply(c: connection, version: string, code: count, reason: string) &group="http-print-debugging"
    {
        print fmt("HTTP reply: %s/%s version %s (%s->%s)", code, reason, version, c$id$resp_h, c$id$orig_h);
    }

This example shows http_request, http_header and http_reply event handlers, all with a group attribute of http-print-debugging. When running Zeek against a pcap containing a single HTTP transaction, the output is as follows.

$ zeek -r traces/get.trace  ./event_groups_attr_01.zeek
HTTP request: GET /download/CHANGES.bro-aux.txt (141.142.228.5->192.150.187.43)
HTTP header : User-Agent=Wget/1.14 (darwin12.2.0) (141.142.228.5->192.150.187.43)
HTTP reply: 200/OK version 1.1 (192.150.187.43->141.142.228.5)
HTTP header : Server=Apache/2.4.3 (Fedora) (192.150.187.43->141.142.228.5)

Such debugging functionality would generally only be enabled on demand. Extending the above script, we introduce an option and a change handler function from the configuration framework` to enable and disable the http-print-debugging event group at runtime.

event_groups_attr_02.zeek

@load base/frameworks/config

redef Config::config_files += { "./myconfig.dat" };

module Debug;

export {
    option http_print_debugging = F;
}

event http_request(c: connection, method: string, original_URI: string, unescaped_URI: string, version: string) &group="http-print-debugging"
    {
        print fmt("HTTP request: %s %s (%s->%s)", method, original_URI, c$id$orig_h, c$id$resp_h);
    }

event http_header(c: connection, is_orig: bool, original_name: string, name: string, value: string) &group="http-print-debugging"
    {
    if ( name != "USER-AGENT" && name != "SERVER" )
        return;

    local snd = is_orig ? c$id$orig_h : c$id$resp_h;
    local rcv = is_orig ? c$id$resp_h : c$id$orig_h;
    print fmt("HTTP header : %s=%s (%s->%s)", original_name, value, snd, rcv);
    }

event http_reply(c: connection, version: string, code: count, reason: string) &group="http-print-debugging"
    {
        print fmt("HTTP reply  : %s/%s version %s (%s->%s)", code, reason, version, c$id$resp_h, c$id$orig_h);
    }

event zeek_init()
    {

    Option::set_change_handler("Debug::http_print_debugging", function(id: string, new_value: bool): bool {
        print id, new_value;
        if ( new_value )
            enable_event_group("http-print-debugging");
        else
            disable_event_group("http-print-debugging");

        return new_value;
    });

    # Trigger the change handler, once.
    Config::set_value("Debug::http_print_debugging", F);
    }

Whenever the option Debug::http_print_debugging is set to T, enable_event_group is invoked to ensure the http-print-debugging group is enabled. Conversely, when the option is set to F, disable_event_group disables all event handlers in the group http-print-debugging.

The very same behavior can be achieved by testing the Debug::http_print_debugging option within the respective event handlers using and if statement and early return. In contrast, event groups work in a more declarative way. Further, when disabling event handlers via event groups, their implementation is never invoked and is therefore a more performant way to short-circuit execution.

Module Based Event Group

Besides attribute based event groups, Zeek supports implicit module based event groups. Event and hook handlers are part of an event group that represents the module in which they were implemented. The builtin functions disable_module_events and enable_module_events can be used to disable and enable all event and hook handlers within modules.

An interesting idea here is to implement enabling and disabling of Zeek packages at runtime. For example, the CommunityID package implements its functionality in the CommunityID and CommunityID::Notice modules. The JA3 package implements its event handlers in the JA3 and JA3_Server modules.

event_groups_module_01.zeek

@load base/frameworks/config

@load ja3
@load zeek-community-id
@load zeek-community-id/notice

redef Config::config_files += { "./myconfig.dat" };

module Packages;

export {
    # All packages off by default.
    option community_id_enabled = F;
    option ja3_enabled = F;
}

event zeek_init()
    {
    local package_change_handler = function(id: string, new_value: bool): bool {
        local modules: set[string];

        if ( id == "Packages::community_id_enabled" )
            modules = ["CommunityID", "CommunityID::Notice"];
        else if ( id == "Packages::ja3_enabled" )
            modules = ["JA3", "JA3_Server"];
        else
            {
            Reporter::error(fmt("Unknown option: %s", id));
            return new_value;
            }

        # Toggle the modules.
        for ( m in modules )
            if ( new_value )
                enable_module_events(m);
            else
                disable_module_events(m);

        return new_value;
    };

    Option::set_change_handler("Packages::community_id_enabled", package_change_handler);
    Option::set_change_handler("Packages::ja3_enabled", package_change_handler);

    Config::set_value("Packages::community_id_enabled", F);
    Config::set_value("Packages::ja3_enabled", F);
    }

The above script implements toggling of Zeek package functionality at runtime via the options Packages::ja3_enabled and Packages::community_id_enabled. While for most packages and deployments a Zeek restart is an acceptable way to disable or enable a package - generally this isn’t a regular operation - module based event groups provide a powerful primitive to support runtime toggling of scripting functionality.

Note

A caveat around the above example: The JA3 package builds up state based on the ssl_extension events from SSL ClientHello and ServerHello messages. When the JA3 event handlers are enabled right during processing of these events, the resulting JA3 hash might be based on a partial list of extensions only.

While all ssl_extension handlers are processed jointly for each instance of the event, generally state build up and dynamic enabling and disabling may need careful consideration.