Date: Fri, 28 Mar 2014 19:05:35 +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: r44377 - head/en_US.ISO8859-1/books/handbook/audit Message-ID: <201403281905.s2SJ5Zcp026279@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403281905.s2SJ5Zcp026279>