Beemaster: ACU Framework

Beemaster ships with a self-made general purpose framework for implementing custom alert correlation units (ACUs). Please have a look at the architecture documentation (German) for further reading about ACUs.

Overview

The framework offers a general abstraction layer for Broker-based communication with a Bro IDS instance. It handles messaging entirely and lets programmers focus on implementing algorithms directly in C++ on top of Bro events.

The framework is meant to be extensible; it provides a set of abstract classes for handling Bro events and integrates them into an event processing flow. During this flow, different steps are processed for persisting, aggregating, and correlating the messages. Resulting alerts are sent back to a Bro instance via Broker.

Project setup

Build

The project is intended to be developed with CLion. As it shall also be possible to build the project without an IDE (i.e. on the command-line), we added the Makefile. Calling make will build the project inside the build/ directory.

Code-Structure

├── Makefile                    # Makefile for 'IDE-less' compilation
│
├── cmake                       # additional cmake files
│   └── FindBroker.cmake
├── CMakeLists.txt              # the cmake build file
│
├── include                     # headers
│   └── acu
│       └── *.h
├── README.md
├── src                         # sources
│   ├── *.cc
│   └── CMakeLists.txt
└── test                        # test cases
    ├── *.cc
    └── CMakeLists.txt

Header Template

/* <filename>
 * ACU Framework
 *
 * <description>
 *
 * @author: <influencers>
 */

See acu.h for an example.

Testing

make clean test will clean and rebuild the framework sources. Then it executes all tests from the test directory.

Implementing a custom ACU

By using this framework, implementing a custom ACU is a comfortable task. Please find two examples for custom ACUs: The ACU Portscan respository features a simple ACU for detecting portscans (e.g. a distributed portscan) and the ACU Lattice respository a sample implementation of the lattice algoritm.

Example

Please have a look at the integration test. It provides a minimal example of how to implement a custom ACU using the framework and demonstrates the dataflow cycle from end to end.

Class overview & description

The framework provides a variety of (abstract-) classes and interfaces that need to be implemented for a custom ACU to work properly.

• include/acu/storage.h: Storage interface. The framework uses the custom storage that implements this interface to persist any incoming alert.
• include/acu/incoming_alert.h: Wrapper object for incoming messages. You can use the frameworks default implementation or extend it with your own class.
• include/acu/outgoing_alert.h: Wrapper object for alert generated by the ACU. You can use the frameworks default implementation or extend it with your own class.
• include/acu/aggregation.h: Aggregation algorithm: A custom ACU implementation must provide some aggregation function. The framework invokes this function on each incoming alert. The return value of this function determines whether to start a correlation.
• include/acu/correlation.h: Correlation algorithm. A custom ACU must provide some correlation function. It is invoked on positive aggregation results. The correlation may return an outgoing alert. If so, that will be sent back to the peered Bro master.
• include/acu/alert_mapper.h: Alert mapper. It is used to convert incoming Broker messages to objects. You can use the frameworks default implementation or extend it with your own class.
• include/acu/threshold.h: Thresholds are used for runtime configuration of the aggregations and correlations.