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

<?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 xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="audit">

  <info>
    <title>Security Event Auditing</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	</personname>
	<contrib>Written by </contrib>
      </author>

      <author>
	<personname>
	  <firstname>Robert</firstname>
	  <surname>Watson</surname>
	</personname>
      </author>
    </authorgroup>
  </info>

  <sect1 xml: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 security
      event auditing.  Event auditing supports 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 Basic Security
      Module (<acronym>BSM</acronym>) Application Programming
      Interface (<acronym>API</acronym>) and file format, and is
      interoperable with the &solaris; and &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.  Not all
	security-relevant system events are auditable and some login
	mechanisms, such as <application>Xorg</application>-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 the disk space
	requirements associated with high volume audit configurations.
	For example, it may be desirable to dedicate a file system to
	<filename>/var/audit</filename> so that other file systems are
	not affected if the audit file system becomes full.</para>
    </warning>
  </sect1>

  <sect1 xml:id="audit-inline-glossary">
    <title>Key Terms</title>

    <para>The following terms are related to security event
      auditing:</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>.  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>: a named set of related
	  events which 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>: 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>: a log file consisting of a
	  series of audit records describing security events.  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 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.  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 xml:id="audit-config">
    <title>Audit Configuration</title>

    <para>User space support for event auditing is installed as part
      of the base &os; operating system.  Kernel support is available
      in the <filename>GENERIC</filename> kernel by default,
      and &man.auditd.8; can be enabled
      by adding the following line to
      <filename>/etc/rc.conf</filename>:</para>

    <programlisting>auditd_enable="YES"</programlisting>

    <para>Then, start the audit daemon:</para>

    <screen>&prompt.root; <userinput>service auditd start</userinput></screen>

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

    <programlisting>options	AUDIT</programlisting>

    <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.  Selection expressions are evaluated from left to
	right, and two expressions are combined by appending one onto
	the other.</para>

      <para><xref linkend="event-selection"/> summarizes the default
	audit event classes:</para>

      <table xml:id="event-selection" frame="none" pgwide="1">
	<title>Default Audit Event Classes</title>

	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Class Name</entry>
	      <entry>Description</entry>
	      <entry>Action</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>all</entry>
	      <entry>all</entry>
	      <entry>Match all event classes.</entry>
	    </row>

	    <row>
	      <entry>aa</entry>
	      <entry>authentication and authorization</entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry>ad</entry>
	      <entry>administrative</entry>
	      <entry>Administrative actions performed on the system as
		a whole.</entry>
	    </row>

	    <row>
	      <entry>ap</entry>
	      <entry>application</entry>
	      <entry>Application defined action.</entry>
	    </row>

	    <row>
	      <entry>cl</entry>
	      <entry>file close</entry>
	      <entry>Audit calls to the
		<function>close</function> system call.</entry>
	    </row>

	    <row>
	      <entry>ex</entry>
	      <entry>exec</entry>
	      <entry>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.</entry>
	    </row>

	    <row>
	      <entry>fa</entry>
	      <entry>file attribute access</entry>
	      <entry>Audit the access of object attributes such as
		&man.stat.1; and &man.pathconf.2;.</entry>
	    </row>

	    <row>
	      <entry>fc</entry>
	      <entry>file create</entry>
	      <entry>Audit events where a file is created as a
		result.</entry>
	    </row>

	    <row>
	      <entry>fd</entry>
	      <entry>file delete</entry>
	      <entry>Audit events where file deletion occurs.</entry>
	    </row>

	    <row>
	      <entry>fm</entry>
	      <entry>file attribute modify</entry>
	      <entry>Audit events  where file attribute modification
		occurs, such as by &man.chown.8;, &man.chflags.1;, and
		&man.flock.2;.</entry>
	    </row>

	    <row>
	      <entry>fr</entry>
	      <entry>file read</entry>
	      <entry>Audit events in which data is read or files are
		opened for reading.</entry>
	    </row>

	    <row>
	      <entry>fw</entry>
	      <entry>file write</entry>
	      <entry>Audit events in which data is written or files
		are written or modified.</entry>
	    </row>

	    <row>
	      <entry>io</entry>
	      <entry>ioctl</entry>
	      <entry>Audit use of the <function>ioctl</function>
		system call.</entry>
	    </row>

	    <row>
	      <entry>ip</entry>
	      <entry>ipc</entry>
	      <entry>Audit various forms of Inter-Process
		Communication, including POSIX pipes and System V
		<acronym>IPC</acronym> operations.</entry>
	    </row>

	    <row>
	      <entry>lo</entry>
	      <entry>login_logout</entry>
	      <entry>Audit &man.login.1; and &man.logout.1;
		events.</entry>
	    </row>

	    <row>
	      <entry>na</entry>
	      <entry>non attributable</entry>
	      <entry>Audit non-attributable events.</entry>
	    </row>

	    <row>
	      <entry>no</entry>
	      <entry>invalid class</entry>
	      <entry>Match no audit events.</entry>
	    </row>

	    <row>
	      <entry>nt</entry>
	      <entry>network</entry>
	      <entry>Audit events related to network actions such as
		&man.connect.2; and &man.accept.2;.</entry>
	    </row>

	    <row>
	      <entry>ot</entry>
	      <entry>other</entry>
	      <entry>Audit miscellaneous events.</entry>
	    </row>

	    <row>
	      <entry>pc</entry>
	      <entry>process</entry>
	      <entry>Audit process operations such as &man.exec.3; and
		&man.exit.3;.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <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 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.  <xref linkend="event-prefixes"/> summarizes
	the available prefixes:</para>

      <table xml:id="event-prefixes" frame="none" pgwide="1">
	<title>Prefixes for Audit Event Classes</title>

	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Prefix</entry>
	      <entry>Action</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>+</entry>
	      <entry>Audit successful events in this class.</entry>
	    </row>

	    <row>
	      <entry>-</entry>
	      <entry>Audit failed events in this class.</entry>
	    </row>

	    <row>
	      <entry>^</entry>
	      <entry>Audit neither successful nor failed events in
		this class.</entry>
	    </row>

	    <row>
	      <entry>^+</entry>
	      <entry>Do not audit successful events in this
		class.</entry>
	    </row>

	    <row>
	      <entry>^-</entry>
	      <entry>Do not audit failed events in this class.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

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

      <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>The following configuration files for security event
	auditing are found in
	<filename>/etc/security</filename>:</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, and
	    maximum audit trail size.</para>
	</listitem>

	<listitem>
	  <para><filename>audit_event</filename>: textual names and
	    descriptions of system audit events and a list of which
	    classes each event is in.</para>
	</listitem>

	<listitem>
	  <para><filename>audit_user</filename>: user-specific audit
	    requirements to be 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>

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

      <sect3 xml: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
