audisp-filter - Man Page

audisp-filter MODE CONFIG_FILE BINARY [ BINARY_ARGS ]

audisp-filter is an audit event dispatcher plugin designed to filter out specific events based on its provided configuration. Moreover, it possesses the capability to forward the remaining logs to other plugins. The plugin is universally compatible, allowing seamless integration with any existing audit plugin that expects audit messages on its standard input. Currently it supports the following arguments:

MODE

The operational mode can be either allowlist or blocklist. The mode names have the following exact meaning:

allowlist

Forward non-matching events. Drop events that match the configured ausearch expressions.

blocklist

Forward events that match the configured ausearch expressions. Drop non-matching events.

Do not infer behavior from other allow/deny list terminology; use the definitions above.

CONFIG_FILE

Path to the main configuration file containing ausearch expressions.

BINARY

Path to an external program that will consistently receive filtered audit events through its standard input.

BINARY_ARGS

Optionally, you can pass additional arguments to the external program.

Every single plugin that wants to benefit from the event filtering capability needs to create its own configuration file. It's a good practice to place this file inside the audit config directory, following the naming convention audisp-filter-pluginname.conf, for instance, audisp-filter-syslog.conf to filter audit events before sending them to syslog.

Each line within a configuration represents an ausearch-expression (5). Internally, these expressions are joined using the OR operator. Therefore, every expression is substituted with (PE || CE), where PE represents the previous expression and CE denotes the current expression being processed. Lines starting with a '#' character are treated as comments and do not influence the final rule set.

Upon the creation of an audit event, the filtering engine goes through the list of expressions, constructing the final expression representing our rule set. The event in question will be searched using this expression. The decision to forward an audit event to the configured binary depends on two factors: the operational mode of audisp-filter and whether the expression matches the ongoing event.

Filtering is event based, not record based. If any record in a multi-record audit event matches the final expression, the whole event is treated as a match. When that event is forwarded, all of its records are written to the configured binary, including companion records that did not individually match the expression.

Example 1: Do not syslog audit events containing failed openat syscalls.

First, in the plugin config, make sure that operation mode is set to allowlist, the binary points to /sbin/audisp-syslog and provide any additional arguments if needed. Next, create the plugin specific config file with the content below. Before enabling the audit plugin, always make sure the syntax is correct. This can be checked by calling audisp-filter --check path/to/config/file.

(type r= SYSCALL && syscall i= openat && success r= no)

Example 2: Forward only SERVICE_STOP events and events that contain a NETFILTER_CFG record.

Use blocklist mode and put the following expressions in the plugin specific configuration file:

type r= SERVICE_STOP
type r= NETFILTER_CFG

A NETFILTER_CFG record can be part of a multi-record event that also contains SYSCALL and PROCTITLE records with the same audit timestamp and serial. If the NETFILTER_CFG record matches, audisp-filter forwards all records in that event. A separate SERVICE_START event does not match this example and is not forwarded.

/etc/audit/plugins/filter.conf /etc/audit/auditd.conf

auditd.conf(8), ausearch-expression(5), auditd-plugins(5).

Attila Lakatos