Date: Fri, 5 May 2006 13:59:26 GMT From: Robert Watson <rwatson@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 96701 for review Message-ID: <200605051359.k45DxQ6k058220@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=96701 Change 96701 by rwatson@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@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@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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200605051359.k45DxQ6k058220>