dist:off
flags:lo,aa
minfree:5
naflags:lo,aa
policy:cnt,argv
filesz:2M
expire-after:10M</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>If the <option>dist</option> field is set to
	  <literal>on</literal> or <literal>yes</literal>, hard links
	  will be created to all trail files in
	  <filename>/var/audit/dist</filename>.</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/logout events as
	  well as authentication and authorization 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.</para>

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

	<para>The <option>policy</option> entry specifies a
	  comma-separated list of policy flags controlling various
	  aspects of audit behavior.  The <literal>cnt</literal>
	  indicates that the system should continue running despite an
	  auditing failure (this flag is highly recommended).  The
	  other flag, <literal>argv</literal>, 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 for an audit trail before automatically terminating and
	  rotating the trail file.  A value of <literal>0</literal>
	  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.</para>

	<para>The <option>expire-after</option> field specifies when
	  audit log files will expire and be removed.</para>
      </sect3>

      <sect3 xml: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 <literal>alwaysaudit</literal> field specifies a set of
	  events that should always be audited for the user, and the
	  <literal>neveraudit</literal> field specifies a set of
	  events that should never be audited for the user.</para>

	<para>The following example entries audit login/logout events
	  and successful command execution for <systemitem
	    class="username">root</systemitem> and file creation and
	  successful command execution for <systemitem
	    class="username">www</systemitem>.  If used with the
	  default <filename>audit_control</filename>, the
	  <literal>lo</literal> entry for <systemitem
	    class="username">root</systemitem> is redundant, and
	  login/logout events will also be audited for <systemitem
	    class="username">www</systemitem>.</para>

	<programlisting>root:lo,+ex:no
