Welcome back to the course.
In the previous module,
we dove into the logging and notice frameworks to start learning more about
the scripting and customization capabilities of Zeek.
We saw how we were able to manipulate both in order to change
the logging and notifications for events.
Now,
it's time to start digging into the scripting capabilities of Zeek and
analyze some scripts to better understand them with the intention that
we'll build some later on in the course.
We're going to be using a built‑in script that Zeek comes with in
order to walk through the various pieces of it.
So if you're following along with your own installation of the tool,
you can pull up the policy script for detecting traceroute activity here.
Using this script,
we'll look at the various components of the script and
identify the important ones and options for it.
Before we dive into the scripting details,
we need to identify the scripts themselves.
In a previous module,
we learned that the signatures that we use within the Zeek
environment have the extension of .sig.
Well, as I've mentioned before in the course,
the scripts, they all have the extension of .zeek,
and the tool should recognize them if we call that out
in the scripts themselves or not.
When we load the scripts,
we can either define these individually or we can load the
entire directory that contains them,
which is the case in some of our local .zeek options.
We have a few great tools to use in order to help us better understand
the Zeek ecosystem and how the scripts can be used.
The first one that I want to call out is the script‑reference.
We'll detail this a little bit more later on in the
module this contains all of the options,
and variables, and attributes that can be used,
along with many others.
It also gives us the information about the analyzers,
and log files, and many other capabilities within Zeek.
The next one that I wanted to call out is the script index.
This contains information about every single script that Zeek
contains and gives us information about them.
These are very handy in trying to find a specific one for a specific use case.
We'll check out both of these tools in an upcoming demo.
The final resource that I want to share is the
framework section of the Book of Zeek.
That one gives us explanations and information about each of these,
including the input framework.
Understanding these can give us more insight into the
operations of Zeek and further depth into understanding how
we can manipulate the scripts more.
So let's walk through our sample script and identify the various sections before
we break down the scripting basics into manageable chunks.
Here's what we're working with with our traceroute script.
The first section that we see is with all of these @load directives,
similar to what we've seen earlier in the course.
These load commands tell us where the libraries are
that are included in this script, so we load the frameworks that we're using,
the other scripts that we need to take advantage of,
and more.
The load directive processes the _load_.zeek script and the
directories that are being loaded for use.
Chances are that what we're using in our custom scripts
already have the right libraries loaded,
but it's best practice just to include the load statements here,
just to make sure.
This first section also contains the namespace for
the script defined by a module.
Following this is the next section that gives us the
formatted variables being provided by export.
These define the constants for things like how the
notice framework will handle events, or in this case,
the log records defined for this traceroute log.
We have the different log fields that we're defining for this
one as designated by the log statement here,
similar to what we learned in the previous module.
As you can see in the middle of this section,
we have some constants that have been defined for this script
specifically that we'll need to call later on.
We have the thresholds here for the constants for the
icmp_time_exceeded and for the interval for it.
These definitions are important as we get into the next section of the script,
the events.
The third section is where the instructions to take
for specific events are written.
This is where the event handlers role is,
and it defines every single thing that Zeek will do
whenever an event is defined and occurs.
So for this script, specifically, we have three events defined.
We see what happens during the initialization of Zeek with
this script section that's included here.
Here is where we're doing things like creating new log
streams and defining parameters around those.
If you look here,
we have these variable tokens that link to the constants
that we defined earlier in the script,
defining how to interact with each of them.
We also have two other events,
one when a signature detection is made for low_ttl_packets
and another where the icmp_time_exceeded.
We define what happens to those events and any options
or variables that are applicable.