<?xml version="1.0" encoding="iso-8859-2"?>
<!--
     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>
    </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;&nbsp;7-CURRENT development branch includes
      support for Event Auditing based on the &posix;.1e draft and
      Sun's published <acronym>BSM</acronym> API and file format.
      Event auditing permits the selective logging of security-relevant
      system events for the purposes of post-mortem analysis, system
      monitoring, and intrusion detection.  After some settling time in
      &os;&nbsp;7-CURRENT, this support will be merged to &os;&nbsp;6-STABLE
      and appear in subsequent releases.</para>

    <warning>
      <para>The audit facility in FreeBSD is considered experimental, and
	production deployment should occur only after careful consideration
	of the risks of deploying experimental software.</para>
    </warning>

    <para>This chapter will focus mainly on the installation and
      configuration of Event Auditing.  Explanation of audit policies,
      and an example configuration will be provided for the
      convenience of the reader.</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>
    </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>Event auditing can generate a great deal of log file
	data, exceeding gigabytes a week in some configurations.  An
	administrator should read this chapter in its entirety to avoid
	possible self-inflicted <acronym>DoS</acronym> attacks due to
	improper configuration.</para>
    </warning>

    <para>The implementation of Event Auditing in &os; is similar to
      that of the &sun; Basic Security Module, or <acronym>BSM</acronym>
      library.  Thus, the configuration is almost completely
      interchangeable with &solaris; and Mac OS X/Darwin operating
      systems.</para>
  </sect1>

  <sect1 id="audit-inline-glossary">
    <title>Key Terms - Words to Know</title>

    <para>Before reading this chapter, a few key terms must be
      explained.  This is intended to clear up any confusion that
      may occur and to avoid the abrupt introduction of new terms
      and information.</para>

    <itemizedlist>
      <listitem>
	<para><emphasis>event</emphasis>: An auditable event is
	  an event that can be logged using the audit subsystem.  The
	  administrator can configure which events will be audited.
	  Examples of security-relevant events include the creation of
	  a file, the building of a network connection, or the logging
	  in of a user.  Events are either <quote>attributable</quote>,
	  meaning that they can be traced back to a user
	  authentication, or <quote>non-attributable</quote>.  Examples
	  of non-attributable events are any events that occur before
	  authentication has succeeded in the login process, such as
	  failed authentication attempts.</para>
      </listitem>

      <listitem>
        <para><emphasis>class</emphasis>: Events may be assigned to
	  one or more classes, usually based on the general category
	  of the events, such as <quote>file creation</quote>,
	  <quote>file access</quote>, or <quote>network</quote>.  Login
	  and logout events are assigned to the <literal>lo</literal>
	  class.  The use of classes allows the administrator to
	  specify high level auditing rules without having to specify
	  whether each individual auditable operation will be logged.</para>
      </listitem>

      <listitem>
	<para><emphasis>record</emphasis>: A record is a log entry
	  describing a security event.  Records typically have a
	  record event type, information on the subject (user) associated
	  with the event, time information, information on any objects,
	  such as files, and information on whether the event corresponded
	  to a successful operation.</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>prefix</emphasis>: A prefix is considered to
	  be the configuration element used to toggle auditing for
	  success and failed events.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="audit-install">
    <title>Installing Audit Support</title>

    <para>Support for Event Auditing is installed with
      the normal <maketarget>installworld</maketarget> process.  An
      administrator may confirm this by viewing the contents
      of <filename class="directory">/etc/security</filename>.  Files
      beginning with the word <emphasis>audit</emphasis> should be present.
      For example, <filename>audit_event</filename>.</para>

    <para>In-kernel support for the framework must also exist.  This
      may be done by adding the following lines to the local 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 completed, enable the audit daemon by adding the
      following line to &man.rc.conf.5;:</para>

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

    <para>Functionality not provided by the default may be added
      here with the <option>auditd_flags</option> option.</para>
  </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,
	  etc.</para>
      </listitem>

      <listitem>
	<para><filename>audit_event</filename> - Defines the kernel
	  audit events.  These map, mostly, to system calls.</para>
      </listitem>

      <listitem>
	<para><filename>audit_user</filename> - The events to audit
	  for individual users.  Users not appearing here will be
	  subject to the default configuration in the control
	  configuration file.</para>
      </listitem>

      <listitem>
	<para><filename>audit_warn</filename> - A shell script
	  used by auditd to generate warning messages in
	  exceptional situations, such as when space for audit
	  records is running low.</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>Audit File Syntax</title>

      <para>The configuration file syntax is rather arcane, albeit easy
	to work with.  One thing an administrator must be leery about
	is overriding system defaults.  This could create potential
	openings for audit data to not be collected properly.</para>

      <para>The audit subsystem will accept both the short name and
	long name with regards to configuration syntax.  A syntax
	map has been included below.</para>

      <para>The following list contains all supported audit
	classes:</para>

      <itemizedlist>
	<listitem>
	  <para><option>all</option> - <literal>all</literal> - All
	    audit flags set.</para>
	</listitem>

	<listitem>
	  <para><option>ad</option> - <literal>administrative</literal>
	    - Administrative actions performed on the system as a
	    whole.</para>
	</listitem>

	<listitem>
	  <para><option>ap</option> - <literal>application</literal> -
	    Application defined action.</para>
	</listitem>

	<listitem>
	  <para><option>cl</option> - <literal>file_close</literal> -
	    Audit calls to the <function>close</function> system
	    call.</para>
	</listitem>

	<listitem>
	  <para><option>ex</option> - <literal>exec</literal> - Audit
	    program or utility execution.</para>
	</listitem>

	<listitem>
	  <para><option>fa</option> - <literal>file_attr_acc</literal>
	    - Audit the access of object attributes such as
	    &man.stat.1;, &man.pathconf.2; and similar events.</para>
	</listitem>

	<listitem>
	  <para><option>fc</option> - <literal>file_creation</literal>
	    - Audit events where a file is created as a result.</para>
	</listitem>

	<listitem>
	  <para><option>fd</option> - <literal>file_deletion</literal>
	    - Audit events where file deletion occurs.</para>
	</listitem>

	<listitem>
	  <para><option>fm</option> - <literal>file_attr_mod</literal>
	    - Audit events where file attribute modification occurs,
	    such as &man.chown.8;, &man.chflags.1;, &man.flock.2;,
	    etc.</para>
	</listitem>

	<listitem>
	  <para><option>fr</option> - <literal>file_read</literal>
	    - Audit events in which data is read, files are opened for
	    reading, etc.</para>
	</listitem>

	<listitem>
	  <para><option>fw</option> - <literal>file_write</literal> -
	    Audit events in which data is written, files are written
	    or modified, etc.</para>
	</listitem>

	<listitem>
	  <para><option>io</option> - <literal>ioctl</literal> - Audit
	    use of the &man.ioctl.2; system call.</para>
	</listitem>

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

	<listitem>
	  <para><option>lo</option> - <literal>login_logout</literal> -
	    Audit &man.login.1; and &man.logout.1; events occurring
	    on the system.</para>
	</listitem>

	<listitem>
	  <para><option>na</option> - <literal>non_attrib</literal> -
	    Audit non-attributable events.</para>
	</listitem>

	<listitem>
	  <para><option>no</option> - <literal>no_class</literal> -
	    Null class used to disable event auditing.</para>
	</listitem>

	<listitem>
	  <para><option>nt</option> - <literal>network</literal> -
	    Audit events related to network actions, such as
	    &man.connect.2; and &man.accept.2;.</para>
	</listitem>

	<listitem>
	  <para><option>ot</option> - <literal>other</literal> -
	    Audit miscellaneous events.</para>
	</listitem>

	<listitem>
	  <para><option>pc</option> - <literal>process</literal> -
	    Audit process operations, such as &man.exec.3; and
	    &man.exit.3;.</para>
	</listitem>
      </itemizedlist>

      <para>Following is a list of all supported audit prefixes:</para>

      <itemizedlist>
	<listitem>
	  <para><literal>none</literal> - Audit both the success
	    or failure of an event.  For example, just listing a
	    class will result in the auditing of both success and
	    failure.</para>
	</listitem>

	<listitem>
	  <para><literal>+</literal> - Audit successful events
	    only.</para>
	</listitem>

	<listitem>
	  <para><literal>-</literal> - Audit failed events
	    only.</para>
	</listitem>
      </itemizedlist>

      <warning>
	<para>Using the <option>all</option> class with either the
	  positive or negative prefix can generate a large amount
	  of data at an extremely rapid rate.</para>
      </warning>

      <para>Extra prefixes used to modify the default configuration
	values:</para>
