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.

Installing Spicy

To be able to use the Spicy protocol analyzers, you will need to install Spicy. Installation instructions can be found here:

https://docs.zeek.org/projects/spicy/en/latest/

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:

https://github.com/zeek/spicy-analyzers

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:

https://github.com/zeek/spicy-analyzers/tree/v0.2.8/analyzer/protocol/openvpn

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:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/openvpn.spicy

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:

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpn-defs.pac

You will see that “dpd.sig” does not change between the Binpac and Spicy versions:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/dpd.sig

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/scripts/zeek/openvpn/dpd.sig

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:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/openvpn.evt

The “openvpn.evt” file holds the same information that these four files contained previously:

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpn-protocol.pac

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpnhmac-protocol.pac

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpntcp-protocol.pac

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpntcphmac-protocol.pac

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:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/openvpn_zeek.spicy

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:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/main.zeek

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:

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/scripts/zeek/openvpn/main.zeek

If we run into an error during parsing, we will reject the connection as not being OpenVPN:

https://github.com/zeek/spicy-analyzers/blob/v0.2.8/analyzer/protocol/openvpn/openvpn_zeek.spicy#L19

Lastly, do you remember all of the complicated Binpac logic in this file?

https://github.com/corelight/zeek-openvpn/blob/v0.0.14/src/openvpn-analyzer.pac

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?

Conclusion

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:

https://github.com/zeek/spicy-analyzers/tree/v0.2.8/analyzer/protocol/ipsec

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!