Introduction and Background
I last wrote about detecting OpenVPN with Zeek, and to understand this blog you should familiarize yourself with that post.
This blog will not repeat the basics of OpenVPN, but instead it will briefly walk through the Spicy version of the same protocol analyzer we built in Binpac. You will see that the Spicy version of the protocol analyzer will be much more intuitive and compact.
To be able to use the Spicy protocol analyzers, you will need to install Spicy. Installation instructions can be found here:
Spicy comes with several components. First, it has a compilation toolchain much like gcc, except for the Spicy language. Second, Spicy has a Zeek plugin that enables Zeek to understand the Spicy analyzers without recompiling. The spicy-analyzers repository, discussed further in the next section, is the third component and contains the actual Spicy implementation of the analyzers. By installing the compilation toolchain, the Zeek plugin, and the spicy analyzers, you will have several new protocols supported in your Zeek installation. With Spicy installed, you can also begin to develop your own.
A (Brief) Code Walkthrough
Spicy analyzers are stored in the following public Github repository:
Spicy analyzers are either a file analyzer, which we won’t be talking about here, or a protocol analyzer. The OpenVPN analyzer is a protocol analyzer, so it can be found in the following directory:
Assuming you are familiar with the Binpac version of the OpenVPN protocol analyzer from the previous blog, you can apply some of that familiarity to the first file:
You can see at the top that a module “OpenVPN” is declared and spicy is imported. Then, you will notice all of the familiar data structures from our first blog! The syntax is slightly different, and by reading through the Spicy documentation each change will become clear. “openvpn.spicy” is similar to the following file from Binpac:
You will see that “dpd.sig” does not change between the Binpac and Spicy versions:
This means the Spicy and Binpac versions will be activated on the same network traffic.
That brings us to one of the main files in Spicy, the “openvpn.evt” file. This file enables the four protocol analyzers (OpenVPN, OpenVPN with HMAC, OpenVPN over TCP, and OpenVPN over TCP with HMAC) in lines 3-13:
The “openvpn.evt” file holds the same information that these four files contained previously:
Lines 18-22 of “openvpn.evt” tells Zeek to fire the newly created events on the right side when the protocol units on the left are successfully parsed. These events are more fully declared in “main.zeek”, a file we will discuss momentarily. The helper functions, such as “create_controlmsg”, are defined in the next file, which ties Spicy and Zeek together:
The beginning of this file loads a Zeek library so that Spicy can access Zeek specific functionality. Then, the logic between lines 8 and 17 will confirm the protocol if a control message is received as anticipated. Then, the helper functions are defined after line 27 in this file. These functions create tuples that can be coerced into Zeek records, defined in this file:
You can see in “main.zeek” that the structures and events are fully declared for script users. The rest of this file contains the same logic as our original version:
If we run into an error during parsing, we will reject the connection as not being OpenVPN:
Lastly, do you remember all of the complicated Binpac logic in this file?
We don’t need this complication in Spicy. The corresponding logic has already been covered because Spicy is a much more compact language. Are you sold on Spicy yet?
As you can see, Spicy brings much needed organization and simplicity to Zeek analyzers. OpenVPN was trivial to implement in Spicy, and more complicated protocols can be developed much faster than before. IPSec is a much more complicated protocol than OpenVPN, but I was able to write a Spicy parser in relatively short order. The same code would have taken me weeks in Binpac:
Download and install Spicy to have these new analyzers in your Zeek install, or use Spicy to develop protocol analyzers at high velocity. Either way, Spicy is becoming the next greatest technology underneath Zeek so stay tuned for new analyzers!