From owner-svn-doc-all@FreeBSD.ORG Fri Mar 28 21:08:05 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 8DDC8C81; Fri, 28 Mar 2014 21:08:05 +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 79130292; Fri, 28 Mar 2014 21:08:05 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2SL85TL076919; Fri, 28 Mar 2014 21:08:05 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2SL854o076918; Fri, 28 Mar 2014 21:08:05 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403282108.s2SL854o076918@svn.freebsd.org> From: Dru Lavigne Date: Fri, 28 Mar 2014 21:08:05 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44379 - 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-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 28 Mar 2014 21:08:05 -0000 Author: dru Date: Fri Mar 28 21:08:05 2014 New Revision: 44379 URL: http://svnweb.freebsd.org/changeset/doc/44379 Log: White space fix only. Translators can ignore. 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 20:37:20 2014 (r44378) +++ head/en_US.ISO8859-1/books/handbook/audit/chapter.xml Fri Mar 28 21:08:05 2014 (r44379) @@ -44,16 +44,16 @@ requirements. --> MAC - 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 Basic - Security Module (BSM) Application Programming - Interface (API) and file format, and is interoperable - with the &solaris; and &macos; X audit + 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 Basic Security + Module (BSM) Application Programming + Interface (API) and file format, and is + interoperable with the &solaris; and &macos; X audit implementations. This chapter focuses on the installation and configuration @@ -82,14 +82,14 @@ requirements. --> - Understand &unix; and &os; basics - (). + Understand &unix; and &os; basics (). Be familiar with the basics of kernel - configuration/compilation - (). + configuration/compilation (). @@ -99,22 +99,21 @@ requirements. --> - The audit facility has some known limitations. - Not all security-relevant system events are - auditable and some login mechanisms, such as - Xorg-based display managers and third-party daemons, do not - properly configure auditing for user login sessions. + The audit facility has some known limitations. Not all + security-relevant system events are auditable and some login + mechanisms, such as Xorg-based + display managers and third-party daemons, do not properly + configure auditing for user login sessions. The security event auditing facility is able to generate - 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. + 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 the disk space requirements associated with high volume audit configurations. For example, it may be desirable to dedicate a file system to - /var/audit - so that other file systems are not affected if the audit file - system becomes full. + /var/audit so that other file systems are + not affected if the audit file system becomes full. @@ -132,23 +131,23 @@ requirements. --> a file, the building of a network connection, or a user logging in. Events are either attributable, meaning that they can be traced to an authenticated user, or - non-attributable. Examples - of non-attributable events are any events that occur before + non-attributable. Examples of + non-attributable events are any events that occur before authentication in the login process, such as bad password attempts. - class: a named set - of related events which are used in selection expressions. - Commonly used classes of events include file - creation (fc), exec (ex), and + class: a named set of related + events which are used in selection expressions. Commonly + used classes of events include file creation + (fc), exec (ex), and login_logout (lo). - record: an audit log - entry describing a security event. Records contain a record + record: 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 objects or arguments, and a success or failure @@ -156,28 +155,27 @@ requirements. --> - trail: 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. + trail: 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. - selection expression: a - string containing a list of prefixes and - audit event class names used to match events. + selection expression: a string + containing a list of prefixes and audit event class names + used to match events. preselection: the process by which the system identifies which events are of interest to 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 - authenticated and unauthenticated processes. + 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 authenticated and unauthenticated + processes. @@ -198,9 +196,9 @@ requirements. --> Audit Configuration 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 - /etc/rc.conf: + of the base &os; operating system. Kernel support can be + enabled by adding the following line to + /etc/rc.conf: auditd_enable="YES" @@ -208,8 +206,7 @@ requirements. --> &prompt.root; service auditd start - Users who prefer to compile - a custom kernel must include the + Users who prefer to compile a custom kernel must include the following line in their custom kernel configuration file: options AUDIT @@ -227,10 +224,10 @@ requirements. --> right, and two expressions are combined by appending one onto the other. - summarizes the default audit event - classes: + summarizes the default + audit event classes: - +
Default Audit Event Classes @@ -242,150 +239,147 @@ requirements. --> - - - all - all - Match all event classes. - - - - aa - authentication and authorization - - - - - ad - administrative - Administrative - actions performed on the system as a whole. - - - - ap - application - Application defined - action. - - - - cl - file close - Audit calls to the - close system call. - - - - ex - exec - Audit program execution. Auditing of command line - arguments and environmental variables is controlled via - &man.audit.control.5; using the argv - and envv parameters to the - policy setting. - - - - fa - file attribute access - Audit the - access of object attributes such as &man.stat.1; and - &man.pathconf.2;. - - - - fc - file create - Audit events where a - file is created as a result. - - - - fd - file delete - Audit events where file - deletion occurs. - - - - fm - file attribute modify - Audit events - where file attribute modification occurs, such as by - &man.chown.8;, &man.chflags.1;, and &man.flock.2;. - - - - fr - file read - Audit events in which data is read or files are opened for - reading. - - - - fw - file write - Audit events in which - data is written or files are written or modified. - - - - io - ioctl - Audit use of the ioctl system call. - - - - ip - ipc - Audit various forms of Inter-Process Communication, - including POSIX pipes and System V IPC - operations. - - - - lo - login_logout - Audit &man.login.1; - and &man.logout.1; events. - - - - na - non attributable - Audit - non-attributable events. - - - - no - invalid class - Match no audit - events. - - - - nt - network - Audit events related to network actions such as - &man.connect.2; and &man.accept.2;. - - - - ot - other - Audit miscellaneous events. - - - - pc - process - Audit process operations such as &man.exec.3; and - &man.exit.3;. - - - + + + all + all + Match all event classes. + + + + aa + authentication and authorization + + + + + ad + administrative + Administrative actions performed on the system as + a whole. + + + + ap + application + Application defined action. + + + + cl + file close + Audit calls to the + close system call. + + + + ex + exec + Audit program execution. Auditing of command + line arguments and environmental variables is + controlled via &man.audit.control.5; using the + argv and envv + parameters to the policy + setting. + + + + fa + file attribute access + Audit the access of object attributes such as + &man.stat.1; and &man.pathconf.2;. + + + + fc + file create + Audit events where a file is created as a + result. + + + + fd + file delete + Audit events where file deletion occurs. + + + + fm + file attribute modify + Audit events where file attribute modification + occurs, such as by &man.chown.8;, &man.chflags.1;, and + &man.flock.2;. + + + + fr + file read + Audit events in which data is read or files are + opened for reading. + + + + fw + file write + Audit events in which data is written or files + are written or modified. + + + + io + ioctl + Audit use of the ioctl + system call. + + + + ip + ipc + Audit various forms of Inter-Process + Communication, including POSIX pipes and System V + IPC operations. + + + + lo + login_logout + Audit &man.login.1; and &man.logout.1; + events. + + + + na + non attributable + Audit non-attributable events. + + + + no + invalid class + Match no audit events. + + + + nt + network + Audit events related to network actions such as + &man.connect.2; and &man.accept.2;. + + + + ot + other + Audit miscellaneous events. + + + + pc + process + Audit process operations such as &man.exec.3; and + &man.exit.3;. + + +
These audit event classes may be customized by modifying @@ -398,7 +392,7 @@ requirements. --> class and type. summarizes the available prefixes: - +
Prefixes for Audit Event Classes @@ -409,42 +403,39 @@ requirements. --> - - - + - Audit successful events in this - class. - - - - - - Audit failed events in this - class. - - - - ^ - Audit neither successful nor - failed events in this class. - - - - ^+ - Do not audit successful events - in this class. - - - - ^- - Do not audit failed events in - this class. - - + + + + + Audit successful events in this class. + + + + - + Audit failed events in this class. + + + + ^ + Audit neither successful nor failed events in + this class. + + + + ^+ + Do not audit successful events in this + class. + + + + ^- + Do not audit failed events in this class. + +
- If no prefix is present, both successful and failed instances of - the event will be audited. + If no prefix is present, both successful and failed + instances of the event will be audited. The following example selection string selects both successful and failed login/logout events, but only successful @@ -456,53 +447,55 @@ requirements. --> Configuration Files - The following configuration files for security event auditing are found in - /etc/security: - - - - audit_class: contains the - definitions of the audit classes. - - - - audit_control: 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. - - - - audit_event: textual names and - descriptions of system audit events and a list of - which classes each event is in. - - - - audit_user: user-specific audit - requirements to be combined with the global defaults at - login. - - - - audit_warn: 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. - - + The following configuration files for security event + auditing are found in + /etc/security: + + + + audit_class: contains the + definitions of the audit classes. + + + + audit_control: 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. + + + + audit_event: textual names and + descriptions of system audit events and a list of which + classes each event is in. + + + + audit_user: user-specific audit + requirements to be combined with the global defaults at + login. + + + + audit_warn: 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. + + - - Audit configuration files should be edited and maintained - carefully, as errors in configuration may result in improper - logging of events. - + + Audit configuration files should be edited and + maintained carefully, as errors in configuration may result + in improper logging of events. + In most cases, administrators will only need to modify - audit_control and audit_user. - The first file controls system-wide audit properties and policies and - the second file may be used to fine-tune auditing by user. + audit_control and + audit_user. The first file controls + system-wide audit properties and policies and the second file + may be used to fine-tune auditing by user. The <filename>audit_control</filename> File @@ -535,7 +528,8 @@ expire-after:10M The field sets the system-wide default preselection mask for attributable events. In the example above, successful and failed login/logout events as - well as authentication and authorization are audited for all users. + 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 @@ -543,29 +537,27 @@ expire-after:10M The entry specifies audit classes to be audited for non-attributed events, such as the - login/logout process and authentication and authorization. + login/logout process and authentication and + authorization. The entry specifies a comma-separated list of policy flags controlling various - aspects of audit behavior. The - cnt indicates that the system should - continue running despite an auditing failure (this flag is - 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. + aspects of audit behavior. The cnt + indicates that the system should continue running despite an + auditing failure (this flag is 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 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. + 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. - @@ -574,22 +566,21 @@ 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 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 entries - audit login/logout events and successful command execution - for root and - file creation and successful command execution for - www. If used with - the default audit_control, the - lo entry for - root is redundant, - and login/logout events will also be audited for - www. + 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 entries audit login/logout events + and successful command execution for root and file creation and + successful command execution for www. If used with the + default audit_control, the + lo entry for root is redundant, and + login/logout events will also be audited for www. root:lo,+ex:no www:fc,+ex:no @@ -600,35 +591,33 @@ www:fc,+ex:no Working with Audit Trails - 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, 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, to dump the entire - contents of a specified audit log in plain text: - - &prompt.root; praudit /var/audit/AUDITFILE - - Where - AUDITFILE is - the audit log to dump. - - Audit trails consist of a series of audit records made up - of tokens, which praudit prints sequentially, one per - line. Each token is of a specific type, such as - header (an audit record header) or - path (a file path from a name - lookup). The following is an example of an - execve event: + 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, 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, to dump the entire contents of a specified + audit log in plain text: + + &prompt.root; praudit /var/audit/AUDITFILE + + Where AUDITFILE is the audit log + to dump. + + Audit trails consist of a series of audit records made up of + tokens, which praudit prints sequentially, + one per line. Each token is of a specific type, such as + 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 + header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec exec arg,finger,doug path,/usr/bin/finger attribute,555,root,wheel,90,24918,104944 @@ -636,72 +625,66 @@ subject,robert,root,wheel,root,wheel,384 return,success,0 trailer,133 - This audit represents a successful - execve call, in which the command - 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 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 as the user - robert switched - to the root account - before running this command, but it is audited using the - original authenticated user. The - return token indicates the successful - execution and the trailer concludes the - record. - - XML output format is also supported - and can be selected by including - . - - 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 - - Members of the - audit group have - permission to read audit trails in - /var/audit. By default, this group is - empty, so only the - root user can read - audit trails. Users may be added to the - audit group in - 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. + This audit represents a successful + execve call, in which the command + 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 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 as the user + robert switched to the + root account before + running this command, but it is audited using the original + authenticated user. The return token + indicates the successful execution and the + trailer concludes the record. + + XML output format is also supported and + can be selected by including . + + 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 + + Members of the audit group have permission to + read audit trails in /var/audit. By + default, this group is empty, so only the root user can read audit trails. + Users may be added to the audit group in 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 - 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, - 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: + 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, 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: &prompt.root; praudit /dev/auditpipe By default, audit pipe device nodes are accessible only to the root user. To - make them accessible to the members of the - audit group, add a + make them accessible to the members of the audit group, add a devfs rule to /etc/devfs.rules: @@ -714,12 +697,14 @@ 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 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. For this reason, it is advisable to run - praudit on an audit pipe device from sessions - without fine-grained I/O auditing. + 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. For this reason, it is + advisable to run praudit on an audit pipe + device from sessions without fine-grained + I/O auditing. @@ -740,9 +725,8 @@ trailer,133 &prompt.root; audit -n - If &man.auditd.8; is not currently running, this - command will fail and an error message will be - produced. + 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 schedule this rotation @@ -765,8 +749,8 @@ trailer,133 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 - /etc/security/audit_warn to compress audit - trails on close: + /etc/security/audit_warn to compress + audit trails on close: # # Compress audit trail files on close.