Some edits of the audit handbook chapter:

Rename section "Security Event Auditing" from "Kernel Event Auditing" --
while most of our events are currently generated by the kernel, the intent
is that it will be whole system auditing.

More carefully distinguish our implementation being based on Sun's
published API and file format, and not their implementation.

Clarify a few more things audit can be used for, including post-mortem
analysis and intrusion detection.

Mention Mac OS X compatibility in addition to Darwin.

Sort glossary slightly differently -- events before classes, since classes
are defined in terms of events.  Tweak definition and examples.  Mention
non-attributable vs attributable here.

Mention that classes allow administrators to specify auditing requirements
at a high level.

Describe contents of a record.

Define 'trail'.

Since audit is now part of the base system, remove directions for
installing files, etc, since complete installs should have them, and if
they don't, the user should seek support.

Mention that audit trails are happiest on a file system of their own.

Update example flags option in audit_control -- add information on the
new default, but keep the current example because the new default doesn't
reflect the scope of possible expressions, whereas the earlier example
did.

Rephrase paragraph on avoiding directly manipulating logs in order to
explain that this is because the kernel/daemon own the log until it is
terminated.

Correct example: auditreduce just reduces, not prints, so |praudit is
needed or the user will experience the power of raw BSM's effects on
his or her terminal.

Much suggested by:	brueffer
Reviewed by:		brueffer

en_US.ISO8859-1/books/handbook/audit/chapter.sgml

@@ -21,23 +21,23 @@ requirements. -->
     </authorgroup>
   </chapterinfo>
 
-  <title>Kernel Event Auditing</title>
+  <title>Security Event Auditing</title>
 
   <sect1 id="audit-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>AUDIT</primary></indexterm>
     <indexterm>
-      <primary>Kernel Event Auditing</primary>
+      <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
-      the &sun; <acronym>BSM</acronym> implementation.  Event auditing
+      the &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 system analysis, system monitoring, and
+      for the purposes of post-mortem analysis, system monitoring, and
-      security evaluation.  After some settling time in &os;&nbsp;7-CURRENT,
+      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>
 
@@ -96,7 +96,7 @@ requirements. -->
     <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 Darwin operating systems.</para>
+      interchangeable with &solaris; and Mac OS X/Darwin operating systems.</para>
   </sect1>
 
   <sect1 id="audit-inline-glossary">
@@ -109,22 +109,47 @@ requirements. -->
 
     <itemizedlist>
       <listitem>
-        <para><emphasis>class</emphasis>: A class specifies the category
+	<para><emphasis>event</emphasis>: An auditable event is
-	  different actions the system are placed in.  For example,
+	  an event that can be logged using the audit subsystem.  The
-	  use of &man.login.1; could be placed in a class.</para>
+	  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>event</emphasis>: An event could be considered
+        <para><emphasis>class</emphasis>: Events may be assigned to
-	  an action taken on the system.  Creating a file would be
+	  one or more classes, usually based on the general category
-	  an event.</para>
+	  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 or a note
+	<para><emphasis>record</emphasis>: A record is a log entry
-	  about a specific action.</para>
+	  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>
 	<para><emphasis>prefix</emphasis>: A prefix is considered to
 	  be the configuration element used to toggle auditing for
@@ -136,7 +161,7 @@ requirements. -->
   <sect1 id="audit-install">
     <title>Installing Audit Support</title>
 
-    <para>Support for Event Auditing should have been installed with
+    <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 role="directory">/etc/security</filename>.  Files
@@ -190,21 +215,19 @@ requirements. -->
 
       <listitem>
 	<para><filename>audit_user</filename> - The events to audit
-	  for individual users.  A user name does not need to appear
+	  for individual users.  Users not appearing here will be
-	  in here.</para>
+	  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 form warning messages.</para>
+	  used by auditd to generate warning messages in
+	  exceptional situations, such as when space for audit
+	  records is running low.</para>
       </listitem>
     </itemizedlist>
 
-    <para>If these files do not exist, for whatever reason, they can
-      be installed easily by issuing the following commands:</para>
-
-    <screen>&prompt.root; <userinput>cd /usr/src/contrib/bsm/etc &amp;&amp; make install</userinput></screen>
-
     <sect2>
       <title>Audit File Syntax</title>
 
@@ -392,15 +415,21 @@ requirements. -->
 	  we see the following:</para>
 
 	<programlisting>dir:/var/audit
-flags:lo,ad,-all,^-fa,^-fc,^-cl
+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.</para>
+	  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,
+	  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
@@ -426,19 +455,17 @@ naflags:lo</programlisting>
 	  to eighty (80) percent full.</para>
 
 	<para>The <option>naflags</option> option specifies audit
-	  flags to be considered non attributable; i.e.: classes of
+	  classes to be audited for non-attributed events &mdash;
-	  events which cannot be attributed to a specific user
+	  that is, events for which there is no authenticated user.
-	  on the system.  This can be overridden with the
+	  </para>
-	  <filename>audit_user</filename> configuration file.</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 map audit specific events directly
+	  administrator to determine which classes of audit events
-	  to users.  This adds a finer-grained control mechanism
+	  should be logged for which system users.</para>
-	  for all system users.</para>
 
 	<para>The following is the defaults currently placed in
 	  the <filename>audit_user</filename> file:</para>
@@ -462,15 +489,16 @@ audit:fc:no</programlisting>
   <sect1 id="audit-administration">
     <title>Event Audit Administration</title>
 
-    <para>Events from the <command>auditd</command> daemon cannot
+    <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> or <command>auditreduce</command>
+      <command>praudit</command> command; audit trails may be reduced
-      utilities.</para>
+      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>There are two utilities because of different requirements.
+    <para>For example, the <command>praudit</command> utility will dump the
-      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>
 
@@ -483,7 +511,7 @@ audit:fc:no</programlisting>
       command, where <username>trhodes</username> is the user of
       choice:</para>
 
-    <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE</userinput></screen>
+    <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
@@ -496,13 +524,17 @@ audit:fc:no</programlisting>
     <sect2>
       <title>Rotating Audit Log Files</title>
 
-      <para>Manually rotating audit log files will cause great
+      <para>Because of log reliability requirements, audit trails
-	havoc within the system.  Therefore, adding a line to
+	are written to only by the kernel, and managed only by
-	&man.newsyslog.conf.5; will provide no usefulness.  So how
+	<command>auditd</command>.  Administrators should not
-	are the logs to be rotated?  Sending the appropriate flag
+	attempt to use &man.newsyslog.conf.5; or other tools to
-	to the <command>audit</command> utility will shut down
+	directly rotate audit logs.  Instead, the <command>audit</command>
-	event auditing and safely rotate.  The following command
+	management tool should be used to shut down auditing,
-	should handle everything for an administrator:</para>
+	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>