More flexible signature "event" interface

[vpax]

Currently, Zeek's signature framework supports the generation of a single event:

event signature_match(state: signature_state, msg: string, data: string)

and when writing signatures, all that's specified is the msg that goes with that event:

signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*root/
    event "Found root!"
}

We've been developing Zeek scripts that need to dispatch on the particular signature matched. Currently this requires a bunch of comparisons of msg (and these can happen in different instances of signature_match event handlers, depending on the modularity associated with the content). An extension to deal with this would be to allow the event specifier in a signature to optionally be the name of an event to generate, rather than a string to associate with it:

signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*root/
    event my_first_sig_event
}

(the event value could instead be a string like now, in which case signature_match is generated), or perhaps:

signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*root/
    event "Found root!"
    zeek_event my_first_sig_event
}

where the given event would have to have a common type signature (which for the second example could be the same as the signature_match event).

This seems handy and pretty straightforward to implement. Thoughts?

[awelzel]

where the given event would have to have a common type signature (which for the second example could be the same as the signature_match event).

This seems handy and pretty straightforward to implement. Thoughts?

How about extending the existing event keyword (and underlying RuleActionEvent) to include an optional event name, defaulting to signature_match?

EDIT: That might end-up a bit more repetitive and verbose than your first proposal, particularly if all signatures are dispatched to different events as the string parameter becomes redundant. However, the event keyword already allows identifiers - these are expected to be type string - and changing behavior based on the type of identifier seems trickier to explain than a bit more verbosity. The latter approach also allows to use a different event and use msg: string for dispatching within that event.

signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*root/
    event my_first_sig_event, "Found root";
}

signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*root/
    event Detector::found_root, "";
}

[awelzel]

I shouldn't have given that example :-)

My edit may have gotten lost. It is already valid today to provide an identifier instead of a quoted string for the event keyword. The example below gives you msg "GET_MATCH_STRING" within signature_match. It's the "event get_match" line below that I'm worried is confusing as one can't tell what's happening. The event name, "" is certainly not pretty, but it sets up the right expectations what the accompanying Zeek script will look like. Also, less of a hassle to document IMO.

I'm in no way blocking the type-based dispatch or alternative approaches, just worried about more gotchas ;-) Maybe someone else has a reaction/thought, too.

# sig.zeek
global get_match = "GET_MATCH_STRING";

@load-sigs ./sig.sig

event signature_match(state: signature_state, msg: string, data: string) {
        print "signature_match", msg, data;
}

# sig.sig
signature my-first-sig {
    ip-proto == tcp
    dst-port == 80
    payload /.*GET.*/
    event get_match
}

[vpax]

Ah, got it. What do you think about the zeek_event approach I sketched above? (Or some other name if there's a better one, I think zeek_event is a bit weird/clunky.)

[awelzel]

The extra keyword works. Just event_name maybe? Not too weird and unsurprising?

That said, would any of the following resonate? Or do you have a special character you associate with an event? There's much freedom to add a bit of syntax to identify the event identifier.

# Banging the event
event !found_root
event !found_root "token"

# Bracketing the event -  `()` or `{}` could also work.
event [found_root]
event [found_root] "token"

event @found_root
event @found_root "token"

# Reasonable, but also disconnected from Zeek script syntax and the actual signature, so not sure I like that.
event found_root()
event found_root() "token"

If none of these, event_name seems pragmatic enough :-)

[vpax]

For my taste, the [found_root] approach would be okay. The remaining question would be whether the first form (where there's no "token" argument) would have the same signature, with an empty msg, or a different signature that omits the msg paramater entirely. I like the latter, though I suspect you'll prefer the former.

Not a biggie either way - would be helpful to know if others have opinions.

[awelzel]

I liked [found_root] the most, too. It's unusual at first, but doesn't have a disagreeing meaning in Zeek script which helps avoid confusion.

I like the latter, though I suspect you'll prefer the former.

You convinced me with removing the msg: parameter from the signature ;-) The only case that won't work is if a user has two usages of:

event [found_root]
event [found_root] "token"

...and seems reasonable to not allow that and instead require one or the other form consistently. The result will be cleaner. (and they can use event [found_root] "" as an escape hatch if that's really what they want).

[vpax]

@awelzel given we've converged, what's next? Add an issue for this to the backlog? (Fine by me if you want to take it over from here. Fine if not, too :-))

[awelzel]

Yes. There's a ticket I'm planning on working on soon so this should be in 6.2. There's a link at the right of the discussion with a bread-crumb, though little obvious.

#3403