The audit_class File

The audit_class file contains definitions of the existing audit classes. Audit classes are groups of audit events. Each class has an associated audit flag, which is the short name that stands for the class. You use the short name in the audit_control file, optionally with a + or - prefix, to preselect the classes whose events you want to audit. The root user, or an administrator in an equivalent role, can define new audit classes, rename existing classes, or otherwise edit existing classes by using vi, ed, or some other editor. See the audit_class(4) man page for more information. For descriptions of the audit flags, see "Definitions of Audit Flags".

The audit_control File

An audit_control file on each machine is read by the audit daemon (see the audit_control(4) man page). The audit_control file is located in the /etc/security directory. Each machine has its own local audit_control file so that every machine can mount their audit file systems from different locations or in a different order. For example, the primary audit file system for machineA might be the secondary audit file system for machineB.

You specify four kinds of information in the audit_control file:

• The audit flags line (flags:) contains the audit flags that preselect which classes of events are audited for all users on the machine. The audit flags specified here are referred to as the machine-wide audit flags or the machine-wide audit preselection mask. Audit flags are separated by commas, with no spaces.

• The nonattributable flags line (naflags:) contains the audit flags that preselect which classes of events are audited when an action cannot be attributed to a specific user. The flags are separated by commas, with no spaces.

• The audit threshold line (minfree:) defines the minimum free-space level for all audit file systems. The minfree percentage must be greater than or equal to 0. The default is 20 percent.

• The directory definition lines (dir:) define which audit file systems and directories the machine will use to store its audit log files. You can define one or more directory definition lines. The order of the dir: lines is significant. The auditd daemon creates audit files in the directories in the specified order (see the audit(1M) man page). The first directory is the primary audit directory for the machine. The second directory is the secondary audit directory where the audit daemon creates audit trail files when the first directory becomes full, and so forth.

You create an audit_control file during the configuration process on each machine.

When you make changes to the audit_control file, you then run the audit -s to instruct the audit daemon to reread the file.

Note - The audit -scommand does not change the preselection mask for existing processes. Use auditconfig, setaudit (see the getuid(2) man page), or auditon for existing processes.

Sample audit_control File

The following is a sample audit_control file for the machine dopey. dopey uses two audit file systems on the audit server blinken, and a third audit file system that is mounted from the second audit server winken. The third file system is used only when the audit file systems on blinken become full or unavailable. The minfree value of 20 percent specifies that the warning script is run when the file systems are 80 percent filled and the audit data for the current machine will be stored in the next available audit directory, if any (see the audit_warn(1M) man page). The flags specify that all logins and administrative operations are to be audited (whether or not they succeed), and that failures of all types, except failures to create a file system object, are to be audited.

flags:lo,ad,-all,^-fc
naflags:lo,nt
minfree:20
dir:/etc/security/audit/blinken/files
dir:/etc/security/audit/blinken.1/files
#
# Audit filesystem used when blinken fills up
#
dir:/etc/security/audit/winken 

The audit_data File

When the auditd daemon starts on each machine, it creates the file /etc/security/audit_data. The format of the file consists of a single entry with the two fields separated by a colon (see the audit_data(4) man page). The first field is the audit daemon's process ID. The second field is the path name of the audit file to which the audit daemon is currently writing audit records. Here is an example:

# cat /etc/security/audit_data
116:/etc/security/audit/blinken.1/files/19990320100002.not_terminated.dopey

The audit_event File

The audit_event file, located in the /etc/security directory, contains the default event-to-class mappings (see the audit_event(4) man page). You can edit this file to change the class mappings. However, if you do so, you must reboot the system or run auditconfig -conf to read the changed mappings into the kernel.

The audit_startup Script

Auditing is enabled by starting the audit daemon, auditd. You can start the audit daemon by executing /usr/sbin/auditd as root or in an equivalent role. See the auditd(1M) man page.

The existence of the file /etc/security/audit_startup causes the audit daemon to be run automatically when the system enters multiuser mode. This file is an executable script that is invoked as part of the startup sequence, just prior to the execution of the audit daemon (see the audit_startup(1M) man page). A default audit_startup script that automatically configures the event-to-class mappings and sets the audit policies is created during the BSM package installation.

