path: root/en_US.ISO8859-1/books/handbook/audit/chapter.xml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!--
     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>/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>/etc/rc.d/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 <application>auditd</application> 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>The <filename>audit_control</filename> file specifies a number
	  of defaults for the audit subsystem.  Viewing the contents of this
	  file, we see the following:</para>

	<programlisting>dir:/var/audit
flags:lo
minfree:20
naflags:lo
policy:cnt
filesz:0</programlisting>

	<para>The <option>dir</option> option 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> option 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> option specifies audit classes to
	  be audited for non-attributed events, such as the login process
	  and system daemons.</para>

	<para>The <option>policy</option> option 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> option 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 <filename>audit_user</filename> file permits the
	  administrator to specify further audit requirements for specific
	  users.
	  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> file
	  audits login/logout events and successful command execution for
	  the <username>root</username> user, and audits file creation and successful command
	  execution for the <username>www</username> user.
	  If used with the example <filename>audit_control</filename> file
	  above, the <literal>lo</literal> entry for <username>root</username>
	  is redundant, and login/logout events will also be audited for the
	  <username>www</username> user.</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.
	<command>auditreduce</command> supports a variety of selection
	parameters, including event type, event class, user, date or time of
	the event, and the file path or object acted on.</para>

      <para>For example, the <command>praudit</command> utility 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 <command>praudit</command> 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><command>praudit</command> also supports
	an XML output format, which can be selected using the
	<option>-x</option> argument.</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 the user
	<username>trhodes</username> stored in the
	<filename><replaceable>AUDITFILE</replaceable></filename> file.</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>/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
	  <command>praudit</command> 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, <application>auditd</application>.  Administrators
	should not attempt to use &man.newsyslog.conf.5; or other tools to
	directly rotate audit logs.  Instead, the <command>audit</command>
	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 the <application>auditd</application> daemon 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 via the <option>filesz</option> 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>