From owner-svn-doc-all@FreeBSD.ORG Fri Mar 28 19:05:36 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 078847B5; Fri, 28 Mar 2014 19:05:36 +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 E78286DB; Fri, 28 Mar 2014 19:05:35 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2SJ5ZUe026280; Fri, 28 Mar 2014 19:05:35 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2SJ5Zcp026279; Fri, 28 Mar 2014 19:05:35 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403281905.s2SJ5Zcp026279@svn.freebsd.org> From: Dru Lavigne Date: Fri, 28 Mar 2014 19:05:35 +0000 (UTC) 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 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 19:05:36 -0000 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. --> MAC - The &os; operating system includes support for fine-grained - security event auditing. Event auditing allows the reliable, + 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 - BSM 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 (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 - of Event Auditing. It explains audit policies, and provides an + of event auditing. It explains audit policies and provides an example audit configuration. After reading this chapter, you will know: - What Event Auditing is and how it works. + What event auditing is and how it works. - How to configure Event Auditing on &os; for users and + How to configure event auditing on &os; for users and processes. @@ -98,55 +99,55 @@ requirements. --> - 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 + 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 + 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 /var/audit tree + /var/audit so that other file systems are not affected if the audit file system becomes full. - Key Terms in This Chapter + Key Terms - Before reading this chapter, a few key audit-related terms - must be explained: + The following terms are related to security event + auditing: - event: An auditable event is any + event: 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 attributable, meaning that they can be traced to an authenticated user, or - non-attributable if they cannot be. Examples + non-attributable. Examples of non-attributable events are any events that occur before authentication in the login process, such as bad password attempts. - class: Event classes are named sets - of related events, and are used in selection expressions. + 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 + creation (fc), exec (ex), and login_logout (lo). - record: A record is an audit log + 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 @@ -155,25 +156,24 @@ requirements. --> - trail: An audit trail, or log file, - consists of a series of audit records describing security - events. Typically, trails are in roughly chronological + 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 selection - expression is a string containing a list of prefixes and + selection expression: a + string containing a list of prefixes and audit event class names used to match events. - preselection: The process by which + preselection: 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. --> - reduction: The process by which + reduction: 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. --> - - Installing Audit Support - - 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: - - options AUDIT - - Rebuild and reinstall the kernel via the normal process - explained in . - - 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;: - - auditd_enable="YES" - - Audit support must then be started by a reboot, or by - manually starting the audit daemon: - - service auditd start - - Audit Configuration - All configuration files for security audit are found in - /etc/security. The following files must be - present before the audit daemon is started: + 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: - - - 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, - maximum audit trail size, etc. - + auditd_enable="YES" - - audit_event - Textual names and - descriptions of system audit events, as well as a list of - which classes each event is in. - + Then, start the audit daemon: - - audit_user - User-specific audit - requirements, which are combined with the global defaults at - login. - + &prompt.root; service auditd start - - 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. - - + Users who prefer to compile + a custom kernel must include the + following line in their custom kernel configuration file: - - Audit configuration files should be edited and maintained - carefully, as errors in configuration may result in improper - logging of events. - + options AUDIT Event Selection Expressions @@ -280,170 +227,218 @@ requirements. --> right, and two expressions are combined by appending one onto the other. - The following list contains the default audit event - classes present in audit_class: + summarizes the default audit event + classes: + + + Default Audit Event Classes - - - all - all - - Match all event classes. - - - - 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 + + + + Class Name + Description + Action + + + + + + all + all + Match all event classes. + + + + 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. - + policy setting. + - - fa - - file attribute access - Audit the - access of object attributes such as &man.stat.1;, - &man.pathconf.2; and similar events. - - - - 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 - &man.chown.8;, &man.chflags.1;, &man.flock.2;, etc. - - - - fr - file read - - Audit events in which data is read, files are opened for - reading, etc. - - - - fw - - file write - Audit events in which - data is written, files are written or modified, - etc. - - - - io - ioctl - - Audit use of the &man.ioctl.2; system call. - - - - ip - ipc - - Audit various forms of Inter-Process Communication, + + 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 occurring on the system. - - - - 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;. - + 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 the audit_class and audit_ event configuration files. - Each audit class in the list is combined with a prefix + 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. + class and type. summarizes + the available prefixes: + + + Prefixes for Audit Event Classes + + + + + Prefix + Action + + + + + + + + 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. + + + +
- - - (none) Audit both successful and failed instances of - the event. - - - - + 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. The following example selection string selects both successful and failed login/logout events, but only successful @@ -455,11 +450,53 @@ requirements. --> Configuration Files - In most cases, administrators will need to modify only two - files when configuring the audit system: audit_ - control and audit_user. - The first controls system-wide audit properties and policies; - the second may be used to fine-tune auditing by user. + 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. + + + 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. The <filename>audit_control</filename> File @@ -468,11 +505,13 @@ requirements. --> specified in audit_control: dir:/var/audit -flags:lo -minfree:20 -naflags:lo -policy:cnt -filesz:0 +dist:off +flags:lo,aa +minfree:5 +naflags:lo,aa +policy:cnt,argv +filesz:2M +expire-after:10M The entry is used to set one or more directories where audit logs will be stored. If more