www:fc,+ex:no</programlisting>
      </sect3>
    </sect2>
  </sect1>

  <sect1 xml:id="audit-administration">
    <title>Working with Audit Trails</title>

    <para>Since audit trails are stored in the <acronym>BSM</acronym>
      binary format, several built-in tools are available to modify or
      convert these trails to text.  To convert trail files to a
      simple text format, use <command>praudit</command>.  To reduce
      the audit trail file for analysis, archiving, or printing
      purposes, use <command>auditreduce</command>.  This utility
      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, to dump the entire contents of a specified
      audit log in plain text:</para>

    <screen>&prompt.root; <userinput>praudit /var/audit/<replaceable>AUDITFILE</replaceable></userinput></screen>

    <para>Where <replaceable>AUDITFILE</replaceable> 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> (an audit record header) or
      <literal>path</literal> (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
      <literal>exec arg</literal> token contains 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 includes the file mode.  The
      <literal>subject</literal> token stores 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 as the user
      <systemitem class="username">robert</systemitem> switched to the
      <systemitem class="username">root</systemitem> account before
      running this command, but it is audited using the original
      authenticated user.  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 and
      can be selected by including <option>-x</option>.</para>

    <para>Since audit logs may be very large, a subset of records can
      be selected using <command>auditreduce</command>.  This example
      selects all audit records produced for the user
      <systemitem class="username">trhodes</systemitem> stored in
      <filename>AUDITFILE</filename>:</para>

    <screen>&prompt.root; <userinput>auditreduce -u <replaceable>trhodes</replaceable> /var/audit/<replaceable>AUDITFILE</replaceable> | praudit</userinput></screen>

    <para>Members of the <systemitem
	class="groupname">audit</systemitem> group have permission to
      read audit trails in <filename>/var/audit</filename>.  By
      default, this group is empty, so only the <systemitem
	class="username">root</systemitem> user can read audit trails.
      Users may be added to the <systemitem
	class="groupname">audit</systemitem> group in order to
      delegate audit review rights.  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>
      <title>Live Monitoring Using Audit Pipes</title>

      <para>Audit pipes are cloning pseudo-devices 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, the audit pipe
	device is a convenient way for the administrator 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:</para>

      <screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen>

      <para>By default, audit pipe device nodes are accessible only to
	the <systemitem class="username">root</systemitem> user.  To
	make them accessible to the members of the <systemitem
	  class="groupname">audit</systemitem> group, add a
	<literal>devfs</literal> rule to
	<filename>/etc/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 <acronym>I/O</acronym> is audited, and
	  <command>praudit</command> is run from an
	  <acronym>SSH</acronym> session, a continuous stream of audit
	  events will be generated at a high rate, as each event being
	  printed will generate another event.  For this reason, it is
	  advisable to run <command>praudit</command> on an audit pipe
	  device from sessions without fine-grained
	  <acronym>I/O</acronym> auditing.</para>
      </warning>
    </sect2>

    <sect2>
      <title>Rotating and Compressing Audit Trail Files</title>

      <para>Audit trails are written to by the kernel and
	managed 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, <command>audit</command> should
	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>

      <para>If &man.auditd.8; is not currently running, this command
	will fail and an error message will be produced.</para>

      <para>Adding the following line to
	<filename>/etc/crontab</filename> will schedule this rotation
	every twelve hours:</para>

      <programlisting>0     */12       *       *       *       root    /usr/sbin/audit -n</programlisting>

      <para>The change will take effect once
	<filename>/etc/crontab</filename> is saved.</para>

      <para>Automatic rotation of the audit trail file based on file
	size is possible using <option>filesz</option> in
	<filename>audit_control</filename> as described in <xref
	  linkend="audit-auditcontrol"/>.</para>

      <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
	<filename>/etc/security/audit_warn</filename> 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.  This
	script will be run only when audit trail files are cleanly
	terminated.  It will not be run on trails left unterminated
	following an improper shutdown.</para>
    </sect2>
  </sect1>
</chapter>