Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document &priority=N for evt files #277

Closed
wants to merge 2 commits into from
Closed

Document &priority=N for evt files #277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c857351
Document `&priority=N` for `evt` files
evantypanski Oct 14, 2024
4d84aed
fixup! Document `&priority=N` for `evt` files
evantypanski Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 30 additions & 11 deletions devel/spicy/reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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];
bbannier marked this conversation as resolved.
Show resolved Hide resolved

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'
Expand All @@ -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``).
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down
Loading