diff --git a/devel/spicy/reference.rst b/devel/spicy/reference.rst index f97aa9c1c..bc18629bb 100644 --- a/devel/spicy/reference.rst +++ b/devel/spicy/reference.rst @@ -339,12 +339,24 @@ 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_N); + on HOOK_ID -> event EVENT_NAME(ARG_1, ARG_2, ARG_3); - on HOOK_ID if COND -> event EVENT_NAME(ARG_1, ..., ARG_N); +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' @@ -364,6 +376,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 +505,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: @@ -520,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