17.3. Audit Configuration

User space support for event auditing is installed as part of the base FreeBSD operating system. Kernel support is available in the GENERIC kernel by default, and auditd(8) can be enabled by adding the following line to /etc/rc.conf:

auditd_enable="YES"

Then, start the audit daemon:

# service auditd start

Users who prefer to compile a custom kernel must include the following line in their custom kernel configuration file:

options	AUDIT

17.3.1. Event Selection Expressions

Selection expressions are used in a number of places in the audit configuration to determine which events should be audited. Expressions contain a list of event classes to match. Selection expressions are evaluated from left to right, and two expressions are combined by appending one onto the other.

Table 17.1, “Default Audit Event Classes” summarizes the default audit event classes:

Table 17.1. Default Audit Event Classes
Class NameDescriptionAction
allallMatch all event classes.
aaauthentication and authorization 
adadministrativeAdministrative actions performed on the system as a whole.
apapplicationApplication defined action.
clfile closeAudit calls to the close system call.
exexecAudit program execution. Auditing of command line arguments and environmental variables is controlled via audit_control(5) using the argv and envv parameters to the policy setting.
fafile attribute accessAudit the access of object attributes such as stat(1) and pathconf(2).
fcfile createAudit events where a file is created as a result.
fdfile deleteAudit events where file deletion occurs.
fmfile attribute modifyAudit events where file attribute modification occurs, such as by chown(8), chflags(1), and flock(2).
frfile readAudit events in which data is read or files are opened for reading.
fwfile writeAudit events in which data is written or files are written or modified.
ioioctlAudit use of the ioctl system call.
ipipcAudit various forms of Inter-Process Communication, including POSIX pipes and System V IPC operations.
lologin_logoutAudit login(1) and logout(1) events.
nanon attributableAudit non-attributable events.
noinvalid classMatch no audit events.
ntnetworkAudit events related to network actions such as connect(2) and accept(2).
ototherAudit miscellaneous events.
pcprocessAudit process operations such as exec(3) and exit(3).

These audit event classes may be customized by modifying the audit_class and audit_event configuration files.

Each audit event class may be combined with a prefix indicating whether successful/failed operations are matched, and whether the entry is adding or removing matching for the class and type. Table 17.2, “Prefixes for Audit Event Classes” summarizes the available prefixes:

Table 17.2. Prefixes for Audit Event Classes
PrefixAction
+Audit successful events in this class.
-Audit failed events in this class.
^Audit neither successful nor failed events in this class.
^+Do not audit successful events in this class.
^-Do not audit failed events in this class.

If no prefix is present, both successful and failed instances of the event will be audited.

The following example selection string selects both successful and failed login/logout events, but only successful execution events:

lo,+ex

17.3.2. Configuration Files

The following configuration files for security event auditing are found in /etc/security:

  • audit_class: contains the definitions of the audit classes.

  • audit_control: controls aspects of the audit subsystem, such as default audit classes, minimum disk space to leave on the audit log volume, and maximum audit trail size.

  • audit_event: textual names and descriptions of system audit events and a list of which classes each event is in.

  • audit_user: user-specific audit requirements to be combined with the global defaults at login.

  • audit_warn: a customizable shell script used by auditd(8) to generate warning messages in exceptional situations, such as when space for audit records is running low or when the audit trail file has been rotated.

Warning:

Audit configuration files should be edited and maintained carefully, as errors in configuration may result in improper logging of events.

In most cases, administrators will only need to modify audit_control and audit_user. The first file controls system-wide audit properties and policies and the second file may be used to fine-tune auditing by user.

17.3.2.1. The audit_control File

A number of defaults for the audit subsystem are specified in audit_control:

dir:/var/audit
dist:off
flags:lo,aa
minfree:5
naflags:lo,aa
policy:cnt,argv
filesz:2M
expire-after:10M

The dir entry is used to set one or more directories where audit logs will be stored. If more than one directory entry appears, they will be used in order as they fill. It is common to configure audit so that audit logs are stored on a dedicated file system, in order to prevent interference between the audit subsystem and other subsystems if the file system fills.

If the dist field is set to on or yes, hard links will be created to all trail files in /var/audit/dist.

The flags field sets the system-wide default preselection mask for attributable events. In the example above, successful and failed login/logout events as well as authentication and authorization are audited for all users.

The minfree entry defines the minimum percentage of free space for the file system where the audit trail is stored.

The naflags entry specifies audit classes to be audited for non-attributed events, such as the login/logout process and authentication and authorization.

The policy entry specifies a comma-separated list of policy flags controlling various aspects of audit behavior. The cnt indicates that the system should continue running despite an auditing failure (this flag is highly recommended). The other flag, argv, causes command line arguments to the execve(2) system call to be audited as part of command execution.

The filesz entry specifies the maximum size for an audit trail before automatically terminating and rotating the trail file. A value of 0 disables automatic log rotation. If the requested file size is below the minimum of 512k, it will be ignored and a log message will be generated.

The expire-after field specifies when audit log files will expire and be removed.

17.3.2.2. The audit_user File

The administrator can specify further audit requirements for specific users in audit_user. Each line configures auditing for a user via two fields: the alwaysaudit field specifies a set of events that should always be audited for the user, and the neveraudit field specifies a set of events that should never be audited for the user.

The following example entries audit login/logout events and successful command execution for root and file creation and successful command execution for www. If used with the default audit_control, the lo entry for root is redundant, and login/logout events will also be audited for www.

root:lo,+ex:no
www:fc,+ex:no

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.