Alert Correlation Unit (Framework)

The ACU Framework provides an abstraction to underlying messaging work and a skeleton for concrete implementations. An ACU shall receive messages, aggregate and correlate them and finally send a meta-alert back to the Bro.

Acu

class acu::Acu

Public Functions

Acu(Storage *storage, AlertMapper *mapper)

Parameters
  • storage: The concrete storage implementation to use for storing every incoming alert.
  • mapper: The concrete alert mapper to be used to convert raw Broker messages to IncomingAlerts.

void Register(std::vector<std::string> *topics, Aggregation *aggregation, Correlation *correlation)

Register aggregations and correlations on the given topics.

aggregation may be NULL.

Parameters
  • topics: The topics to register to.
  • aggregation: The Aggregation to register on those topics.
  • correlation: The Correlation to register on those topics.

void Run()

Start the ACU main loop.

void CheckForAlerts()

Check for new alerts. Should be called periodically. Allows the user to interact after incoming messages.

void SetReceiverInfo(std::string address, port_t port)

Set connection data for the receiver.

void SetSenderInfo(std::string address, port_t port)

Set connection data for the sender.

Protected Functions

void OnReceive(const IncomingAlert *alert)

Receiver

class acu::Receiver

Public Functions

Receiver(std::string address, port_t port, std::vector<std::string> *topics, AlertMapper *mapper)

Initialise a new Receiver.

Parameters
  • address: The address to listen on.
  • port: The port to listen on.
  • topics: The topics to subscribe to.

void Peer(std::queue<IncomingAlert *> *queue)

Establish the connection with the outside to receive messages into the queue.

Parameters
  • queue: The queue fill with messages. The calling side can then pop those messages.

AlertMapper

class acu::AlertMapper

Public Functions

IncomingAlert *GetAlert(const std::string *topic, const broker::message &msg) const

Factory method to convert a raw Broker message into the corresponding IncomingAlert-Subclass.

Return
The correctly mapped message.
Parameters
  • topic: The topic string to identify the message.
  • message: The message to convert.

IncomingAlert

class acu::IncomingAlert

Public Functions

IncomingAlert(const std::string *topic, const broker::message &msg)

Instantiate a new IncomingAlert.

This type allows for easy, controlled access to the underlying message while trying to reduce complexity and memory.

Parameters
  • topic: The topic, this message was send on.
  • message: The actual message.

time_point<system_clock> timestamp() const

Timestamp indicating when the alert occurred.

const std::string &source_ip() const

Source IP of the connection that triggered this alert.

const port_t &source_port() const

Source port of the connection that triggered this alert.

const std::string &destination_ip() const

Destination IP of the connection that triggered this alert.

const port_t &destination_port() const

Destination port of the connection that triggered this alert.

bool operator==(const IncomingAlert &rhs) const

Checks upon equality.

bool operator!=(const IncomingAlert &rhs) const

Checks upon inequality.

Public Members

const std::string *topic

Topic the IncomingAlert was received under.

Protected Attributes

const std::vector<broker::data> message

The underlying message.

Friends

std::ostream &operator<<(std::ostream &stream, const IncomingAlert &alert)

Allows to print the alert into an ostream.

Aggregation

class acu::Aggregation

Public Functions

Aggregation(Storage *storage, std::vector<Threshold> *thresholds)

Instantiates a new Aggregation.

Parameters
  • storage: The shared storage object
  • thresholds: The thresholds for this aggregation to trigger correlations

virtual bool Invoke(const IncomingAlert *alert) = 0

Method called, when a new IncomingAlert is available. The actual aggregation will be done by this method.

Return
True if correlation shall be triggered, false otherwise
Parameters

Public Members

Storage *storage

The storage object, shared with all aggregations and correlations.

std::vector<Threshold> *thresholds

The thresholds for triggering correlations.

Correlation

class acu::Correlation

Public Functions

Correlation(Storage *storage, std::vector<Threshold> *thresholds)

Instantiates a new Correlation.

Parameters
  • storage: The shared storage object
  • thresholds: The thresholds for this internal triggers

virtual OutgoingAlert *Invoke() = 0

Method triggered by aggregation. The actual correlation will be done in this method.

Public Members

Storage *storage

The storage object, shared with all aggregations and correlations.

std::vector<Threshold> *thresholds

The thresholds for triggering correlations.

Storage

class acu::Storage

Public Functions

Storage(std::string db_name)

Instantiate the storage object, used for interaction with the underlying database.

Parameters
  • db_name: The name of the database

virtual void Persist(const IncomingAlert *alert) = 0

Persists the given alert.

Parameters

Public Members

std::string db_name

Name of the database.

Threshold

struct acu::Threshold

Public Functions

Threshold(int count, std::string field_name, std::string value)

Instantiate a Threshold.

Parameters
  • count: The count, the value must reach to trigger further computations
  • field_name: The name of the corresponding database field
  • value: The expected value of that field

bool operator==(const Threshold &rhs) const

Checks for equality.

bool operator!=(const Threshold &rhs) const

Checks for inequality.

Public Members

uint64_t count

Count after the threshold is reached.

std::string field_name

Field name which should be checked for the value.

std::string value

Value of the field which will be counted.

OutgoingAlert

class acu::OutgoingAlert

Public Functions

OutgoingAlert(std::string name, time_point<system_clock> timestamp)

Instantiate an OutgoingAlert.

Parameters
  • name: Name of the alert-event
  • timestamp: The point in time, this event occured

const std::string EventName() const

Return
The name of this event.

const broker::message ToMessage() const

Return
The broker-message of this alert.

Public Members

std::string incidentName

The name of this incident/alert.

time_point<system_clock> timestamp

The time_point to this incident/alert.

Sender

class acu::Sender

Public Functions

Sender(std::string destination, port_t port)

Instantiate a Sender

Parameters
  • destination: The destination address to send to
  • port: The destination port to send to

bool Send(OutgoingAlert *alert) const

Send the given alert.

Return
True if successful, false otherwise
Parameters

Public Static Attributes

const std::string ACU_OUTGOING_ALERT_TOPIC = "beemaster/acu/alert"

Constant topic name for outgoing alerts.

const std::string ENDPOINT_NAME = "acu_sender"

Constant name of the senders endpoint.

Utils

namespace acu

Typedefs

typedef uint16_t port_t

Typedef for consistent use of port numbers.