MP-IDS 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](https://git.informatik.uni-hamburg.de/iss/mp-ids/blob/master/dokumente/dokumentation/architektur/Architektur.pdf) (German) for further reading about ACUs.

## Overview

The framework offers a general abstraction layer for [Broker](https://github.com/bro/broker)-based communication with a [Bro](https://www.bro.org) 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][0]. As it shall also be
possible to build the project without an IDE (i.e. on the command-line), we
added the [`Makefile`](Makefile). Calling `make` will build the project inside the
`build/` directory.

[0]: https://www.jetbrains.com/clion/

#### 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

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

See [acu.h](include/acu/acu.h) for an example.

#### Testing

`make clean test` will clean and rebuild the framework sources. Then it executes all tests from the [test](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 inside the Beemaster [ACU respository](https://github.com/UHH-ISS/beemaster-acu-portscan). The `master` branch features a simple ACU for detecting portscans (e.g. a distributed portscan). ~~On the `experimental_lattice` branch, there is more sophisticated ACU featuring a sample implementation of the lattice algorithm.~~

#### Example

Please have a look at the [integration test](test/test_acu.cc). 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](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](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](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](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](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](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](include/acu/threshold.h): Thresholds are used for runtime configuration of the aggregations and correlations.