From owner-svn-doc-head@FreeBSD.ORG Fri Mar 28 20:37:21 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 63FA8E17; Fri, 28 Mar 2014 20:37:21 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4F7B2F4B; Fri, 28 Mar 2014 20:37:21 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2SKbLCM064279; Fri, 28 Mar 2014 20:37:21 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2SKbL0a064278; Fri, 28 Mar 2014 20:37:21 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403282037.s2SKbL0a064278@svn.freebsd.org> From: Dru Lavigne Date: Fri, 28 Mar 2014 20:37:21 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 28 Mar 2014 20:37:21 -0000 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. --> + aa + authentication and authorization + + + + ad administrative Administrative @@ -521,38 +527,45 @@ expire-after:10M prevent interference between the audit subsystem and other subsystems if the file system fills. + If the field is set to + on or yes, hard links + will be created to all trail files in + /var/audit/dist. + The 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. + example above, successful and failed login/logout events as + well as authentication and authorization are audited for all users. The 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. + trail is stored. The entry specifies audit classes to be audited for non-attributed events, such as the - login process and system daemons. + login/logout process and authentication and authorization. The entry specifies a comma-separated list of policy flags controlling various - aspects of audit behavior. The default - cnt flag indicates that the system should + aspects of audit behavior. The + cnt indicates that the system should continue running despite an auditing failure (this flag is - highly recommended). Another commonly used flag is - argv, which causes command line arguments + highly recommended). The other flag, + argv, causes command line arguments to the &man.execve.2; system call to be audited as part of command execution. The 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 0 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. + + The field specifies when + audit log files will expire and be removed. + @@ -561,18 +574,18 @@ expire-after:10M The administrator can specify further audit requirements for specific users in audit_user. Each line configures auditing for a user via two fields: - the first is the alwaysaudit field, - which specifies a set of events that should always be - audited for the user, and the second is the - neveraudit field, which specifies a set + the alwaysaudit field + specifies a set of events that should always be + audited for the user, and the + neveraudit field specifies a set of events that should never be audited for the user. - The following example audit_user - audits login/logout events and successful command execution - for root, and - audits file creation and successful command execution for + The following example entries + audit login/logout events and successful command execution + for root and + file creation and successful command execution for www. If used with - the above example audit_control, the + the default audit_control, the lo entry for root is redundant, and login/logout events will also be audited for @@ -585,36 +598,34 @@ www:fc,+ex:no - Administering the Audit Subsystem + Working with Audit Trails - - Viewing Audit Trails - - 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 + Since audit trails are stored in the + BSM 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 praudit. 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 auditreduce. 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. - For example, &man.praudit.1; will dump the entire + For example, to dump the entire contents of a specified audit log in plain text: - &prompt.root; praudit /var/audit/AUDITFILE + &prompt.root; praudit /var/audit/AUDITFILE Where - AUDITFILE is + AUDITFILE is the audit log to dump. Audit trails consist of a series of audit records made up - of tokens, which &man.praudit.1; prints sequentially one per + of tokens, which praudit prints sequentially, one per line. Each token is of a specific type, such as - header holding an audit record header, or - path holding a file path from a name - lookup. The following is an example of an + header (an audit record header) or + path (a file path from a name + lookup). The following is an example of an execve event: header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec @@ -627,75 +638,63 @@ trailer,133 This audit represents a successful execve call, in which the command - finger doug has been run. The arguments + finger doug has been run. The exec arg token contains the processed command line presented by the shell to the kernel. The path token holds the path to the executable as looked up by the kernel. - The attribute token describes the binary, - and in particular, includes the file mode which can be used to - determine if the application was setuid. The - subject token describes the subject - process, and stores in sequence the audit user ID, effective + The attribute token describes the binary + and includes the file mode. The + subject 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 - robert has switched + user ID and real user ID differ as the user + robert switched to the root account before running this command, but it is audited using the - original authenticated user. Finally, the + original authenticated user. The return token indicates the successful - execution, and the trailer concludes the + execution and the trailer concludes the record. - XML output format is also supported by - &man.praudit.1;, and can be selected using + XML output format is also supported + and can be selected by including . - - - - Reducing Audit Trails - 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: + Since audit logs may be very large, a + subset of records can be selected using + auditreduce. This example selects all + audit records produced for the user + trhodes stored in + AUDITFILE: - &prompt.root; auditreduce -u trhodes /var/audit/AUDITFILE | praudit - - This will select all audit records produced for - trhodes stored in - AUDITFILE. - - - - Delegating Audit Review Rights + &prompt.root; auditreduce -u trhodes /var/audit/AUDITFILE | praudit Members of the - audit group are - given permission to read audit trails in - /var/audit; by default, this group is + audit group have + permission to read audit trails in + /var/audit. By default, this group is empty, so only the - root user may read + root user can read audit trails. Users may be added to the audit 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. - Live Monitoring Using Audit Pipes - Audit pipes are cloning pseudo-devices in the device file - system which allow applications to tap the live audit record + 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: + stream. To track the live audit event stream: &prompt.root; praudit /dev/auditpipe @@ -704,7 +703,7 @@ trailer,133 make them accessible to the members of the audit group, add a devfs rule to - devfs.rules: + /etc/devfs.rules: add path 'auditpipe*' mode 0440 group audit @@ -715,56 +714,49 @@ trailer,133 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 I/O is audited, and praudit is run from an + SSH 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. + will generate another event. For this reason, it is advisable to run + praudit on an audit pipe device from sessions + without fine-grained I/O auditing. - Rotating Audit Trail Files + Rotating and Compressing Audit Trail Files - Audit trails are written to only by the kernel, and - managed only by the audit daemon, &man.auditd.8;. + 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, audit 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. + manipulated by the administrator: &prompt.root; audit -n - If &man.auditd.8; is not currently running, this command will fail and an error message will be produced. - Adding the following line to - /etc/crontab will force the rotation - every twelve hours from &man.cron.8;: + /etc/crontab will schedule this rotation + every twelve hours: 0 */12 * * * root /usr/sbin/audit -n - The change will take effect once you have saved the new - /etc/crontab. + The change will take effect once + /etc/crontab is saved. Automatic rotation of the audit trail file based on file size is possible using in - &man.audit.control.5;, and is described in the configuration - files section of this chapter. - - - - Compressing Audit Trails + audit.control as described in . 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 audit_warn 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 - audit_warn script to compress audit + rotated. For example, the following may be added to + /etc/security/audit_warn to compress audit trails on close: # @@ -785,7 +777,7 @@ fi 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.