<!-- XXX: Perhaps a variable listing here. -->
      <itemizedlist>
	<listitem>
	  <para>^- - Disable auditing of failed events.</para>
	</listitem>

	<listitem>
	  <para>^+ - Enable auditing of successful events.</para>
	</listitem>

	<listitem>
	  <para>^ - Disable auditing of both successful and failed
	    events.</para>
	</listitem>
      </itemizedlist>
    </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 paramaters and defaults for both attributable and
	non-attributable events.  The second may be used to tune the level
	and nature of auditing for individual users.</para>

      <sect3 id="audit-auditcontrol">
        <title>The <filename>audit_control</filename> File</title>

	<para>The <filename>audit_control</filename> file contains some basic
	  defaults that the administrator may wish to modify.  Perhaps
	  even set some new ones.  Viewing the contents of this file,
	  we see the following:</para>

	<programlisting>dir:/var/audit
flags:lo
minfree:20
naflags:lo</programlisting>

	<para>The <option>dir</option> option is used to set the default
	  directory where audit logs are stored.  Audit is frequently
	  configured so that audit logs are stored on a dedicated file
	  system, so as to prevent interference between the audit
	  subsystem and other subsystems when file systems become full.
	  </para>

	<para>The <option>flags</option> option is used to set the
	  system-wide defaults.  The current setting, <option>lo</option>
	  configures the auditing of all &man.login.1; and &man.logout.1;
	  actions.  A more complex example,
	  <option>lo,ad,-all,^-fa,^-fc,^-cl</option> audits all system
	  &man.login.1; and &man.logout.1; actions, all administrator
	  actions, all failed events in the system, and finally disables
	  auditing of failed attempts for <option>fa</option>,
	  <option>fc</option>, and <option>cl</option>.  Even though
	  the <option>-all</option> turned on the auditing of all
	  failed attempts, the <option>^-</option> prefix will override
	  that for the latter options.</para>

	<para>Notice that the previous paragraph shows the file is
	  read from left to right.  As such, values further on the
	  right side may override a previous value specified to
	  its left.</para>

	<para>The <option>minfree</option> option defines the minimum
	  percentage of free space for audit file systems.  This
	  relates to the file system where audit logs are stored.
	  For example, if the <option>dir</option> specifies
	  <filename class="directory">/var/audit</filename> and
	  <option>minfree</option> is set to twenty (20), warning
	  messages will be generated when the
	  <filename class="directory">/var</filename> file system grows
	  to eighty (80) percent full.</para>

	<para>The <option>naflags</option> option specifies audit
	  classes to be audited for non-attributed events &mdash;
	  that is, events for which there is no authenticated user.
	  </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 determine which classes of audit events
	  should be logged for which system users.</para>

	<para>The following is the defaults currently placed in
	  the <filename>audit_user</filename> file:</para>

	<programlisting>root:lo:no
