Perl Bindings for Broccoli

This Perl module provides bindings for Broccoli, Bro's client communication library. Note that this package is still considered experimental, and not yet part of the Broccoli distribution. Please let us know whether it works for you.

Contents

• Download
• Installation
• Usage
  • Connectiong to Bro
  • Sending Events
  • Receiving Events
• Examples

Download

Broccoli-Perl's git repository is located at git://git.bro-ids.org/broccoli-perl.git. You can browse the repository here. Please note that we do not yet provide releases outside of git (but plan to do so in the future)

This document describes Broccoli-Perl 0.1-1. See the CHANGES file for version history.

Installation

Broccoli-Perl requires perl 5.10.1 or newer.

To install do something like:

export CCFLAGS="-I/usr/local/bro/include"
export LDDFLAGS="-L/usr/local/bro/lib"

perl Makefile.PL

make
make install

If broccoli.h is not found (many unknown definition errors), check CCFLAGS. If a scripts complain about dynamic linking errors at start, check LDDFLAGS.

Usage

The following examples give a short demonstration on how to send and receive Bro events in Perl.

A more thorough explanation can be found in the pod documentation of the module.

Connectiong to Bro

The following code opens a connection to a remote Bro instance. Automatic type guessing is enabled.

# import Broccoli and all types
use Broccoli::Connection qw/:types/;

# connect to bro
my $b = Broccoli::Connection->new(
                destination => "localhost:47758",
                quess_types => 1,
});

Sending Events

When a bro connection has been set up, it can be used to send events:

# send events
my $seq = 0;
$b->send("ping", $seq++);

Records are automaticially generated from Hashes:

# send records
$b->send("recordtest", {
        intvalue => 1,
        stringvalue => "hi",
});

# send records of records
$b->send("RecordOfRecordTest", {
        first => { intvalue => 1 },
        second => { addr => "192.168.17.1" }
};

Types can be explecitely specified when necessary. For more details see the pod documentation

# specify type
$b->send("counttest", count(5));

Receiving Events

To receive events, a callback function has to be specified.

# define event handlers
$b->event("pong", sub {
        my $seq = shift;
        say "Received pong with number $seq";
});

After defining all callback functons, the event handlers have to be registered by calling

$b->registerEvents();

Bro data types are automatically converted to the perl equivalents. Records are converted to hashes.

Examples

Some examples are in te examples subdirectory.

• broping.pl sends pings to the broping.bro script included with Broccoli.
• broping-record.py sends pings to the broping-record script included with Broccoli.
• test.pl and test_guesstypes.pl together with test.bro show most of the features supported by the library.