Category : Plug-Ins

Submitted By : Savvius

Downloaded : 191 Times

View Comments (1)

Deep in the dark corridors of Savvius Labs, we have developed a new capability called Filter Scripts for the Windows and Linux Capture Engines that makes it possible for users to create filters that generate events and summary stats. It builds on the existing filter and filter UI functionality to create arbitrarily complex conditions for generating custom events and summary stats, as well as extract values and strings out of the packets to create the text for the events and summary stats. 

So how does it work? There are two parts to it. The first part is very simple, or at least familiar, since it is a feature we are all already used to: creating a filter. Just create an advanced filter with all of the filter nodes necessary to filter a particular type of packet.  The filter could be for HTTP Response Code Packets, DNS Error Packet, SSL Version Packets, or virtually any other type of packet you can think of that has something your want to count or alert on.

The next step is to specify what the action should be if the filter is matched. This is easy as well since it is just another type of filter node. The filter node type is called the FilterEventPlugin, and it is one of the options available in the Analysis Module Filter Node list.  By adding this node to the end of your filter node chain, you can now specify the action to be taken when a packet matches the preceding filter nodes.

Now comes the fun part, which is specifying the actions, and the various options for the actions. The action options are specified in the Comment field of the filter, along with the static text that will be used in the label or title of the action, which is to either generate an event and/or a summary stat.

Example

Alright, enough with the description, let’s see what it all looks like. Below is a list of Filter Scripts in a filter folder called “Action Filters”.  As the list of filters grows, there can be many different folders with many different types of filter scripts.

Let’s open one up.

This Filter Script is called “DNS Questions”.  The filter node is simple, just test for DNS.  The next filter node is the FilterEventPlugin node, which in this case says to perform an action.

The action is specified as text in the Comment field.  First is the static text of our action which is “DNS Questions”.  In this case we have specified a –s, which means to generate a summary stat, we also use  --g”DNS Stats” to specify the summary stat group to put it into.  The next option is very cool.  It is the –v, which says to extract 1 byte from offset 47 and use it to increment the value of the summary stat.

Here is the result:

Do you see what we just did?  We not only created a Summary Stat, but once it is there, then subsequent packets cause it to increment, either by 1, or by some value extracted from the packet. 

And to go just a bit deeper, here is an example of a DNS packet showing the number of questions at offset 46

Options

Here is a list of the  Filter Script options:

--iN:M (extract and display integer with M bytes from N offset )

--aN:M (extract and display string with M chars from N offset. Stops at nonprintable character)

--vN:M (like –i, but read binary M bytes as value to add to stats)

--o”pattern”:N (read N ascii-bytes, after pattern “pattern”  , attach to filterName)

--t (if TCP, adjust “0-point” for offsets to tcppayload start instead of packet start)

--u (if UDP, adjust “0-point” for offsets to tcppayload start instead of packet start)

--s (enable summary stats) 

--lN (enable log entry with severity N)

--g”name” (stats group name)

Some of these options deserve a little more discussion. Let's start with the two primary output options, events and summary stats. If you want to generate an event every time a packet gets through the filter, use the --IN option. The N is the severity of 1-4. Events are good if you want to know ASAP when something occurred, or you want to get the information to some other reporting tool, like Splunk or ELK. Keep in mind, events can tax the system, especially if there are a lot of them, resulting in a performance hit, and potentially causing dropped packets. If you want to just keep track of how often something occurs, but not be notified immediately, use the --s option to create a Summary Stat. The --s option would typically be combined with the --g option to specify the Summary Stat Group Name. The --t and --u are used in conjunction with the data extraction options.  --t says to start the offset after the TCP header, and --u says to start after the UDP header. The remaining options specify different ways to extract data. The --iN:M option is used to extract an integer of M number of bytes, starting at offset N. Valid values for M are 1-8. --vN:M is just like --iN:M except that it uses the extracted value to add the summary stat value, instead of just incrementing the value by 1. The --aN:M option is used to extract a string of M bytes, starting at offset N. The --a has the extra feature of stopping at a newline or other non-printable character. The --o"pattern":N option is like the --a, but instead of a starting offset, a regular expression is matched and N ascii-bytes are extract after that.

More examples can be found in the FilterScripts.pptx file attached to the Package link of this page. But really, the possibilities are endless. We look forward to hearing back from the community on the interesting and/or useful ways to use this powerful capability

Installation

To use the FilterScripts, download the "Package" using the "Download Package" link at the top of this page, unzip it, and put the files in the appropriate locations. The FilterEventPlugin.he is common for both Linux and Windows.  On Linux, use the FilterEventPlugin.so file. For Windows use the FilterEventPlugin.dll file.

On Windows, the files go here:

C:Program FilesSavviusCapture Engine

On Linux, they go here

/usr/lib/omni/plugins – FilterEventPlugin.so

/etc/omni – FilterEventPlugin.he