The audit_user File

To audit some users differently from others, you can edit the audit_user file to add audit flags for individual users. If specified, these flags are combined with the system-wide flags in the audit_control file to determine which classes of events to audit for that user. The flags that you add to the user's entry in the audit_user file modify the defaults from the audit_control file in two ways:

• By specifying a set of event classes that are never to be audited for this user

• By specifying a set of event classes that are always to be audited for this user

Each user entry in the audit_user file contains three fields.

• The username field

• The always-audit field

• The never-audit field

The audit fields are processed in sequence. Auditing is enabled by the always-audit field and turned off by the never-audit field.

Note - Avoid the common mistake of leaving the all audit flag in the never-audit field. This mistake causes all auditing to be turned off for that user, which overrides the flags that are set in the always-audit field.

Using the never-audit flags for a user is not the same as removing classes from the always-audit set. For example, suppose you want to audit everything for user tamiko for except for successful reads of file system objects. This strategy audits almost everything for a user, while generating only about three-quarters of the audit data that would be produced if all data reads were audited. You also want to apply the system defaults to tamiko. Here are two possible audit_user entries:

The correct entry:

tamiko:all,^+fr:

The incorrect entry:

tamiko:all:+fr

The first example means, "always audit everything except for successful file-reads." The second example means, "always audit everything, but never audit successful file-reads." The second example is incorrect because it overrides the system default. The first example achieves the desired effect: the system defaults apply, as well as what is specified in the audit_user entry.

Note - Successful events and failed events are treated separately, so a process can generate more audit records when an error occurs than when an event is successful.

The audit_warn Script

Whenever the audit daemon encounters an unusual condition while writing audit records, it invokes the /etc/security/audit_warn script. See the audit_warn(1M) man page. You can customize this script for your site to warn of conditions that might require manual intervention, or you could specify how to handle them automatically. For all error conditions, audit_warn writes a message to the console and sends a message to the audit_warn mail alias. You should set up this alias when you enable auditing.

When audit daemon detects the following conditions, it invokes the audit_warn script.

• An audit directory has become more full than the minfree value allows. The minfree value or soft limit is a percentage of the space available on an audit file system.

  The audit_warn script is invoked with the string soft and the name of the directory whose available space has gone below the minimum value. The audit daemon switches automatically to the next suitable directory and writes the audit files there until this new directory reaches its minfree limit. The audit daemon then goes to each remaining directory in the order that is listed in the audit_control file, and writes audit records until each directory is at its minfree limit.

• All the audit directories have reached the minfree threshold.

  The audit_warn script is invoked with the string allsoft. A message is written to the console and mail is sent to the audit_warn alias.

  When all audit directories that are listed in the audit_control file have reached their minfree threshold, the audit daemon switches back to the first directory, and writes audit records until the directory becomes completely full.

• An audit directory has become completely full with no space remaining.

  The audit_warn script is invoked with the string hard and the name of the directory. A message is written to the console and mail is sent to the audit_warn alias.

  The audit daemon switches automatically to the next suitable directory with any space available, if any. The audit daemon goes to each remaining directory in the order that is listed in the audit_control file, and writes audit records until each directory is full.

• All the audit directories are completely full. The audit_warn script is invoked with the string allhard as an argument.

  In the default configuration, a message is written to the console and mail is sent to the audit_warn alias. The processes that generate audit records are suspended. The audit daemon goes into a loop, waiting for space to become available, and resumes processing audit records when that happens. While audit records are not being processed, no auditable activities occur. Every process that attempts to generate an audit record is suspended. For this reason, you should set up a separate audit administration account that could operate without any auditing enabled. Then, you could continue operations without being suspended.

• An internal error occurs, such as:

  • Another audit daemon process is already running (string ebusy)

  • A temporary file cannot be used (string tmpfile)

  • The auditsvc() system call fails (string auditsvc)

  • A signal was received during auditing shutdown (string postsigterm)

  Mail is sent to the audit_warn alias.

• A problem is discovered with the syntax of the audit_control file. By default, mail is sent to the audit_warn alias and a message is sent to the console.