<?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>