audit:fc:no</programlisting>

	<para>Notice how the default is to audit all cases of
	  <command>login</command>/<command>logout</command>
	  and disable auditing of all other actions for
	  <username>root</username>.  This configuration
	  also audits all file creation and disables all
	  other auditing for the <username>audit</username>
	  user.  While event auditing does not require a special
	  user exist, some configurations, specifically environments
	  making use of <acronym>MAC</acronym>, may require it.</para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="audit-administration">
    <title>Event Audit Administration</title>

    <para>Events written by the kernel audit subsystem cannot
      be altered or read in plain text.  Data is stored and accessed
      in a method similar to that of &man.ktrace.1; and &man.kdump.1;,
      that is, they may only be viewed by dumping them using the
      <command>praudit</command> command; audit trails may be reduced
      using the <command>auditreduce</command> command, which selects
      records from an audit trail based on properties of interest, such
      as the user, time of the event, and type of operation.</para>

    <para>For example, the <command>praudit</command> utility will dump the
      entire contents of a specified audit log in plain text.  To dump an
      audit log in its entirety, use:</para>

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

    <para>Where <replaceable>AUDITFILE</replaceable> is the audit log
      of viewing choice.  Since audit logs may contain enormous
      amounts of data, an administrator may prefer to select records
      for specific users.  This is made possible with the following
      command, where <username>trhodes</username> is the user of
      choice:</para>

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

    <para>This will select all audit records produced by the user
      <username>trhodes</username> stored in the
      <replaceable>AUDITFILE</replaceable> file.</para>

    <para>There are several other options available for reading audit
      records, see the aforementioned command's manual pages for
      a more in depth explanation.</para>

    <sect2>
      <title>Rotating Audit Log Files</title>

      <para>Due to log reliability requirements, audit trails
	are written to only by the kernel, and managed only by
	<command>auditd</command>.  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 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>

      <warning>
	<para>If the <command>auditd</command> daemon is not currently
	  running, the previous 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>*     */12       *       *       *       root    /usr/sbin/audit -n</programlisting>

      <para>The change will take effect once you have saved the
	new <filename>/etc/crontab</filename>.</para>
    </sect2>

    <sect2>
      <title>Delegating Audit Review Rights</title>

      <para>By default, only the root user has the right to read system audit
	logs.  However, that right may be delegated to members of the
	<literal>audit</literal> group, as the audit directory and audit
	trail files are assigned to that group, and made group-readable.  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>
  </sect1>
</chapter>