share/man/man4/auditpipe.4

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