README

# Zeek::Lognorm

This plugin aims at integrating liblognorm into Zeek. The current state should be considered as experimental.

## Installation

The plugin is based on [liblognorm](https://github.com/rsyslog/liblognorm), which requires [libfastjson](https://github.com/rsyslog/libfastjson) and [libestr](https://github.com/rsyslog/libestr). Make sure the libraries are available including their headers, which are required to build this plugin.

### Package Manager
The plugin is available as package for the [Zeek Package Manager](https://github.com/zeek/package-manager) and can be installed using the following command:

    zkg install zeek-lognorm

### Manual Install
The following will compile and install the Lognorm plugin alongside Zeek, assuming it can find the headers in a standard location:

    # ./configure && make && make install

If the headers are installed somewhere non-standard, add `--with-liblognorm=<liblognorm-header-directory>` and `--with-libfastjson=<libfastjson-header-directory>` to the `configure` command. If everything built and installed correctly, you should see this:

    # zeek -N Zeek::Lognorm
	Zeek::Lognorm - Log file analyzing (experimental) (dynamic, version 1.0.0)
    [Function] Lognorm::lognormalizer_init
    [Function] Lognorm::lognormalizer_init_ex
    [Function] Lognorm::lognormalizer_load_rule_file
    [Function] Lognorm::lognormalizer_load_rule
    [Function] Lognorm::lognormalizer_normalize

## Usage

The plugin wraps basic liblognorm functionality by providing the `lognorm` opaque type. This type allows to parse log lines based on liblognorm rule files. In case a rule matches, an event for every tag the rule defines is scheduled. To handle these, one needs to define an event with the corresponding name. This event may specify any subset of fields, parsed by the rule, as arguments. Fields are mapped to arguments by name.

The plugin comes with a small set of scripts that allow easy integration. For more details see `scripts/lognorm/`.

## Notes

 - The plugin is not well tested!
 - Lognorm variables are converted into Zeek types. Currently only `string`, `int`, `double` and `bool` are supported.
 - In particular, the plugin does not support nested types (might be implemented on demand).
 - The `unparsed_line()` event cannot be used in cluster mode.
 - If you have any ideas or suggestions, feel free to reach out!