]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man4/auditpipe.4
e3a7a94272b9b8b207a7c7bbb5b6b90ca71a9cea
[apple/xnu.git] / 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 Oct 18, 2010
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 au_mask_t .
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 au_mask_t .
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 au_mask_t .
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 au_mask_t .
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 allow applications to select which records are
256 dropped, possibly in the style of preselection.