Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 28 Mar 2014 19:05:35 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r44377 - head/en_US.ISO8859-1/books/handbook/audit
Message-ID:  <201403281905.s2SJ5Zcp026279@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Fri Mar 28 19:05:35 2014
New Revision: 44377
URL: http://svnweb.freebsd.org/changeset/doc/44377

Log:
  Editorial review of first 1/2 of Security Event Auditing.
  Add 2 tables.
  Still need to research additional entries which are not described
  in this section.
  More commits to come.
  
  Sponsored by:	iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/audit/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/audit/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/audit/chapter.xml	Fri Mar 28 17:21:22 2014	(r44376)
+++ head/en_US.ISO8859-1/books/handbook/audit/chapter.xml	Fri Mar 28 19:05:35 2014	(r44377)
@@ -44,30 +44,31 @@ requirements. -->
       <see>MAC</see>
     </indexterm>
 
-    <para>The &os; operating system includes support for fine-grained
-      security event auditing.  Event auditing allows the reliable,
+    <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
-      <acronym>BSM</acronym> API and file format, and is interoperable
-      with both &sun;'s &solaris; and &apple;'s &macos; X audit
+      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
+      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>
+	<para>What event auditing is and how it works.</para>
       </listitem>
 
       <listitem>
-	<para>How to configure Event Auditing on &os; for users and
+	<para>How to configure event auditing on &os; for users and
 	  processes.</para>
       </listitem>
 
@@ -98,55 +99,55 @@ requirements. -->
     </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
+      <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
+	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
+	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
-	the <filename>/var/audit</filename> tree
+	<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 in This Chapter</title>
+    <title>Key Terms</title>
 
-    <para>Before reading this chapter, a few key audit-related terms
-      must be explained:</para>
+    <para>The following terms are related to security event
+      auditing:</para>
 
     <itemizedlist>
       <listitem>
-	<para><emphasis>event</emphasis>: An auditable event is any
+	<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
+	  <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>: Event classes are named sets
-	  of related events, and are used in selection expressions.
+	<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
+	    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
+	<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
@@ -155,25 +156,24 @@ requirements. -->
       </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
+	<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 selection
-	  expression is a string containing a list of prefixes and
+	<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
+	<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
+	  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
@@ -181,7 +181,7 @@ requirements. -->
       </listitem>
 
       <listitem>
-	<para><emphasis>reduction</emphasis>: The process by which
+	<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
@@ -194,78 +194,25 @@ requirements. -->
     </itemizedlist>
   </sect1>
 
-  <sect1 xml: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 xml:id="audit-config">
     <title>Audit Configuration</title>
 
-    <para>All configuration files for security audit are found in
-      <filename>/etc/security</filename>.  The following files must be
-      present before the audit daemon is started:</para>
+    <para>User space support for event auditing is installed as part
+      of the base &os; operating system.  Kernel support can be enabled
+      by adding the following line to
+      <filename>/etc/rc.conf</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,
-	  maximum audit trail size, etc.</para>
-      </listitem>
+    <programlisting>auditd_enable="YES"</programlisting>
 
-      <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>
+    <para>Then, start the audit daemon:</para>
 
-      <listitem>
-	<para><filename>audit_user</filename> - User-specific audit
-	  requirements, which are combined with the global defaults at
-	  login.</para>
-      </listitem>
+    <screen>&prompt.root; <userinput>service auditd start</userinput></screen>
 
-      <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>
+    <para>Users who prefer to compile
+      a custom kernel must include the
+      following line in their custom kernel configuration file:</para>
 
-    <warning>
-      <para>Audit configuration files should be edited and maintained
-	carefully, as errors in configuration may result in improper
-	logging of events.</para>
-    </warning>
+    <programlisting>options	AUDIT</programlisting>
 
     <sect2>
       <title>Event Selection Expressions</title>
@@ -280,170 +227,218 @@ requirements. -->
 	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>
+      <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>
 
-      <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
+	<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>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.</para>
-	</listitem>
+	    <literal>policy</literal> setting.</entry>
+	</row>
 
-	<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,
+	<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.</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>
+	    operations.</entry>
+	</row>
 
-      </itemizedlist>
+	<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 class in the list is combined with a prefix
+      <para>Each audit event class 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>
+	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>
 
-      <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>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
@@ -455,11 +450,53 @@ requirements. -->
     <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>
+    <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>
@@ -468,11 +505,13 @@ requirements. -->
 	  specified in <filename>audit_control</filename>:</para>
 
 	<programlisting>dir:/var/audit
-flags:lo
-minfree:20
-naflags:lo
-policy:cnt
-filesz:0</programlisting>
+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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403281905.s2SJ5Zcp026279>