.\" Automatically generated by Pandoc 2.17.1.1 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. .ie "\f[CB]x\f[]"x" \{\ . ftr V B . ftr VI BI . ftr VB B . ftr VBI BI .\} .el \{\ . ftr V CR . ftr VI CI . ftr VB CB . ftr VBI CBI .\} .TH "laurel" "8" "" "laurel 0.5.1" "System Administration Utilities" .hy .SH NAME .PP laurel(8) \[en] transform, enrich Linux audit logs .SH SYNOPSIS .PP \f[V]laurel\f[R] is an \f[V]auditd(8)\f[R] plug-in that parses Linux audit events, enriches them with local information, and transforms them into a JSONlines-based output format intended for consumption by log processing and SIEM software. .SH OPTIONS .TP \f[B]-c FILE\f[R], \f[B]--config=FILE\f[R] path to configuration file (default: unset) .TP \f[B]-d\f[R], \f[B]--dry-run\f[R] Only parse configuration and exit .TP \f[B]-h\f[R], \f[B]--help\f[R] Print short help text and exit .TP \f[B]-v\f[R], \f[B]--version\f[R] Print version and exit .SH DESCRIPTION .PP \f[V]laurel\f[R] is typically configured to be spawned by \f[V]auditd(8)\f[R] itself or by \f[V]audispd(8)\f[R] (for 2.x \f[I]auditd\f[R] versions). All audit events are fed to \f[V]laurel\f[R] via its standard input channel. .PP Sample configuration file \f[V]/etc/audit/plugins.d/laurel.conf\f[R]: .IP .nf \f[C] active = yes direction = out type = always format = string path = /usr/sbin/laurel args = --config /etc/laurel/config.toml \f[R] .fi .SH CONFIGURATION .PP Configuration of \f[V]laurel\f[R] itself is done through a single configuration file in TOML format. .SS main section .PP This section contains basic operation parameters. .IP \[bu] 2 \f[V]user\f[R]: \f[V]laurel\f[R] is started as \f[V]root\f[R] by \f[V]auditd\f[R], but it drops to a dedicated user as soon as possible. Default: unset .IP \[bu] 2 \f[V]directory\f[R]: The base directory into which all files are written. Default: \f[V].\f[R] (current directory) .IP \[bu] 2 \f[V]statusreport-period\f[R]: How often stats are written to Syslog, in seconds. Default: unset .SS \f[V][auditlog]\f[R] section .PP This section describes the main audit log file. \f[V]laurel\f[R] performs its own log file rotation, just like \f[V]auditd(8)\f[R]. .IP \[bu] 2 \f[V]file\f[R]: Filename for the audit log file. Default: \f[V]audit.log\f[R] .IP \[bu] 2 \f[V]size\f[R]: Size in bytes after which the log file is rotated. Default: 10MiB .IP \[bu] 2 \f[V]generations\f[R]: Number of generations to keep after rotation. Default: 5 .IP \[bu] 2 \f[V]read-users\f[R]: List of users that are granted read access to the log file using POSIX ACLs. Default: empty .IP \[bu] 2 \f[V]line-prefix\f[R]: A string that is prepended to every line. Default: unset .SS \f[V][transform]\f[R] section .IP \[bu] 2 \f[V]execve-argv\f[R]: The list of \f[V]EXECVE.a*\f[R] fields are transformed to an \f[V]ARGV\f[R] list or \f[V]ARGV_STR\f[R] string. Set to \f[V]array\f[R], \f[V]string\f[R] (or both). Default: \f[V]array\f[R] .IP \[bu] 2 \f[V]execve-argv-limit-bytes\f[R]: Arguments are cut out of the middle long argument lists in \f[V]EXECVE.ARGV\f[R] or \f[V]EXECVE.ARGV_STR\f[R] so that this limit is not exceeded. Default: unset .SS \f[V][translate]\f[R] section .PP Options that can be configured here correspond to what \f[V]auditd(8)\f[R] does when configured with \f[V]log_format=ENRICHED\f[R]. .IP \[bu] 2 \f[V]userdb\f[R]: Add translations for \f[V]uid\f[R] and \f[V]gid\f[R] fields. Default: false .IP \[bu] 2 \f[V]universal\f[R]: Add translations for everything else: \f[V]SYSCALL.arch\f[R], \f[V]SYSCALL.syscall\f[R], \f[V]SOCKADDR.saddr\f[R] .SS \f[V][enrich]\f[R] section .PP Options that can be configured here actually add information to events .IP \[bu] 2 \f[V]execve-env\f[R]: A list of environment variables to dump for \f[V]exec\f[R] events. Default: \f[V][\[dq]LD_PRELOAD\[dq], \[dq]LD_LIBRARY_PATH\[dq]]\f[R] .IP \[bu] 2 \f[V]container\f[R]: Add container information for processes running within container runtimes. Default: true .IP \[bu] 2 \f[V]pid\f[R]: Add context information for process IDs. Default: true .IP \[bu] 2 \f[V]script\f[R]: If an \f[V]exec\f[R] syscall spawns a script (as opposed to a binary), add a \f[V]SCRIPT\f[R] entry to the \f[V]SYSCALL\f[R] record. A script is assumed if the first \f[V]PATH\f[R] entry does not correspond to file mentioned in \f[V]SYSCALL.exe\f[R]. Default: true .IP \[bu] 2 \f[V]parent-info\f[R]: Add \f[V]PARENT_INFO\f[R] record corresponding to \f[V]SYSCALL.ppid\f[R]. Deprecated, use \f[V]pid\f[R] instead in new setups. Default: false .SS \f[V][label-process]\f[R] section .PP Labels can be attached to processes and are added to any event associated with those processes. These labels can be propagated from parent to child processes. .IP \[bu] 2 \f[V]label-exe. = \f[R]: Regular expressions/label mappings applied to binary executables (\f[V]SYSCALL.exe\f[R]) on \f[V]exec\f[R] calls. Default: none .IP \[bu] 2 \f[V]label-script. = \f[R]: Regular expressions/label mappings applied to scripts (\f[V]SYSCALL.SCRIPT\f[R], see \f[V]enrich.script\f[R] description above) on \f[V]exec\f[R] calls. Default: none .IP \[bu] 2 \f[V]label-keys\f[R]: A list of keys that are applied as a process label, see \f[V]auditctl(8)\f[R]\[cq]s \f[V]-k\f[R] option. Default: none .IP \[bu] 2 \f[V]unlabel-exe. = \f[R]: Like \f[V]label-exe\f[R], but for removing labels .IP \[bu] 2 \f[V]unlabel-script. = \f[R]: Like \f[V]label-script\f[R], but for removing labels .IP \[bu] 2 \f[V]propagate-labels\f[R]: List of labels that are propagated to child processes. Default: empty .SS \f[V][filter]\f[R] section .PP Filters make \f[V]laurel\f[R] drop entire events from the log file while still using them for internal processing such as process tracking. .IP \[bu] 2 \f[V]filter-keys\f[R]: A list of strings that are matched against \f[V]SYSCALL.key\f[R] to drop the event. Default: empty .IP \[bu] 2 \f[V]filter-labels\f[R]: A list of strings that are matched against process labels. Default: empty .SH AUTHORS .IP \[bu] 2 Hilko Bengen <> .IP \[bu] 2 Sergej Schmidt <>