<?xml version="1.0" encoding="iso-8859-1"?> <!-- The FreeBSD Documentation Project $FreeBSD$ --> <!-- Need more documentation on praudit, auditreduce, etc. Plus more info on the triggers from the kernel (log rotation, out of space, etc). And the /dev/audit special file if we choose to support that. Could use some coverage of integrating MAC with Event auditing and perhaps discussion on how some companies or organizations handle auditing and auditing requirements. --> <chapter id="audit"> <chapterinfo> <authorgroup> <author> <firstname>Tom</firstname> <surname>Rhodes</surname> <contrib>Written by </contrib> </author> <author> <firstname>Robert</firstname> <surname>Watson</surname> </author> </authorgroup> </chapterinfo> <title>Security Event Auditing</title> <sect1 id="audit-synopsis"> <title>Synopsis</title> <indexterm><primary>AUDIT</primary></indexterm> <indexterm> <primary>Security Event Auditing</primary> <see>MAC</see> </indexterm> <para>The &os; operating system includes support for fine-grained security event auditing. Event auditing allows the reliable, fine-grained, and configurable logging of a variety of security-relevant system events, including logins, configuration changes, and file and network access. These log records can be invaluable for live system monitoring, intrusion detection, and postmortem analysis. &os; implements &sun;'s published <acronym>BSM</acronym> API and file format, and is interoperable with both &sun;'s &solaris; and &apple;'s &macos; X audit implementations.</para> <para>This chapter focuses on the installation and configuration of Event Auditing. It explains audit policies, and provides an example audit configuration.</para> <para>After reading this chapter, you will know:</para> <itemizedlist> <listitem> <para>What Event Auditing is and how it works.</para> </listitem> <listitem> <para>How to configure Event Auditing on &os; for users and processes.</para> </listitem> <listitem> <para>How to review the audit trail using the audit reduction and review tools.</para> </listitem> </itemizedlist> <para>Before reading this chapter, you should:</para> <itemizedlist> <listitem> <para>Understand &unix; and &os; basics (<xref linkend="basics"/>).</para> </listitem> <listitem> <para>Be familiar with the basics of kernel configuration/compilation (<xref linkend="kernelconfig"/>).</para> </listitem> <listitem> <para>Have some familiarity with security and how it pertains to &os; (<xref linkend="security"/>).</para> </listitem> </itemizedlist> <warning> <para>The audit facility has some known limitations which include that not all security-relevant system events are currently auditable, and that some login mechanisms, such as X11-based display managers and third party daemons, do not properly configure auditing for user login sessions.</para> <para>The security event auditing facility is able to generate very detailed logs of system activity: on a busy system, trail file data can be very large when configured for high detail, exceeding gigabytes a week in some configurations. Administrators should take into account disk space requirements associated with high volume audit configurations. For example, it may be desirable to dedicate a file system to the <filename class="directory">/var/audit</filename> tree so that other file systems are not affected if the audit file system becomes full.</para> </warning> </sect1> <sect1 id="audit-inline-glossary"> <title>Key Terms in This Chapter</title> <para>Before reading this chapter, a few key audit-related terms must be explained:</para> <itemizedlist> <listitem> <para><emphasis>event</emphasis>: An auditable event is any event that can be logged using the audit subsystem. Examples of security-relevant events include the creation of a file, the building of a network connection, or a user logging in. Events are either <quote>attributable</quote>, meaning that they can be traced to an authenticated user, or <quote>non-attributable</quote> if they cannot be. Examples of non-attributable events are any events that occur before authentication in the login process, such as bad password attempts.</para> </listitem> <listitem> <para><emphasis>class</emphasis>: Event classes are named sets of related events, and are used in selection expressions. Commonly used classes of events include <quote>file creation</quote> (fc), <quote>exec</quote> (ex) and <quote>login_logout</quote> (lo).</para> </listitem> <listitem> <para><emphasis>record</emphasis>: A record is an audit log entry describing a security event. Records contain a record event type, information on the subject (user) performing the action, date and time information, information on any objects or arguments, and a success or failure condition.</para> </listitem> <listitem> <para><emphasis>trail</emphasis>: An audit trail, or log file, consists of a series of audit records describing security events. Typically, trails are in roughly chronological order with respect to the time events completed. Only authorized processes are allowed to commit records to the audit trail.</para> </listitem> <listitem> <para><emphasis>selection expression</emphasis>: A selection expression is a string containing a list of prefixes and audit event class names used to match events.</para> </listitem> <listitem> <para><emphasis>preselection</emphasis>: The process by which the system identifies which events are of interest to the administrator in order to avoid generating audit records describing events that are not of interest. The preselection configuration uses a series of selection expressions to identify which classes of events to audit for which users, as well as global settings that apply to both authenticated and unauthenticated processes.</para> </listitem> <listitem> <para><emphasis>reduction</emphasis>: The process by which records from existing audit trails are selected for preservation, printing, or analysis. Likewise, the process by which undesired audit records are removed from the audit trail. Using reduction, administrators can implement policies for the preservation of audit data. For example, detailed audit trails might be kept for one month, but after that, trails might be reduced in order to preserve only login information for archival purposes.</para> </listitem> </itemizedlist> </sect1> <sect1 id="audit-install"> <title>Installing Audit Support</title> <para>User space support for Event Auditing is installed as part of the base &os; operating system. Kernel support for Event Auditing is compiled in by default, but support for this feature must be explicitly compiled into the custom kernel by adding the following line to the kernel configuration file:</para> <programlisting>options AUDIT</programlisting> <para>Rebuild and reinstall the kernel via the normal process explained in <xref linkend="kernelconfig"/>.</para> <para>Once an audit-enabled kernel is built, installed, and the system has been rebooted, enable the audit daemon by adding the following line to &man.rc.conf.5;:</para> <programlisting>auditd_enable="YES"</programlisting> <para>Audit support must then be started by a reboot, or by manually starting the audit daemon:</para> <programlisting>service auditd start</programlisting> </sect1> <sect1 id="audit-config"> <title>Audit Configuration</title> <para>All configuration files for security audit are found in <filename class="directory">/etc/security</filename>. The following files must be present before the audit daemon is started:</para> <itemizedlist> <listitem> <para><filename>audit_class</filename> - Contains the definitions of the audit classes.</para> </listitem> <listitem> <para><filename>audit_control</filename> - Controls aspects of the audit subsystem, such as default audit classes, minimum disk space to leave on the audit log volume, maximum audit trail size, etc.</para> </listitem> <listitem> <para><filename>audit_event</filename> - Textual names and descriptions of system audit events, as well as a list of which classes each event is in.</para> </listitem> <listitem> <para><filename>audit_user</filename> - User-specific audit requirements, which are combined with the global defaults at login.</para> </listitem> <listitem> <para><filename>audit_warn</filename> - A customizable shell script used by &man.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.</para> </listitem> </itemizedlist> <warning> <para>Audit configuration files should be edited and maintained carefully, as errors in configuration may result in improper logging of events.</para> </warning> <sect2> <title>Event Selection Expressions</title> <para>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, each with a prefix indicating whether matching records should be accepted or ignored, and optionally to indicate if the entry is intended to match successful or failed operations. Selection expressions are evaluated from left to right, and two expressions are combined by appending one onto the other.</para> <para>The following list contains the default audit event classes present in <filename>audit_class</filename>:</para> <itemizedlist> <listitem> <para><literal>all</literal> - <emphasis>all</emphasis> - Match all event classes.</para> </listitem> <listitem> <para><literal>ad</literal> - <emphasis>administrative</emphasis> - Administrative actions performed on the system as a whole.</para> </listitem> <listitem> <para><literal>ap</literal> - <emphasis>application</emphasis> - Application defined action.</para> </listitem> <listitem> <para><literal>cl</literal> - <emphasis>file close</emphasis> - Audit calls to the <function>close</function> system call.</para> </listitem> <listitem> <para><literal>ex</literal> - <emphasis>exec</emphasis> - Audit program execution. Auditing of command line arguments and environmental variables is controlled via &man.audit.control.5; using the <literal>argv</literal> and <literal>envv</literal> parameters to the <literal>policy</literal> setting.</para> </listitem> <listitem> <para><literal>fa</literal> - <emphasis>file attribute access</emphasis> - Audit the access of object attributes such as &man.stat.1;, &man.pathconf.2; and similar events.</para> </listitem> <listitem> <para><literal>fc</literal> - <emphasis>file create</emphasis> - Audit events where a file is created as a result.</para> </listitem> <listitem> <para><literal>fd</literal> - <emphasis>file delete</emphasis> - Audit events where file deletion occurs.</para> </listitem> <listitem> <para><literal>fm</literal> - <emphasis>file attribute modify</emphasis> - Audit events where file attribute modification occurs, such as &man.chown.8;, &man.chflags.1;, &man.flock.2;, etc.</para> </listitem> <listitem> <para><literal>fr</literal> - <emphasis>file read</emphasis> - Audit events in which data is read, files are opened for reading, etc.</para> </listitem> <listitem> <para><literal>fw</literal> - <emphasis>file write</emphasis> - Audit events in which data is written, files are written or modified, etc.</para> </listitem> <listitem> <para><literal>io</literal> - <emphasis>ioctl</emphasis> - Audit use of the &man.ioctl.2; system call.</para> </listitem> <listitem> <para><literal>ip</literal> - <emphasis>ipc</emphasis> - Audit various forms of Inter-Process Communication, including POSIX pipes and System V <acronym>IPC</acronym> operations.</para> </listitem> <listitem> <para><literal>lo</literal> - <emphasis>login_logout</emphasis> - Audit &man.login.1; and &man.logout.1; events occurring on the system.</para> </listitem> <listitem> <para><literal>na</literal> - <emphasis>non attributable</emphasis> - Audit non-attributable events.</para> </listitem> <listitem> <para><literal>no</literal> - <emphasis>invalid class</emphasis> - Match no audit events.</para> </listitem> <listitem> <para><literal>nt</literal> - <emphasis>network</emphasis> - Audit events related to network actions, such as &man.connect.2; and &man.accept.2;.</para> </listitem> <listitem> <para><literal>ot</literal> - <emphasis>other</emphasis> - Audit miscellaneous events.</para> </listitem> <listitem> <para><literal>pc</literal> - <emphasis>process</emphasis> - Audit process operations, such as &man.exec.3; and &man.exit.3;.</para> </listitem> </itemizedlist> <para>These audit event classes may be customized by modifying the <filename>audit_class</filename> and <filename>audit_ event</filename> configuration files.</para> <para>Each audit class in the list is 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.</para> <itemizedlist> <listitem> <para>(none) Audit both successful and failed instances of the event.</para> </listitem> <listitem> <para><literal>+</literal> Audit successful events in this class.</para> </listitem> <listitem> <para><literal>-</literal> Audit failed events in this class.</para> </listitem> <listitem> <para><literal>^</literal> Audit neither successful nor failed events in this class.</para> </listitem> <listitem> <para><literal>^+</literal> Do not audit successful events in this class.</para> </listitem> <listitem> <para><literal>^-</literal> Do not audit failed events in this class.</para> </listitem> </itemizedlist> <para>The following example selection string selects both successful and failed login/logout events, but only successful execution events:</para> <programlisting>lo,+ex</programlisting> </sect2> <sect2> <title>Configuration Files</title> <para>In most cases, administrators will need to modify only two files when configuring the audit system: <filename>audit_ control</filename> and <filename>audit_user</filename>. The first controls system-wide audit properties and policies; the second may be used to fine-tune auditing by user.</para> <sect3 id="audit-auditcontrol"> <title>The <filename>audit_control</filename> File</title> <para>A number of defaults for the audit subsystem are specified in <filename>audit_control</filename>:</para> <programlisting>dir:/var/audit flags:lo minfree:20 naflags:lo policy:cnt filesz:0</programlisting> <para>The <option>dir</option> 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.</para> <para>The <option>flags</option> field sets the system-wide default preselection mask for attributable events. In the example above, successful and failed login and logout events are audited for all users.</para> <para>The <option>minfree</option> entry defines the minimum percentage of free space for the file system where the audit trail is stored. When this threshold is exceeded, a warning will be generated. The above example sets the minimum free space to twenty percent.</para> <para>The <option>naflags</option> entry specifies audit classes to be audited for non-attributed events, such as the login process and system daemons.</para> <para>The <option>policy</option> entry specifies a comma-separated list of policy flags controlling various aspects of audit behavior. The default <literal>cnt</literal> flag indicates that the system should continue running despite an auditing failure (this flag is highly recommended). Another commonly used flag is <literal>argv</literal>, which causes command line arguments to the &man.execve.2; system call to be audited as part of command execution.</para> <para>The <option>filesz</option> entry specifies the maximum size in bytes to allow an audit trail file to grow to before automatically terminating and rotating the trail file. The default, 0, disables automatic log rotation. If the requested file size is non-zero and below the minimum 512k, it will be ignored and a log message will be generated.</para> </sect3> <sect3 id="audit-audituser"> <title>The <filename>audit_user</filename> File</title> <para>The administrator can specify further audit requirements for specific users in <filename>audit_user</filename>. Each line configures auditing for a user via two fields: the first is the <literal>alwaysaudit</literal> field, which specifies a set of events that should always be audited for the user, and the second is the <literal>neveraudit</literal> field, which specifies a set of events that should never be audited for the user.</para> <para>The following example <filename>audit_user</filename> audits login/logout events and successful command execution for <username>root</username>, and audits file creation and successful command execution for <username>www</username>. If used with the above example <filename>audit_control</filename>, the <literal>lo</literal> entry for <username>root</username> is redundant, and login/logout events will also be audited for <username>www</username>.</para> <programlisting>root:lo,+ex:no www:fc,+ex:no</programlisting> </sect3> </sect2> </sect1> <sect1 id="audit-administration"> <title>Administering the Audit Subsystem</title> <sect2> <title>Viewing Audit Trails</title> <para>Audit trails are stored in the BSM binary format, so tools must be used to modify or convert to text. The &man.praudit.1; command converts trail files to a simple text format; the &man.auditreduce.1; command may be used to reduce the audit trail file for analysis, archiving, or printing purposes. A variety of selection parameters are supported by &man.auditreduce.1;, including event type, event class, user, date or time of the event, and the file path or object acted on.</para> <para>For example, &man.praudit.1; will dump the entire contents of a specified audit log in plain text:</para> <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen> <para>Where <filename><replaceable>AUDITFILE</replaceable></filename> is the audit log to dump.</para> <para>Audit trails consist of a series of audit records made up of tokens, which &man.praudit.1; prints sequentially one per line. Each token is of a specific type, such as <literal>header</literal> holding an audit record header, or <literal>path</literal> holding a file path from a name lookup. The following is an example of an <literal>execve</literal> event:</para> <programlisting>header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec exec arg,finger,doug path,/usr/bin/finger attribute,555,root,wheel,90,24918,104944 subject,robert,root,wheel,root,wheel,38439,38032,42086,128.232.9.100 return,success,0 trailer,133</programlisting> <para>This audit represents a successful <literal>execve</literal> call, in which the command <literal>finger doug</literal> has been run. The arguments token contains both the processed command line presented by the shell to the kernel. The <literal>path</literal> token holds the path to the executable as looked up by the kernel. The <literal>attribute</literal> token describes the binary, and in particular, includes the file mode which can be used to determine if the application was setuid. The <literal>subject</literal> token describes the subject process, and stores in sequence the audit user ID, effective user ID and group ID, real user ID and group ID, process ID, session ID, port ID, and login address. Notice that the audit user ID and real user ID differ: the user <username>robert</username> has switched to the <username>root</username> account before running this command, but it is audited using the original authenticated user. Finally, the <literal>return</literal> token indicates the successful execution, and the <literal>trailer</literal> concludes the record.</para> <para><acronym>XML</acronym> output format is also supported by &man.praudit.1;, and can be selected using <option>-x</option>.</para> </sect2> <sect2> <title>Reducing Audit Trails</title> <para>Since audit logs may be very large, an administrator will likely want to select a subset of records for using, such as records associated with a specific user:</para> <screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE | praudit</userinput></screen> <para>This will select all audit records produced for <username>trhodes</username> stored in <filename><replaceable>AUDITFILE</replaceable></filename>.</para> </sect2> <sect2> <title>Delegating Audit Review Rights</title> <para>Members of the <groupname>audit</groupname> group are given permission to read audit trails in <filename class="directory">/var/audit</filename>; by default, this group is empty, so only the <username>root</username> user may read audit trails. Users may be added to the <groupname>audit</groupname> group in order to delegate audit review rights to the user. As the ability to track audit log contents provides significant insight into the behavior of users and processes, it is recommended that the delegation of audit review rights be performed with caution.</para> </sect2> <sect2> <title>Live Monitoring Using Audit Pipes</title> <para>Audit pipes are cloning pseudo-devices in the device file system which allow applications to tap the live audit record stream. This is primarily of interest to authors of intrusion detection and system monitoring applications. However, for the administrator the audit pipe device is a convenient way to allow live monitoring without running into problems with audit trail file ownership or log rotation interrupting the event stream. To track the live audit event stream, use the following command line:</para> <screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen> <para>By default, audit pipe device nodes are accessible only to the <username>root</username> user. To make them accessible to the members of the <groupname>audit</groupname> group, add a <literal>devfs</literal> rule to <filename>devfs.rules</filename>:</para> <programlisting>add path 'auditpipe*' mode 0440 group audit</programlisting> <para>See &man.devfs.rules.5; for more information on configuring the devfs file system.</para> <warning> <para>It is easy to produce audit event feedback cycles, in which the viewing of each audit event results in the generation of more audit events. For example, if all network I/O is audited, and &man.praudit.1; is run from an SSH session, then a continuous stream of audit events will be generated at a high rate, as each event being printed will generate another event. It is advisable to run &man.praudit.1; on an audit pipe device from sessions without fine-grained I/O auditing in order to avoid this happening.</para> </warning> </sect2> <sect2> <title>Rotating Audit Trail Files</title> <para>Audit trails are written to only by the kernel, and managed only by the audit daemon, &man.auditd.8;. Administrators should not attempt to use &man.newsyslog.conf.5; or other tools to directly rotate audit logs. Instead, the &man.audit.8; management tool may be used to shut down auditing, reconfigure the audit system, and perform log rotation. The following command causes the audit daemon to create a new audit log and signal the kernel to switch to using the new log. The old log will be terminated and renamed, at which point it may then be manipulated by the administrator.</para> <screen>&prompt.root; <userinput>audit -n</userinput></screen> <warning> <para>If &man.auditd.8; is not currently running, this command will fail and an error message will be produced.</para> </warning> <para>Adding the following line to <filename>/etc/crontab</filename> will force the rotation every twelve hours from &man.cron.8;:</para> <programlisting>0 */12 * * * root /usr/sbin/audit -n</programlisting> <para>The change will take effect once you have saved the new <filename>/etc/crontab</filename>.</para> <para>Automatic rotation of the audit trail file based on file size is possible using <option>filesz</option> in &man.audit.control.5;, and is described in the configuration files section of this chapter.</para> </sect2> <sect2> <title>Compressing Audit Trails</title> <para>As audit trail files can become very large, it is often desirable to compress or otherwise archive trails once they have been closed by the audit daemon. The <filename>audit_warn</filename> script can be used to perform customized operations for a variety of audit-related events, including the clean termination of audit trails when they are rotated. For example, the following may be added to the <filename>audit_warn</filename> script to compress audit trails on close:</para> <programlisting># # Compress audit trail files on close. # if [ "$1" = closefile ]; then gzip -9 $2 fi</programlisting> <para>Other archiving activities might include copying trail files to a centralized server, deleting old trail files, or reducing the audit trail to remove unneeded records. The script will be run only when audit trail files are cleanly terminated, so will not be run on trails left unterminated following an improper shutdown.</para> </sect2> </sect1> </chapter>