Date: Fri, 28 Mar 2014 20:37:21 +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: r44378 - head/en_US.ISO8859-1/books/handbook/audit Message-ID: <201403282037.s2SKbL0a064278@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Fri Mar 28 20:37:20 2014 New Revision: 44378 URL: http://svnweb.freebsd.org/changeset/doc/44378 Log: Finish editorial review of Event Auditing. Still need an Action for aa in Table 17.1. 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 19:05:35 2014 (r44377) +++ head/en_US.ISO8859-1/books/handbook/audit/chapter.xml Fri Mar 28 20:37:20 2014 (r44378) @@ -250,6 +250,12 @@ requirements. --> </row> <row> + <entry>aa</entry> + <entry>authentication and authorization</entry> + <entry></entry> + </row> + + <row> <entry>ad</entry> <entry>administrative</entry> <entry>Administrative @@ -521,38 +527,45 @@ expire-after:10M</programlisting> 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 and logout events - are audited for all users.</para> + 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. When this threshold is exceeded, a warning - will be generated. The above example sets the minimum free - space to twenty percent.</para> + trail is stored.</para> <para>The <option>naflags</option> entry specifies audit classes to be audited for non-attributed events, such as the - login process and system daemons.</para> + 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 default - <literal>cnt</literal> flag indicates that the system should + aspects of audit behavior. The + <literal>cnt</literal> indicates that the system should continue running despite an auditing failure (this flag is - highly recommended). Another commonly used flag is - <literal>argv</literal>, which causes command line arguments + 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 in bytes to allow an audit trail file to grow to before - automatically terminating and rotating the trail file. The - default, 0, disables automatic log rotation. If the - requested file size is non-zero and below the minimum 512k, + 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"> @@ -561,18 +574,18 @@ expire-after:10M</programlisting> <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 first is the <literal>alwaysaudit</literal> field, - which specifies a set of events that should always be - audited for the user, and the second is the - <literal>neveraudit</literal> field, which specifies a set + 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 <filename>audit_user</filename> - audits login/logout events and successful command execution - for <systemitem class="username">root</systemitem>, and - audits file creation and successful command execution for + <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 above example <filename>audit_control</filename>, the + 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 @@ -585,36 +598,34 @@ www:fc,+ex:no</programlisting> </sect1> <sect1 xml:id="audit-administration"> - <title>Administering the Audit Subsystem</title> + <title>Working with Audit Trails</title> - <sect2> - <title>Viewing Audit Trails</title> - - <para>Audit trails are stored in the BSM binary format, so tools - must be used to modify or convert to text. The - &man.praudit.1; command converts trail files to a simple text - format; the &man.auditreduce.1; command may be used to reduce + <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. A variety of selection parameters are supported by - &man.auditreduce.1;, including event type, event class, user, + 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, &man.praudit.1; will dump the entire + <para>For example, to dump the entire contents of a specified audit log in plain text:</para> - <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen> + <screen>&prompt.root; <userinput>praudit /var/audit/<replaceable>AUDITFILE</replaceable></userinput></screen> <para>Where - <filename><replaceable>AUDITFILE</replaceable></filename> is + <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 &man.praudit.1; prints sequentially one per + of tokens, which <command>praudit</command> prints sequentially, one per line. Each token is of a specific type, such as - <literal>header</literal> holding an audit record header, or - <literal>path</literal> holding a file path from a name - lookup. The following is an example of an + <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 @@ -627,75 +638,63 @@ 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 arguments + <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 in particular, includes the file mode which can be used to - determine if the application was setuid. The - <literal>subject</literal> token describes the subject - process, and stores in sequence the audit user ID, effective + 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: the user - <systemitem class="username">robert</systemitem> has switched + 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. Finally, the + original authenticated user. The <literal>return</literal> token indicates the successful - execution, and the <literal>trailer</literal> concludes the + execution and the <literal>trailer</literal> concludes the record.</para> - <para><acronym>XML</acronym> output format is also supported by - &man.praudit.1;, and can be selected using + <para><acronym>XML</acronym> output format is also supported + and can be selected by including <option>-x</option>.</para> - </sect2> - - <sect2> - <title>Reducing Audit Trails</title> - <para>Since audit logs may be very large, an administrator will - likely want to select a subset of records for using, such as - records associated with a specific user:</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 + <replaceable>trhodes</replaceable> stored in + <replaceable>AUDITFILE</replaceable>:</para> - <screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE | praudit</userinput></screen> - - <para>This will select all audit records produced for - <systemitem class="username">trhodes</systemitem> stored in - <filename><replaceable>AUDITFILE</replaceable></filename>.</para> - </sect2> - - <sect2> - <title>Delegating Audit Review Rights</title> + <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 are - given permission to read audit trails in - <filename>/var/audit</filename>; by default, this group is + <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 may read + <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 to the user. As the + 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> <sect2> <title>Live Monitoring Using Audit Pipes</title> - <para>Audit pipes are cloning pseudo-devices in the device file - system which allow applications to tap the live audit record + <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, for - the administrator the audit pipe device is a convenient way to + 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, use the - following command line:</para> + stream. To track the live audit event stream:</para> <screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen> @@ -704,7 +703,7 @@ trailer,133</programlisting> make them accessible to the members of the <systemitem class="groupname">audit</systemitem> group, add a <literal>devfs</literal> rule to - <filename>devfs.rules</filename>:</para> + <filename>/etc/devfs.rules</filename>:</para> <programlisting>add path 'auditpipe*' mode 0440 group audit</programlisting> @@ -715,56 +714,49 @@ trailer,133</programlisting> <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 I/O is audited, and &man.praudit.1; is run from an - SSH session, then a continuous stream of audit events will + 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. It is advisable to run - &man.praudit.1; on an audit pipe device from sessions - without fine-grained I/O auditing in order to avoid this - happening.</para> + 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 Audit Trail Files</title> + <title>Rotating and Compressing Audit Trail Files</title> - <para>Audit trails are written to only by the kernel, and - managed only by the audit daemon, &man.auditd.8;. + <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, the &man.audit.8; management tool may + 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> + manipulated by the administrator:</para> <screen>&prompt.root; <userinput>audit -n</userinput></screen> - <warning> <para>If &man.auditd.8; is not currently running, this 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> + <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 you have saved the new - <filename>/etc/crontab</filename>.</para> + <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 - &man.audit.control.5;, and is described in the configuration - files section of this chapter.</para> - </sect2> - - <sect2> - <title>Compressing Audit Trails</title> + <filename>audit.control</filename> as described in <xref + linkend="audit-config"/>.</para> <para>As audit trail files can become very large, it is often desirable to compress or otherwise archive trails once they @@ -772,8 +764,8 @@ trailer,133</programlisting> <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 the - <filename>audit_warn</filename> script to compress audit + rotated. For example, the following may be added to + <filename>/etc/security/audit_warn</filename> to compress audit trails on close:</para> <programlisting># @@ -785,7 +777,7 @@ 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. The + reducing the audit trail to remove unneeded records. This script will be run only when audit trail files are cleanly terminated, so will not be run on trails left unterminated following an improper shutdown.</para>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403282037.s2SKbL0a064278>