Friday, August 9, 2013

Intro to Brogramming - Modules

Bro modules are essentially C++ namespaces. Modules allow grouping of related functions, variables, and events under a single context.

The GLOBAL module is the default namespace for all Bro scripts. If no module is defined in a Bro script, it is dropped into GLOBAL. Modules are defined whenever a brogrammer is extending Bro at the scripting layer to do something beyond what Bro currently does. Modules are basic building blocks for extending Bro via scriptland. Examples of modules include the LogAscii, LogDataSeries, and LogSQLite. Each offers a different interface for logging information Bro generates.

Often times Bro modules are organized in the source tree in a somewhat logical manner and are given their own directory. A very basic module can be found here. To learn Bro, you have to read and understand its code. I highly recommend spending time exploring the /usr/local/bro/share/bro directory and files within it especially the base directory (which contains important scriptland modules and scripts) and the policy directory (which contains tweaks to the base scripts).

A module usually consists of the following

main.bro - The main script that defines the module and what it does.

__load__.bro - A special file Bro uses to to load all required dependency scripts for a module. Bro looks for this file in the working directory by default and loads it if the file is present.

helper scripts or data files - Other Bro scripts or data files that might be too long or specific to put into the main.bro file. Bro modules often work by chaining short script files (that do something specific) together.

From within a script file, the 'module' keyword registers a new module with Bro's core and the 'export' block defines global changes Bro should make to accommodate the new module being defined. Usually, the code in the rest of a module script is used to set values in the module's record (often for logging) or to accomplish other tasks the module intends to provide.

To find the names of all modules in your version of Bro, try running the following command in the directory %BRO_PREFIX%/share/bro