From c85735112290fdf594e2eb73f774feab9b58a7cd Mon Sep 17 00:00:00 2001 From: Evan Typanski Date: Mon, 14 Oct 2024 09:41:35 -0400 Subject: [PATCH 1/2] Document `&priority=N` for `evt` files Also reorganize to make it a little more consistent with other parts. --- devel/spicy/reference.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst index f97aa9c1c..23c17f82a 100644 --- a/devel/spicy/reference.rst +++ b/devel/spicy/reference.rst @@ -342,9 +342,7 @@ Event Definitions To define a Zeek event that you want the Spicy analyzer to trigger, you add lines of the form:: - on HOOK_ID -> event EVENT_NAME(ARG_1, ..., ARG_N); - - on HOOK_ID if COND -> event EVENT_NAME(ARG_1, ..., ARG_N); + on HOOK_ID [if ( COND )] -> event EVENT_NAME(ARG_1, ..., ARG_N) [&priority=N]; Zeek automatically derives from this everything it needs to register new events with Zeek, including a mapping of the arguments' @@ -364,6 +362,12 @@ the pieces going into such an event definition: has been parsed. (In the former example you may skip the ``%done``, actually: ``on HTTP::Request`` implicitly adds it.) +``if ( COND )`` + If given, events are only generated if the expression ``COND`` + evaluates to true. Just like event arguments, the expression is + evaluated in the context of the current unit instance and has + access to ``self``. + ``EVENT_NAME`` The Zeek-side name of the event you want to generate, preferably including a namespace (e.g., ``http::request``). @@ -487,12 +491,9 @@ the pieces going into such an event definition: - List comprehension can be convenient to fill Zeek vectors: ``[some_func(i) for i in self.my_list]``. -``if COND`` - If given, events are only generated if the expression ``COND`` - evaluates to true. Just like event arguments, the expression is - evaluated in the context of the current unit instance and has - access to ``self``. - +``&priority=N`` + An optional priority, where events with higher priority are raised + before lower priority ones. The default priority is ``-1000``. .. _spicy_export_types: From 4d84aedbd84b195045f449684ea59ae523619fd1 Mon Sep 17 00:00:00 2001 From: Evan Typanski Date: Tue, 15 Oct 2024 09:18:47 -0400 Subject: [PATCH 2/2] fixup! Document `&priority=N` for `evt` files --- devel/spicy/reference.rst | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst index 23c17f82a..bc18629bb 100644 --- a/devel/spicy/reference.rst +++ b/devel/spicy/reference.rst @@ -339,11 +339,25 @@ As a full example, here's what a new GIF analyzer could look like: Event Definitions ----------------- -To define a Zeek event that you want the Spicy analyzer to trigger, you -add lines of the form:: +You can define a Zeek event that you want the Spicy analyzer to +trigger:: + + on HOOK_ID -> event EVENT_NAME(ARG_1, ARG_2, ARG_3); + +With an optional condition:: + + on HOOK_ID if ( True ) -> event EVENT_NAME(ARG_1, ARG_2, ARG_3); + +Or with an optional priority:: + + on HOOK_ID -> event EVENT_NAME(ARG_1, ARG_2, ARG_3) &priority=0; + +The generic syntax is:: on HOOK_ID [if ( COND )] -> event EVENT_NAME(ARG_1, ..., ARG_N) [&priority=N]; +where elements in square brackets ``[...]`` are optional. + Zeek automatically derives from this everything it needs to register new events with Zeek, including a mapping of the arguments' Spicy types to corresponding Zeek types. More specifically, these are @@ -521,7 +535,11 @@ To have the Zeek create a type for your analyzer automatically, you need to ``export`` the Spicy type in your EVT file. The syntax for that is:: - export SPICY_ID [as ZEEK_ID]; + export SPICY_ID; + +Optionally, you may add a ``ZEEK_ID``:: + + export SPICY_ID as ZEEK_ID; Here, ``SPICY_ID`` is the fully-scoped type ID on the Spicy side, and ``ZEEK_ID`` is the fully-scoped type ID you want in Zeek. If you leave