PERFORCE change 96701 for review

Fri May 5 14:00:20 UTC 2006

http://perforce.freebsd.org/chv.cgi?CH=96701

Change 96701 by rwatson at rwatson_zoo on 2006/05/05 13:58:05

	Create more detailed auditpipe(4) page by removing audit(4)
	information from auditpipe(4) and vice versa; add a long and
	possibly accurate section on the auditpipe ioctls used to
	configure audit pipes.

Affected files ...

.. //depot/projects/trustedbsd/audit3/share/man/man4/audit.4#2 edit
.. //depot/projects/trustedbsd/audit3/share/man/man4/auditpipe.4#2 edit

Differences ...

==== //depot/projects/trustedbsd/audit3/share/man/man4/audit.4#2 (text+ko) ====

@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD: src/share/man/man4/audit.4,v 1.6 2006/02/06 20:27:00 rwatson Exp $
 .\"
-.Dd February 6, 2006
+.Dd May 5, 2006
 .Os
 .Dt AUDIT 4
 .Sh NAME
@@ -62,37 +62,11 @@
 space conditions, and requests to terminate auditing.
 This device is not intended for use by applications.
 .Ss Audit Pipe Special Devices
-While audit trail files maintained by
-.Xr auditd 8
-provide a reliable long-term store for audit log information, current log
-files are owned by the audit daemon until terminated making them somewhat
-unwieldy for live montoring applications such as host-based intrusion
-detection.
-For example, the log may be cycled and new records written to a new file
-without notice to applications that may be accessing the file.
-.Pp
-The audit facility provides an audit pipe facility for applications requiring
-direct access to live BSM audit data for the purposes of real-time
-monitoring.
-Audit pipes are available via a clonable special device,
-.Pa /dev/auditpipe ,
-subject to the permissions on the device node, and provide a 
-.Qq tee
-of the audit event stream.
-As the device is clonable, more than one instance of the device may be opened
-at a time; each device instance will provide access to all records.
-.Pp
-The audit pipe device provides discreet BSM audit records; if the read buffer
-passed by the application is too small to hold the next record in the
-sequence, it will be dropped.
-Unlike audit data written to the audit trail, the reliability of record
-delivery is not guaranteed.
-In particular, when an audit pipe queue fills, records will be dropped.
-Audit pipe devices are blocking by default, but support non-blocking I/O,
-asynchronous I/O using SIGIO, and support for polled operation via
-.Xr select 2
-and
-.Xr poll 2 .
+Audit pipe special devices, discussed in
+.Xr auditpipe 4 ,
+provide a configurable live tracking mechanism to allow applications to
+tee the audit trail, as well as to configure custom preselection paramaters
+to track users and events in a fine-grained manner.
 .Sh SEE ALSO
 .Xr auditreduce 1 ,
 .Xr praudit 1 ,
@@ -106,6 +80,7 @@
 .Xr setaudit 2 ,
 .Xr setauid 2 ,
 .Xr libbsm 3 ,
+.Xr auditpipe 4 ,
 .Xr audit.log 5 ,
 .Xr audit_class 5 ,
 .Xr audit_control 5 ,

==== //depot/projects/trustedbsd/audit3/share/man/man4/auditpipe.4#2 (text+ko) ====

@@ -22,48 +22,22 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/share/man/man4/audit.4,v 1.6 2006/02/06 20:27:00 rwatson Exp $
+.\" $FreeBSD$
 .\"
-.Dd February 6, 2006
+.Dd May 5, 2006
 .Os
-.Dt AUDIT 4
+.Vt AUDITPIPE 4
 .Sh NAME
-.Nm audit
-.Nd Security Event Audit
+.Nm auditpipe
+.Nd Pseudo-device for live audit event tracking
 .Sh SYNOPSIS
 .Cd "options AUDIT"
 .Sh DESCRIPTION
