Introduction

https://github.com/grigorescu/binpac_quickstart will be used for this tutorial.

Inside the binpac_quickstart directory, simply run:

python start.py Sample "Sample Protocol" ../bro --tcp --buffered

This will generate all the necessary files for this sample analyzer. The ../bro argument here just points to the Zeek source tree. Make sure to change it if yours lives in a different location. See the start.py --help options for more explanation of the options.

Zeek should be able to compile the generated template code right away, but files may have some "TODO" comments in them to mark places that typically need to be changed depending on the specifics of the protocol analyzer you want to make.

Explanation of each created file

In the scripts/base/protocols/sample/ directory:

__load__.bro

This allows all the contents of the directory to be loaded via @load base/protocols/sample.

dpd.sig

This file contains a signature that can be used to attach the analyzer to connections if their content matches. See the signature framework documentation for more information on signatures.

main.bro

Contains the base script-layer functionality for processing events emitted from the analyzer.

In the src/analyzer/protocol/sample/ directory:

CMakeLists.txt

Informs the CMake build system how to compile the analyzer.

Plugin.cc

Analyzers in Zeek are a type of plugin. This file does what’s necessary to register the new analyzer plugin with Zeek.

SAMPLE.h

Defines the API for the new analyzer which derives from one of Zeek’s already-existing analyzer classes.

SAMPLE.cc

Implementation of the analyzer. It’s mostly just responsible for handing off data to the protocol parser that’s been generated by BinPAC.

events.bif

Defines events that the analyzer will generate.

sample.pac

The main entry point for the BinPAC definition of the protocol that you want to parse. See the BinPAC README for more about how to write parsers with it.

sample-protocol.pac

Where the message format is defined.

sample-analyzer.pac

Defines a connection, flow, and other processing functions for the analyzer.