6.4.5.6 Audit Log Filtering

Note

This section describes how audit log filtering works if the
audit log plugin and the accompanying audit tables and UDFs
are installed. If the plugin is installed but not the
accompanying audit tables and UDFs, the plugin operates in
legacy filtering mode, described in
Section 6.4.5.8, “Legacy Mode Audit Log Filtering”. Legacy mode is
filtering behavior as it was prior to MySQL 5.7.13; that is,
before the introduction of rule-based filtering.

The audit log plugin has the capability of controlling logging
of audited events by filtering them:

Audited events can be filtered using these characteristics:

User account

Audit event class

Audit event subclass

Value of event fields such as those that indicate
operation status or SQL statement executed

Audit filtering is rule based:

A filter definition creates a set of auditing rules.
Definitions can be configured to include or exclude
events for logging based on the characteristics just
described.

Filter rules have the capability of blocking (aborting)
execution of qualifying events, in addition to existing
capabilities for event logging.

Multiple filters can be defined, and any given filter
can be assigned to any number of user accounts.

It is possible to define a default filter to use with
any user account that has no explicitly assigned filter.

Audit filters can be defined, displayed, and modified using
an SQL interface based on user-defined functions (UDFs).

Audit filter definitions are stored in the tables in the
mysql system database.

Within a given session, the value of the read-only
audit_log_filter_id system
variable indicates whether a filter has been assigned to the
session.

Note

By default, rule-based audit log filtering logs no auditable
events for any users. To log all auditable events for all
users, use the following statements, which create a simple
filter to enable logging and assign it to the default account:

To use any filtering function, a user must possess the
SUPER privilege or an error
occurs. To grant the SUPER
privilege to a user account, use this statement:

GRANT SUPER ON *.* TO user;

Alternatively, should you prefer to avoid granting the
SUPER privilege while still
permitting users to access specific filtering functions,
“wrapper” stored programs can be defined. This
technique is described in the context of keyring UDFs in
Using General-Purpose Keyring Functions; it can be adapted for
use with filtering UDFs.

The audit_log plugin operates in legacy
mode if it is installed but the accompanying audit tables
and functions are not created. The plugin writes these
messages to the error log at server startup:

[Warning] Plugin audit_log reported: 'Failed to open the audit log filter tables.'
[Warning] Plugin audit_log reported: 'Audit Log plugin supports a filtering,
which has not been installed yet. Audit Log plugin will run in the legacy
mode, which will be disabled in the next release.'

By default, no accounts have a filter assigned, so no
processing of auditable events occurs for any account.

Suppose that instead you want the default to be to log only
connection-related activity (for example, to see connect,
change-user, and disconnect events, but not the SQL statements
users execute while connected). To achieve this, define a
filter (shown here named log_conn_events)
that enables logging only of events in the
connection class, and assign that filter to
the default account, represented by the %
account name:

Filtering of current sessions for the account remains
unaffected. Subsequent connections from the account are
filtered using the new filter. For the filter shown here,
that means no logging for new connections from
user1@localhost.

For audit log filtering, user name and host name comparisons
are case-sensitive. This differs from comparisons for
privilege checking, for which host name comparisons are not
case-sensitive.

To remove a filter, do this:

SELECT audit_log_filter_remove_filter('log_nothing');

Removing a filter also unassigns it from any users to whom it
has been assigned, including any current sessions for those
users.

The filtering UDFs just described affect audit filtering
immediately and update the audit log tables in the
mysql system database that store filters
and user accounts (see Audit Log Tables). It
is also possible to modify the audit log tables directly using
statements such as INSERT,
UPDATE, and
DELETE, but such changes do not
affect filtering immediately. To flush your changes and make
them operational, call
audit_log_filter_flush():

SELECT audit_log_filter_flush();

Warning

audit_log_filter_flush()
should be used only after modifying the audit tables
directly, to force reloading all filters. Otherwise, this
function should be avoided. It is, in effect, a simplified
version of unloading and reloading the
audit_log plugin with
UNINSTALL PLUGIN plus
INSTALL PLUGIN.

audit_log_filter_flush()
affects all current sessions and detaches them from their
previous filters. Current sessions are no longer logged
unless they disconnect and reconnect, or execute a
change-user operation.

To determine whether a filter has been assigned to the current
session, check the session value of the read-only
audit_log_filter_id system
variable. If the value is 0, no filter is assigned. A nonzero
value indicates the internally maintained ID of the assigned
filter: