Zeek integration

Zeek supports writing packet, protocol or file analyzers with Spicy. In addition to allowing inclusion of unmodified Spicy grammars, additional features include:

Getting started

The recommended approach to integrate a Spicy parser with Zeek is to use the default Zeek package template.

We can create Zeek packet, protocol or file analyzers by selecting the appropriate template feature. E.g., to create a new Zeek package for a protocol analyzer and interactively provide required user variables,

zkg create --packagedir my_analyzer --features spicy-protocol-analyzer

Warning

zkg uses Git to track package information. When running in a VM, this can cause issues if the package repository is in a mounted directory. If you run into this trying creating the package in directory which is not mounted from the host.

Example

Use the template to create a Spicy protocol analyzer for analyzing TCP traffic now to follow along with later examples.

This will create a protocol analyzer from the template. Items which need to be updated are marked TODO. It will generate e.g.,

  • zkg.meta: package metadata describing the package and setting up building and testing
  • analyzer/
    • *.evt: interface definition for exposing Spicy parser as Zeek analyzer
    • *.spicy: Spicy grammar of the parser
    • zeek_*.spicy: Zeek-specific Spicy code
  • scripts/
    • main.zeek: Zeek code for interacting with the analyzer
    • dpd.sig: Signatures for dynamic protocol detection (DPD)
  • testing/tests: BTest test cases

Info

You can use zkg to install the package into your Zeek installation.

zkg install <package_dir>

To run its tests, e.g., during development:

zkg test <package_dir>

The generated project uses CMake for building and BTest for testing. You can build manually, e.g., during development. The test scaffolding assumes that the CMake build directory is named build.

# Building.
mkdir build
(cd build && cmake .. && make)

# Testing.
(cd testing && btest)

We can show available template features with zkg template info.

$ zkg template info
API version: 1.0.0
features: github-ci, license, plugin, spicy-file-analyzer, spicy-packet-analyzer, spicy-protocol-analyzer
origin: https://github.com/zeek/package-template
provides package: true
user vars:
    name: the name of the package, e.g. "FooBar" or "spicy-http", no default, used by package, spicy-protocol-analyzer, spicy-file-analyzer, spicy-packet-analyzer
    namespace: a namespace for the package, e.g. "MyOrg", no default, used by plugin
    analyzer: name of the Spicy analyzer, which typically corresponds to the protocol/format being parsed (e.g. "HTTP", "PNG"), no default, used by spicy-protocol-analyzer, spicy-file-analyzer, spicy-packet-analyzer
    protocol: transport protocol for the analyzer to use: TCP or UDP, no default, used by spicy-protocol-analyzer
    unit: name of the top-level Spicy parsing unit for the file/packet format (e.g. "File" or "Packet"), no default, used by spicy-file-analyzer, spicy-packet-analyzer
    unit_orig: name of the top-level Spicy parsing unit for the originator side of the connection (e.g. "Request"), no default, used by spicy-protocol-analyzer
    unit_resp: name of the top-level Spicy parsing unit for the responder side of the connection (e.g. "Reply"); may be the same as originator side, no default, used by spicy-protocol-analyzer
    author: your name and email address, Benjamin Bannier <benjamin.bannier@corelight.com>, used by license
    license: one of apache, bsd-2, bsd-3, mit, mpl-2, no default, used by license
versions: v0.99.0, v1.0.0, v2.0.0, v3.0.0, v3.0.1, v3.0.2