-Security Event Audit is a facility to provide fine-grained, configurable
-logging of security-relevant events, and is intended to meet the requirements
-of the Common Criteria (CC) Common Access Protection Profile (CAPP)
-evaluation.
-The
-.Fx
-audit facility implements the de facto industry standard BSM API, file
-formats, and command line interface, first found in the Solaris operating
-system.
-Information on the user space implementation can be found in
-.Xr libbsm 3 .
-.Pp
-Audit support is enabled at boot, if present in the kernel, using an
-.Xr rc.conf 5
-flag.
-The audit daemon,
-.Xr auditd 8 ,
-is responsible for configuring the kernel to perform audit, pushing
-configuration data from the various audit configuration files into the
-kernel.
-.Ss Audit Special Device
-The kernel audit facility provides a special device,
-.Pa /dev/audit ,
-which is used by
+While audit trail files
+generated with
+.Xr audit 4
+and maintained by
 .Xr auditd 8
-to monitor for audit events, such as requests to cycle the log, low disk
-space conditions, and requests to terminate auditing.
-This device is not intended for use by applications.
-.Ss Audit Pipe Special Devices
-While audit trail files maintained by
-.Xr auditd 8
 provide a reliable long-term store for audit log information, current log
 files are owned by the audit daemon until terminated making them somewhat
 unwieldy for live montoring applications such as host-based intrusion
@@ -93,38 +67,128 @@
 .Xr select 2
 and
 .Xr poll 2 .
+.Ss Preselection
+By default, the audit pipe facility configures pipes to present records
+matched by the system-wide audit trail, configured by
+.Xr auditd 8 .
+However, the preselection mechanism for audit pipes can be configured using
+alternative criteria, including pipe-local flags and naflags settings, as
+well as auid-specific selection masks.
+.Ss Ioctls
+These properties are configured using ioctls on the open audit pipe device.
+.Bl -tag -width AUDITPIPE_DELETE_PRESELECT_AUID
+.It AUDITPIPE_GET_QLEN
+Query the current number of records available for reading on the pipe.
+.It AUDITPIPE_GET_QLIMIT
+Retrieve the current maximum number of records that may be queued for reading
+on the pipe.
+.It AUDITPIPE_SET_QLIMIT
+Set the current maximum number of records that may be queued for reading on
+the pipe.
+The new limit must fall between the queue limit minimum and queue limit
+maximum queryable using the following two ioctls.
+.It AUDITPIPE_GET_QLIMIT_MIN
+Query the lowest possible maximum number of records that may be queued for
+reading on the pipe.
+.It AUDITPIPE_GET_QLIMIT_MAX
+Query the highest possible maximum number of records that may be queued for
+reading on the pipe.
+.It AUDITPIPE_GET_PRESELECT_FLAGS
+Retrieve the current default preselection flags for attributable events on
+the pipe.
+These flags correspond to the
+.Dv flags
+field in
+.Xr audit_control 5 .
+The ioctl argument should be of type
+.Vt u_int.
+.It AUDITPIPE_SET_PRESELECT_FLAGS
+Set the current default preselection flags for attributable events on the
+pipe.
+These flags correspond to the
+.Dv flags
+field in
+.Xr audit_control 5 .
+The ioctl argument should be of type
+.Vt u_int.
+.It AUDITPIPE_GET_PRESELECT_NAFLAGS
+Retrieve the current default preselection flags for non-attributable events
+on the pipe.
+These flags correspond to the
+.Dv naflags
+field in
+.Xr audit_control 5 .
+The ioctl argument should be of type
+.Vt u_int.
+.It AUDITPIPE_SET_PRESELECT_NAFLAGS
+Set the current default preselection flags for non-attributable events on the
+pipe.
+These flags correspond to the
+.Dv naflags
+field in
+.Xr audit_control 5 .
+The ioctl argument should be of type
+.Vt u_int.
+.It AUDITPIPE_GET_PRESELECT_AUID
+Query the current preselection masks for a specific auid on the pipe.
+The ioctl argument should be of type
+.Vt struct auditpipe_preselect .
+The auid to query is specified via the
+.Va ap_auid
+field; the mask will be returned via
+.Va ap_mask
+of type
+.Vt au_mask_t .
+.It AUDITPIPE_SET_PRESELECT_AUID
+Set the current preselection masks for a specific auid on the pipe.
+Arguments are identical to
+.Dv AUDITPIPE_GET_PRESELECT_AUID,
+except that the caller should properly initialize the
+.Va ap_mask
+field to hold the desired preselection mask.
+.It AUDITPIPE_DELETE_PRESELECT_AUID
+Delete the current preselection mask for a specific auid on the pipe.
+Once called, events associated with the specified auid will use the default
+flags mask.
+.It AUDITPIPE_FLUSH_PRESELECT_AUID
+Delete all auid specific preselection specifications.
+.It AUDITPIPE_GET_PRESELECT_TRAIL
+Return the current value of the preselection trail flag on the audit pipe;
+this flag indicates that the system audit trail preselection masks are to be
+used in selecting which events can be read from the audit pipe.
+If the value is 1, the trail masks are used; if the value is 0, then the
+pipe preselection masks will be used.
+The ioctl argument should be of type
+.Vt int .
+.It AUDITPIPE_SET_PRESELECT_TRAIL
+Set the current value of the preselection trail flag on the audit pipe, with
+values as described for
+.Dv AUDITPIPE_GET_PRESELECT_TRAIL.
+The ioctl argument should be of type
+.Vt int .
+.It AUDITPIPE_FLUSH
+Flush all outstanding records on the audit pipe; useful after setting initial
+preselection properties to delete records queued during the configuration
+process which may not match the interests of the user process.
+.El
+.Sh EXAMPLES
+.Xr praudit 1
+may be directly executed on
+.Pa /dev/auditpipe
+to review the default audit trail.
 .Sh SEE ALSO
