Introduction

The accompanying archive for this tutorial comes with the following files:

• sample.pac
• sample-analyzer.pac
• sample-protocol.pac
• Sample.cc
• Sample.h
• sample.bro
• sample-analyzer-diff.txt

The last file sample-analyzer-diff.txt is the output of git diff —cache if you want to start by just creating and modifying the necessary files that way. This diff was made to compile with the CMake version of Bro, after version 1.5. We will include the needed changes for those wanting to create an analyzer to compile with version 1.5.

Explanation of each created file

sample.pac

Ties sample-analyzer.pac and sample-protocol.pac together.

sample-analyzer.pac

Defines a connection and flow for this analyzer and all the functions that sample-protocol.pac uses.

sample-protocol.pac

Where the message format is defined. In this case we just have the data before where length is defined and then the rest of the data.

Sample.cc

This file has the code that will use what the binpac files define. A lot more code can go into this file, such as special handling of data before giving it to binpac or handling of exceptions.

Sample.h

Header file for the .cc file. InstantiateAnalyzer is a constructor function and Available returns whether or not an event is being used, which is used to figure out if this analyzer should be instantiated.

sample.bro

Simple Bro script to catch the sample event. sample_ports are the ports we care about for this sample analyzer (It is currently tailored to look at bgp messages). The line that redefines dpd_config adds the key-value pair of the ports to look at for this script. The redefinition of capture_filters is like adding a filter to tcpdump.

Files that need to be modified

Analyzer.cc

Include the C++ header file at the top and add to analyzer_configs. Look in src/Analyzer.h to see what an Analyzer::Config is and what each parameter is.

AnalyzerTags.h

Add the name of our analyzer, in this case Sample, to the application-layer analyzers list in the enum Tag.

CMakeLists.txt

Add the binpac files to the list of binpac_target. Add our cc file, Sample.cc, to the bro_SRCS.

event.bif

Add all the events related to this analyzer to this file. There is no need in the function prototype to include the first parameter, bro_analyzer, that you had in sample-analyzer.pac.

CMake vs. Autotools

Bro versions before 1.6 used autotools in place of CMake. To compile a binpac analyzer with these earlier versions, the following changes apply:

sample-analyzer.pac

When creating a Bro event, before version 1.6 the format was bro_event_sample_message. After version 1.5 the format is now BifEvent::generate_sample_message.

CMakeLists.txt

This file is used by CMake to build Bro. However version 1.5 and before don’t have CMake. So to compile edit Makefile.am and do the following:

• add sample.pac to BINPAC_SRC
• add sample-protocol.pac and sample-analyzer.pac to BINPAC_RPC_AUXSRC
• add Sample.cc to bro_SOURCES
• add Sample.h to noinst_HEADERS
• create a new build rule for sample_pac.h and sample_pac.cc, look for other build rules of a similar format.