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.Dd April 28, 2019 26.Dt AUDITPIPE 4 27.Os 28.Sh NAME 29.Nm auditpipe 30.Nd "pseudo-device for live audit event tracking" 31.Sh SYNOPSIS 32.Cd "options AUDIT" 33.Sh DESCRIPTION 34While audit trail files 35generated with 36.Xr audit 4 37and maintained by 38.Xr auditd 8 39provide a reliable long-term store for audit log information, current log 40files are owned by the audit daemon until terminated making them somewhat 41unwieldy for live monitoring applications such as host-based intrusion 42detection. 43For example, the log may be cycled and new records written to a new file 44without notice to applications that may be accessing the file. 45.Pp 46The audit facility provides an audit pipe facility for applications requiring 47direct access to live BSM audit data for the purposes of real-time 48monitoring. 49Audit pipes are available via a clonable special device, 50.Pa /dev/auditpipe , 51subject to the permissions on the device node, and provide a 52.Qq tee 53of the audit event stream. 54As the device is clonable, more than one instance of the device may be opened 55at a time; each device instance will provide independent access to all 56records. 57.Pp 58The audit pipe device provides discrete BSM audit records; if the read buffer 59passed by the application is too small to hold the next record in the 60sequence, it will be dropped. 61Unlike audit data written to the audit trail, the reliability of record 62delivery is not guaranteed. 63In particular, when an audit pipe queue fills, records will be dropped. 64Audit pipe devices are blocking by default, but support non-blocking I/O, 65asynchronous I/O using 66.Dv SIGIO , 67and 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 ".Dv AUDITPIPE_GET_MAXAUDITDATA" 78.It Dv AUDITPIPE_GET_QLEN 79Query the current number of records available for reading on the pipe. 80.It Dv AUDITPIPE_GET_QLIMIT 81Retrieve the current maximum number of records that may be queued for reading 82on the pipe. 83.It Dv 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 Dv AUDITPIPE_GET_QLIMIT_MIN 89Query the lowest possible maximum number of records that may be queued for 90reading on the pipe. 91.It Dv AUDITPIPE_GET_QLIMIT_MAX 92Query the highest possible maximum number of records that may be queued for 93reading on the pipe. 94.It Dv 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.It Dv AUDITPIPE_GET_MAXAUDITDATA 99Query the maximum size of an audit record, which is a useful minimum size for 100a user space buffer intended to hold audit records read from the audit pipe. 101.El 102.Ss Audit Pipe Preselection Mode Ioctls 103By default, the audit pipe facility configures pipes to present records 104matched by the system-wide audit trail, configured by 105.Xr auditd 8 . 106However, the preselection mechanism for audit pipes can be configured using 107alternative criteria, including pipe-local flags and naflags settings, as 108well as auid-specific selection masks. 109This allows applications to track events not captured in the global audit 110trail, as well as limit records presented to those of specific interest to 111the application. 112.Pp 113The following ioctls configure the preselection mode on an audit pipe: 114.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_MODE" 115.It Dv AUDITPIPE_GET_PRESELECT_MODE 116Return the current preselect mode on the audit pipe. 117The ioctl argument should be of type 118.Vt int . 119.It Dv AUDITPIPE_SET_PRESELECT_MODE 120Set the current preselection mode on the audit pipe. 121The ioctl argument should be of type 122.Vt int . 123.El 124.Pp 125Possible preselection mode values are: 126.Bl -tag -width ".Dv AUDITPIPE_PRESELECT_MODE_TRAIL" 127.It Dv AUDITPIPE_PRESELECT_MODE_TRAIL 128Use the global audit trail preselection parameters to select records for the 129audit pipe. 130.It Dv AUDITPIPE_PRESELECT_MODE_LOCAL 131Use local audit pipe preselection; this model is similar to the global audit 132trail configuration model, consisting of global flags and naflags parameters, 133as well as a set of per-auid masks. 134These parameters are configured using further ioctls. 135.El 136.Pp 137After changing the audit pipe preselection mode, records selected under 138earlier preselection configuration may still be in the audit pipe queue. 139The application may flush the current record queue after changing the 140configuration to remove possibly undesired records. 141.Ss Audit Pipe Local Preselection Mode Ioctls 142The following ioctls configure the preselection parameters used when an audit 143pipe is configured for the 144.Dv AUDITPIPE_PRESELECT_MODE_LOCAL 145preselection mode. 146.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_NAFLAGS" 147.It Dv AUDITPIPE_GET_PRESELECT_FLAGS 148Retrieve the current default preselection flags for attributable events on 149the pipe. 150These flags correspond to the 151.Va flags 152field in 153.Xr audit_control 5 . 154The ioctl argument should be of type 155.Vt au_mask_t . 156.It Dv AUDITPIPE_SET_PRESELECT_FLAGS 157Set the current default preselection flags for attributable events on the 158pipe. 159These flags correspond to the 160.Va flags 161field in 162.Xr audit_control 5 . 163The ioctl argument should be of type 164.Vt au_mask_t . 165.It Dv AUDITPIPE_GET_PRESELECT_NAFLAGS 166Retrieve the current default preselection flags for non-attributable events 167on the pipe. 168These flags correspond to the 169.Va naflags 170field in 171.Xr audit_control 5 . 172The ioctl argument should be of type 173.Vt au_mask_t . 174.It Dv AUDITPIPE_SET_PRESELECT_NAFLAGS 175Set the current default preselection flags for non-attributable events on the 176pipe. 177These flags correspond to the 178.Va naflags 179field in 180.Xr audit_control 5 . 181The ioctl argument should be of type 182.Vt au_mask_t . 183.It Dv AUDITPIPE_GET_PRESELECT_AUID 184Query the current preselection masks for a specific auid on the pipe. 185The ioctl argument should be of type 186.Vt "struct auditpipe_ioctl_preselect" . 187The auid to query is specified via the 188.Va ap_auid 189field of type 190.Vt au_id_t ; 191the mask will be returned via 192.Va ap_mask 193of type 194.Vt au_mask_t . 195.It Dv AUDITPIPE_SET_PRESELECT_AUID 196Set the current preselection masks for a specific auid on the pipe. 197Arguments are identical to 198.Dv AUDITPIPE_GET_PRESELECT_AUID , 199except that the caller should properly initialize the 200.Va ap_mask 201field to hold the desired preselection mask. 202.It Dv AUDITPIPE_DELETE_PRESELECT_AUID 203Delete the current preselection mask for a specific auid on the pipe. 204Once called, events associated with the specified auid will use the default 205flags mask. 206The ioctl argument should be of type 207.Vt au_id_t . 208.It Dv AUDITPIPE_FLUSH_PRESELECT_AUID 209Delete all auid specific preselection specifications. 210.El 211.Sh EXAMPLES 212The 213.Xr praudit 1 214utility 215may be directly executed on 216.Pa /dev/auditpipe 217to review the default audit trail. 218.Sh SEE ALSO 219.Xr poll 2 , 220.Xr select 2 , 221.Xr audit 4 , 222.Xr dtaudit 4 , 223.Xr audit_control 5 , 224.Xr audit 8 , 225.Xr auditd 8 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 AUTHORS 235The audit pipe facility was designed and implemented by 236.An Robert Watson Aq Mt rwatson@FreeBSD.org . 237.Pp 238The Basic Security Module (BSM) interface to audit records and audit event 239stream format were defined by Sun Microsystems. 240.Sh BUGS 241See the 242.Xr audit 4 243manual page for information on audit-related bugs and limitations. 244.Pp 245The configurable preselection mechanism mirrors the selection model present 246for the global audit trail. 247It might be desirable to provide a more flexible selection model. 248.Pp 249The per-pipe audit event queue is fifo, with drops occurring if either the 250user thread provides in sufficient for the record on the queue head, or on 251enqueue if there is insufficient room. 252It might be desirable to support partial reads of records, which would be 253more compatible with buffered I/O as implemented in system libraries, and to 254allow applications to select which records are dropped, possibly in the style 255of preselection. 256