svn commit: r44377 - head/en_US.ISO8859-1/books/handbook/audit
Dru Lavigne
dru at FreeBSD.org
Fri Mar 28 19:05:36 UTC 2014
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
More information about the svn-doc-all
mailing list