-.Xr auditreduce 1 ,
-.Xr praudit 1 ,
-.Xr audit 2 ,
-.Xr auditctl 2 ,
-.Xr auditon 2 ,
-.Xr getaudit 2 ,
-.Xr getauid 2 ,
 .Xr poll 2 ,
 .Xr select 2 ,
-.Xr setaudit 2 ,
-.Xr setauid 2 ,
-.Xr libbsm 3 ,
-.Xr audit.log 5 ,
-.Xr audit_class 5 ,
+.Xr audit 4 ,
 .Xr audit_control 5 ,
-.Xr audit_event 5 ,
-.Xr audit_user 5 ,
-.Xr audit_warn 5 ,
-.Xr rc.conf 5 ,
 .Xr audit 8 ,
 .Xr auditd 8
 .Sh AUTHORS
-This software was created by McAfee Research, the security research division
-of McAfee, Inc., under contract to Apple Computer Inc.
-Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc.
+The audit pipe facility was created by
+.An Robert Watson Aq rwatson at FreeBSD.org .
 .Pp
 The Basic Security Module (BSM) interface to audit records and audit event
 stream format were defined by Sun Microsystems.
-.Pp
-This manual page was written by
-.An Robert Watson Aq rwatson at FreeBSD.org .
 .Sh HISTORY
 The OpenBSM implementation was created by McAfee Research, the security
 division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
@@ -132,23 +196,8 @@
 the OpenBSM distribution.
 .Pp
 Support for kernel audit first appeared in
-.Fx 6.1 .
+.Fx 6.2 .
 .Sh BUGS
-The audit facility in
-.Fx
-is considered experimental, and production deployment should occur only after
-careful consideration of the risks of deploying experimental software.
-.Pp
-The
-.Fx
-kernel does not fully validate that audit records submitted by user
-applications are syntactically valid BSM; as submission of records is limited
-to privileged processes, this is not a critical bug.
-.Pp
-Instrumentation of auditable events in the kernel is not complete, as some
-system calls do not generate audit records, or generate audit records with
-incomplete argument information.
-.Pp
-Mandatory Access Control (MAC) labels, as provided by the
-.Xr mac 4
-facility, are not audited as part of records involving MAC decisions.
+See the
+.Xr audit 4
+man page for information on audit-related bugs and limitations.
