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