1.\" Copyright (c) 2006 Robert N. M. Watson 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\"
| 1.\" Copyright (c) 2006 Robert N. M. Watson 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\"
|
25.\" $FreeBSD: head/share/man/man4/auditpipe.4 159273 2006-06-05 15:26:09Z rwatson $
| 25.\" $FreeBSD: head/share/man/man4/auditpipe.4 159282 2006-06-05 16:31:57Z joel $
|
26.\" 27.Dd May 5, 2006 28.Os 29.Dt AUDITPIPE 4 30.Sh NAME 31.Nm auditpipe 32.Nd Pseudo-device for live audit event tracking 33.Sh SYNOPSIS 34.Cd "options AUDIT" 35.Sh DESCRIPTION 36While audit trail files 37generated with 38.Xr audit 4 39and maintained by 40.Xr auditd 8 41provide a reliable long-term store for audit log information, current log 42files are owned by the audit daemon until terminated making them somewhat
| 26.\" 27.Dd May 5, 2006 28.Os 29.Dt AUDITPIPE 4 30.Sh NAME 31.Nm auditpipe 32.Nd Pseudo-device for live audit event tracking 33.Sh SYNOPSIS 34.Cd "options AUDIT" 35.Sh DESCRIPTION 36While audit trail files 37generated with 38.Xr audit 4 39and maintained by 40.Xr auditd 8 41provide a reliable long-term store for audit log information, current log 42files are owned by the audit daemon until terminated making them somewhat
|
43unwieldy for live montoring applications such as host-based intrusion
| 43unwieldy for live monitoring applications such as host-based intrusion
|
44detection. 45For example, the log may be cycled and new records written to a new file 46without notice to applications that may be accessing the file. 47.Pp 48The audit facility provides an audit pipe facility for applications requiring 49direct access to live BSM audit data for the purposes of real-time 50monitoring. 51Audit pipes are available via a clonable special device, 52.Pa /dev/auditpipe , 53subject to the permissions on the device node, and provide a 54.Qq tee 55of the audit event stream. 56As the device is clonable, more than one instance of the device may be opened 57at a time; each device instance will provide independent access to all 58records. 59.Pp 60The audit pipe device provides discrete BSM audit records; if the read buffer 61passed by the application is too small to hold the next record in the 62sequence, it will be dropped. 63Unlike audit data written to the audit trail, the reliability of record 64delivery is not guaranteed. 65In particular, when an audit pipe queue fills, records will be dropped. 66Audit pipe devices are blocking by default, but support non-blocking I/O, 67asynchronous I/O using SIGIO, and polled operation via 68.Xr select 2 69and 70.Xr poll 2 . 71.Pp 72Applications may choose to track the global audit trail, or configure local 73preselection parameters independent of the global audit trail parameters. 74.Ss Audit Pipe Queue Ioctls 75The following ioctls retrieve and set various audit pipe record queue 76properties: 77.Bl -tag -width AUDITPIPE_GET_QLIMIT_MIN 78.It AUDITPIPE_GET_QLEN 79Query the current number of records available for reading on the pipe. 80.It AUDITPIPE_GET_QLIMIT 81Retrieve the current maximum number of records that may be queued for reading 82on the pipe. 83.It AUDITPIPE_SET_QLIMIT 84Set the current maximum number of records that may be queued for reading on 85the pipe. 86The new limit must fall between the queue limit minimum and queue limit 87maximum queryable using the following two ioctls. 88.It AUDITPIPE_GET_QLIMIT_MIN 89Query the lowest possible maximum number of records that may be queued for 90reading on the pipe. 91.It AUDITPIPE_GET_QLIMIT_MAX 92Query the highest possible maximum number of records that may be queued for 93reading on the pipe. 94.It AUDITPIPE_FLUSH 95Flush all outstanding records on the audit pipe; useful after setting initial 96preselection properties to delete records queued during the configuration 97process which may not match the interests of the user process. 98.El 99.Ss Audit Pipe Preselection Mode Ioctls 100By default, the audit pipe facility configures pipes to present records 101matched by the system-wide audit trail, configured by 102.Xr auditd 8 . 103However, the preselection mechanism for audit pipes can be configured using 104alternative criteria, including pipe-local flags and naflags settings, as 105well as auid-specific selection masks. 106This allows applications to track events not captured in the global audit 107trail, as well as limit records presented to those of specific interest to 108the application. 109.Pp 110The following ioctls configure the preselection mode on an audit pipe: 111.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE 112.It AUDITPIPE_GET_PRESELECT_MODE 113Return the current preselect mode on the audit pipe. 114The ioctl argument should be of type 115.Vt int . 116.It AUDITPIPE_SET_PRESELECT_MODE 117Set the current preselection mode on the audit pipe. 118The ioctl argument should be of type 119.Vt int . 120.El 121.Pp 122Possible preselection mode values are: 123.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL 124.It AUDITPIPE_PRESELECT_MODE_TRAIL 125Use the global audit trail preselection parameters to select records for the 126audit pipe. 127.It AUDITPIPE_PRESELECT_MODE_LOCAL 128Use local audit pipe preselection; this model is similar to the global audit
| 44detection. 45For example, the log may be cycled and new records written to a new file 46without notice to applications that may be accessing the file. 47.Pp 48The audit facility provides an audit pipe facility for applications requiring 49direct access to live BSM audit data for the purposes of real-time 50monitoring. 51Audit pipes are available via a clonable special device, 52.Pa /dev/auditpipe , 53subject to the permissions on the device node, and provide a 54.Qq tee 55of the audit event stream. 56As the device is clonable, more than one instance of the device may be opened 57at a time; each device instance will provide independent access to all 58records. 59.Pp 60The audit pipe device provides discrete BSM audit records; if the read buffer 61passed by the application is too small to hold the next record in the 62sequence, it will be dropped. 63Unlike audit data written to the audit trail, the reliability of record 64delivery is not guaranteed. 65In particular, when an audit pipe queue fills, records will be dropped. 66Audit pipe devices are blocking by default, but support non-blocking I/O, 67asynchronous I/O using SIGIO, and polled operation via 68.Xr select 2 69and 70.Xr poll 2 . 71.Pp 72Applications may choose to track the global audit trail, or configure local 73preselection parameters independent of the global audit trail parameters. 74.Ss Audit Pipe Queue Ioctls 75The following ioctls retrieve and set various audit pipe record queue 76properties: 77.Bl -tag -width AUDITPIPE_GET_QLIMIT_MIN 78.It AUDITPIPE_GET_QLEN 79Query the current number of records available for reading on the pipe. 80.It AUDITPIPE_GET_QLIMIT 81Retrieve the current maximum number of records that may be queued for reading 82on the pipe. 83.It AUDITPIPE_SET_QLIMIT 84Set the current maximum number of records that may be queued for reading on 85the pipe. 86The new limit must fall between the queue limit minimum and queue limit 87maximum queryable using the following two ioctls. 88.It AUDITPIPE_GET_QLIMIT_MIN 89Query the lowest possible maximum number of records that may be queued for 90reading on the pipe. 91.It AUDITPIPE_GET_QLIMIT_MAX 92Query the highest possible maximum number of records that may be queued for 93reading on the pipe. 94.It AUDITPIPE_FLUSH 95Flush all outstanding records on the audit pipe; useful after setting initial 96preselection properties to delete records queued during the configuration 97process which may not match the interests of the user process. 98.El 99.Ss Audit Pipe Preselection Mode Ioctls 100By default, the audit pipe facility configures pipes to present records 101matched by the system-wide audit trail, configured by 102.Xr auditd 8 . 103However, the preselection mechanism for audit pipes can be configured using 104alternative criteria, including pipe-local flags and naflags settings, as 105well as auid-specific selection masks. 106This allows applications to track events not captured in the global audit 107trail, as well as limit records presented to those of specific interest to 108the application. 109.Pp 110The following ioctls configure the preselection mode on an audit pipe: 111.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE 112.It AUDITPIPE_GET_PRESELECT_MODE 113Return the current preselect mode on the audit pipe. 114The ioctl argument should be of type 115.Vt int . 116.It AUDITPIPE_SET_PRESELECT_MODE 117Set the current preselection mode on the audit pipe. 118The ioctl argument should be of type 119.Vt int . 120.El 121.Pp 122Possible preselection mode values are: 123.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL 124.It AUDITPIPE_PRESELECT_MODE_TRAIL 125Use the global audit trail preselection parameters to select records for the 126audit pipe. 127.It AUDITPIPE_PRESELECT_MODE_LOCAL 128Use local audit pipe preselection; this model is similar to the global audit
|
129trail configuration model, consisting of global flags and naflags paramaters,
| 129trail configuration model, consisting of global flags and naflags parameters,
|
130as well as a set of per-auid masks. 131These parameters are configured using further ioctls. 132.El 133.Pp 134After changing the audit pipe preselection mode, records selected under 135earlier preselection configuration may still be in the audit pipe queue. 136The application may flush the current record queue after changing the 137configuration to remove possibly undesired records. 138.Ss Audit Pipe Local Preselection Mode Ioctls
| 130as well as a set of per-auid masks. 131These parameters are configured using further ioctls. 132.El 133.Pp 134After changing the audit pipe preselection mode, records selected under 135earlier preselection configuration may still be in the audit pipe queue. 136The application may flush the current record queue after changing the 137configuration to remove possibly undesired records. 138.Ss Audit Pipe Local Preselection Mode Ioctls
|
139The following ioctls configure the preselection paramaters used when an audit
| 139The following ioctls configure the preselection parameters used when an audit
|
140pipe is configured for the 141.Dv AUDITPIPE_PRESELECT_MODE_LOCAL 142preselection mode. 143.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS 144.It AUDITPIPE_GET_PRESELECT_FLAGS 145Retrieve the current default preselection flags for attributable events on 146the pipe. 147These flags correspond to the 148.Dv flags 149field in 150.Xr audit_control 5 . 151The ioctl argument should be of type 152.Vt u_int . 153.It AUDITPIPE_SET_PRESELECT_FLAGS 154Set the current default preselection flags for attributable events on the 155pipe. 156These flags correspond to the 157.Dv flags 158field in 159.Xr audit_control 5 . 160The ioctl argument should be of type 161.Vt u_int . 162.It AUDITPIPE_GET_PRESELECT_NAFLAGS 163Retrieve the current default preselection flags for non-attributable events 164on the pipe. 165These flags correspond to the 166.Dv naflags 167field in 168.Xr audit_control 5 . 169The ioctl argument should be of type 170.Vt u_int . 171.It AUDITPIPE_SET_PRESELECT_NAFLAGS 172Set the current default preselection flags for non-attributable events on the 173pipe. 174These flags correspond to the 175.Dv naflags 176field in 177.Xr audit_control 5 . 178The ioctl argument should be of type 179.Vt u_int . 180.It AUDITPIPE_GET_PRESELECT_AUID 181Query the current preselection masks for a specific auid on the pipe. 182The ioctl argument should be of type 183.Vt struct auditpipe_preselect . 184The auid to query is specified via the 185.Va ap_auid 186field of type 187.Vt au_id_t ; 188the mask will be returned via 189.Va ap_mask 190of type 191.Vt au_mask_t . 192.It AUDITPIPE_SET_PRESELECT_AUID 193Set the current preselection masks for a specific auid on the pipe. 194Arguments are identical to 195.Dv AUDITPIPE_GET_PRESELECT_AUID, 196except that the caller should properly initialize the 197.Va ap_mask 198field to hold the desired preselection mask. 199.It AUDITPIPE_DELETE_PRESELECT_AUID 200Delete the current preselection mask for a specific auid on the pipe. 201Once called, events associated with the specified auid will use the default 202flags mask. 203The ioctl argument should be of type 204.Vt au_id_t . 205.It AUDITPIPE_FLUSH_PRESELECT_AUID 206Delete all auid specific preselection specifications. 207.El 208.Sh EXAMPLES 209.Xr praudit 1 210may be directly executed on 211.Pa /dev/auditpipe 212to review the default audit trail. 213.Sh SEE ALSO 214.Xr poll 2 , 215.Xr select 2 , 216.Xr audit 4 , 217.Xr audit_control 5 , 218.Xr audit 8 , 219.Xr auditd 8 220.Sh AUTHORS 221The audit pipe facility was designed and implemented by 222.An Robert Watson Aq rwatson@FreeBSD.org . 223.Pp 224The Basic Security Module (BSM) interface to audit records and audit event 225stream format were defined by Sun Microsystems. 226.Sh HISTORY 227The OpenBSM implementation was created by McAfee Research, the security 228division of McAfee Inc., under contract to Apple Computer Inc. in 2004. 229It was subsequently adopted by the TrustedBSD Project as the foundation for 230the OpenBSM distribution. 231.Pp 232Support for kernel audit first appeared in 233.Fx 6.2 . 234.Sh BUGS 235See the 236.Xr audit 4 237manual page for information on audit-related bugs and limitations. 238.Pp 239The configurable preselection mechanism mirrors the selection model present 240for the global audit trail. 241It might be desirable to provided a more flexible selection model. 242.Pp 243The per-pipe audit event queue is fifo, with drops occuring if either the 244user thread provides in sufficient for the record on the queue head, or on 245enqueue if there is insufficient room. 246It might be desirable to support partial reads of records, which would be 247more compatible with buffered I/O as implemented in system libraries, and to 248allow applications to select which records are dropped, possibly in the style 249of preselection.
| 140pipe is configured for the 141.Dv AUDITPIPE_PRESELECT_MODE_LOCAL 142preselection mode. 143.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS 144.It AUDITPIPE_GET_PRESELECT_FLAGS 145Retrieve the current default preselection flags for attributable events on 146the pipe. 147These flags correspond to the 148.Dv flags 149field in 150.Xr audit_control 5 . 151The ioctl argument should be of type 152.Vt u_int . 153.It AUDITPIPE_SET_PRESELECT_FLAGS 154Set the current default preselection flags for attributable events on the 155pipe. 156These flags correspond to the 157.Dv flags 158field in 159.Xr audit_control 5 . 160The ioctl argument should be of type 161.Vt u_int . 162.It AUDITPIPE_GET_PRESELECT_NAFLAGS 163Retrieve the current default preselection flags for non-attributable events 164on the pipe. 165These flags correspond to the 166.Dv naflags 167field in 168.Xr audit_control 5 . 169The ioctl argument should be of type 170.Vt u_int . 171.It AUDITPIPE_SET_PRESELECT_NAFLAGS 172Set the current default preselection flags for non-attributable events on the 173pipe. 174These flags correspond to the 175.Dv naflags 176field in 177.Xr audit_control 5 . 178The ioctl argument should be of type 179.Vt u_int . 180.It AUDITPIPE_GET_PRESELECT_AUID 181Query the current preselection masks for a specific auid on the pipe. 182The ioctl argument should be of type 183.Vt struct auditpipe_preselect . 184The auid to query is specified via the 185.Va ap_auid 186field of type 187.Vt au_id_t ; 188the mask will be returned via 189.Va ap_mask 190of type 191.Vt au_mask_t . 192.It AUDITPIPE_SET_PRESELECT_AUID 193Set the current preselection masks for a specific auid on the pipe. 194Arguments are identical to 195.Dv AUDITPIPE_GET_PRESELECT_AUID, 196except that the caller should properly initialize the 197.Va ap_mask 198field to hold the desired preselection mask. 199.It AUDITPIPE_DELETE_PRESELECT_AUID 200Delete the current preselection mask for a specific auid on the pipe. 201Once called, events associated with the specified auid will use the default 202flags mask. 203The ioctl argument should be of type 204.Vt au_id_t . 205.It AUDITPIPE_FLUSH_PRESELECT_AUID 206Delete all auid specific preselection specifications. 207.El 208.Sh EXAMPLES 209.Xr praudit 1 210may be directly executed on 211.Pa /dev/auditpipe 212to review the default audit trail. 213.Sh SEE ALSO 214.Xr poll 2 , 215.Xr select 2 , 216.Xr audit 4 , 217.Xr audit_control 5 , 218.Xr audit 8 , 219.Xr auditd 8 220.Sh AUTHORS 221The audit pipe facility was designed and implemented by 222.An Robert Watson Aq rwatson@FreeBSD.org . 223.Pp 224The Basic Security Module (BSM) interface to audit records and audit event 225stream format were defined by Sun Microsystems. 226.Sh HISTORY 227The OpenBSM implementation was created by McAfee Research, the security 228division of McAfee Inc., under contract to Apple Computer Inc. in 2004. 229It was subsequently adopted by the TrustedBSD Project as the foundation for 230the OpenBSM distribution. 231.Pp 232Support for kernel audit first appeared in 233.Fx 6.2 . 234.Sh BUGS 235See the 236.Xr audit 4 237manual page for information on audit-related bugs and limitations. 238.Pp 239The configurable preselection mechanism mirrors the selection model present 240for the global audit trail. 241It might be desirable to provided a more flexible selection model. 242.Pp 243The per-pipe audit event queue is fifo, with drops occuring if either the 244user thread provides in sufficient for the record on the queue head, or on 245enqueue if there is insufficient room. 246It might be desirable to support partial reads of records, which would be 247more compatible with buffered I/O as implemented in system libraries, and to 248allow applications to select which records are dropped, possibly in the style 249of preselection.
|