[apple/xnu.git] / bsd / man / man4 / auditpipe.4

.\" Copyright (c) 2006 Robert N. M. Watson
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man4/auditpipe.4,v 1.6 2008/05/02 17:36:22 rwatson Exp $
.\"
.Dd Oct 18, 2010
.Os
.Dt AUDITPIPE 4
.Sh NAME
.Nm auditpipe
.Nd "pseudo-device for live audit event tracking"
.Sh SYNOPSIS
.Cd "pseudo-device auditpipe"
.Pp
.Fd #include <security/audit/audit_ioctl.h>
.Sh DESCRIPTION
While audit trail files
generated with
.Xr audit 4
and maintained by
.Xr auditd 8
provide a reliable long-term store for audit log information, current log
files are owned by the audit daemon until terminated making them somewhat
unwieldy for live monitoring applications such as host-based intrusion
detection.
For example, the log may be cycled and new records written to a new file
without notice to applications that may be accessing the file.
.Pp
The audit facility provides an audit pipe facility for applications requiring
direct access to live BSM audit data for the purposes of real-time
monitoring.
Audit pipes are available via a clonable special device,
.Pa /dev/auditpipe ,
subject to the permissions on the device node, and provide a
.Qq tee
of the audit event stream.
As the device is clonable, more than one instance of the device may be opened
at a time; each device instance will provide independent access to all
records.
.Pp
The audit pipe device provides discrete BSM audit records; if the read buffer
passed by the application is too small to hold the next record in the
sequence, it will be dropped.
Unlike audit data written to the audit trail, the reliability of record
delivery is not guaranteed.
In particular, when an audit pipe queue fills, records will be dropped.
Audit pipe devices are blocking by default, but support non-blocking I/O,
asynchronous I/O using
.Dv SIGIO ,
and polled operation via
.Xr select 2
and
.Xr poll 2 .
.Pp
Applications may choose to track the global audit trail, or configure local
preselection parameters independent of the global audit trail parameters.
.Ss Audit Pipe Queue Ioctls
The following ioctls retrieve and set various audit pipe record queue
properties:
.Bl -tag -width ".Dv AUDITPIPE_GET_MAXAUDITDATA"
.It Dv AUDITPIPE_GET_QLEN
Query the current number of records available for reading on the pipe.
.It Dv AUDITPIPE_GET_QLIMIT
Retrieve the current maximum number of records that may be queued for reading
on the pipe.
.It Dv AUDITPIPE_SET_QLIMIT
Set the current maximum number of records that may be queued for reading on
the pipe.
The new limit must fall between the queue limit minimum and queue limit
maximum queryable using the following two ioctls.
.It Dv AUDITPIPE_GET_QLIMIT_MIN
Query the lowest possible maximum number of records that may be queued for
reading on the pipe.
.It Dv AUDITPIPE_GET_QLIMIT_MAX
Query the highest possible maximum number of records that may be queued for
reading on the pipe.
.It Dv AUDITPIPE_FLUSH
Flush all outstanding records on the audit pipe; useful after setting initial
preselection properties to delete records queued during the configuration
process which may not match the interests of the user process.
.It Dv AUDITPIPE_GET_MAXAUDITDATA
Query the maximum size of an audit record, which is a useful minimum size for
a user space buffer intended to hold audit records read from the audit pipe.
.El
.Ss Audit Pipe Preselection Mode Ioctls
By default, the audit pipe facility configures pipes to present records
matched by the system-wide audit trail, configured by
.Xr auditd 8 .
However, the preselection mechanism for audit pipes can be configured using
alternative criteria, including pipe-local flags and naflags settings, as
well as auid-specific selection masks.
This allows applications to track events not captured in the global audit
trail, as well as limit records presented to those of specific interest to
the application.
.Pp
The following ioctls configure the preselection mode on an audit pipe:
.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_MODE"
.It Dv AUDITPIPE_GET_PRESELECT_MODE
Return the current preselect mode on the audit pipe.
The ioctl argument should be of type
.Vt int .
.It Dv AUDITPIPE_SET_PRESELECT_MODE
Set the current preselection mode on the audit pipe.
The ioctl argument should be of type
.Vt int .
.El
.Pp
Possible preselection mode values are:
.Bl -tag -width ".Dv AUDITPIPE_PRESELECT_MODE_TRAIL"
.It Dv AUDITPIPE_PRESELECT_MODE_TRAIL
Use the global audit trail preselection parameters to select records for the
audit pipe.
.It Dv AUDITPIPE_PRESELECT_MODE_LOCAL
Use local audit pipe preselection; this model is similar to the global audit
trail configuration model, consisting of global flags and naflags parameters,
as well as a set of per-auid masks.
These parameters are configured using further ioctls.
.El
.Pp
After changing the audit pipe preselection mode, records selected under
earlier preselection configuration may still be in the audit pipe queue.
The application may flush the current record queue after changing the
configuration to remove possibly undesired records.
.Ss Audit Pipe Local Preselection Mode Ioctls
The following ioctls configure the preselection parameters used when an audit
pipe is configured for the
.Dv AUDITPIPE_PRESELECT_MODE_LOCAL
preselection mode.
.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_NAFLAGS"
.It Dv AUDITPIPE_GET_PRESELECT_FLAGS
Retrieve the current default preselection flags for attributable events on
the pipe.
These flags correspond to the
.Va flags
field in
.Xr audit_control 5 .
The ioctl argument should be of type
.Vt au_mask_t .
.It Dv AUDITPIPE_SET_PRESELECT_FLAGS
Set the current default preselection flags for attributable events on the
pipe.
These flags correspond to the
.Va flags
field in
.Xr audit_control 5 .
The ioctl argument should be of type
.Vt au_mask_t .
.It Dv AUDITPIPE_GET_PRESELECT_NAFLAGS
Retrieve the current default preselection flags for non-attributable events
on the pipe.
These flags correspond to the
.Va naflags
field in
.Xr audit_control 5 .
The ioctl argument should be of type
.Vt au_mask_t .
.It Dv AUDITPIPE_SET_PRESELECT_NAFLAGS
Set the current default preselection flags for non-attributable events on the
pipe.
These flags correspond to the
.Va naflags
field in
.Xr audit_control 5 .
The ioctl argument should be of type
.Vt au_mask_t .
.It Dv AUDITPIPE_GET_PRESELECT_AUID
Query the current preselection masks for a specific auid on the pipe.
The ioctl argument should be of type
.Vt "struct auditpipe_ioctl_preselect" .
The auid to query is specified via the
.Va ap_auid
field of type
.Vt au_id_t ;
the mask will be returned via
.Va ap_mask
of type
.Vt au_mask_t .
.It Dv AUDITPIPE_SET_PRESELECT_AUID
Set the current preselection masks for a specific auid on the pipe.
Arguments are identical to
.Dv AUDITPIPE_GET_PRESELECT_AUID ,
except that the caller should properly initialize the
.Va ap_mask
field to hold the desired preselection mask.
.It Dv AUDITPIPE_DELETE_PRESELECT_AUID
Delete the current preselection mask for a specific auid on the pipe.
Once called, events associated with the specified auid will use the default
flags mask.
The ioctl argument should be of type
.Vt au_id_t .
.It Dv AUDITPIPE_FLUSH_PRESELECT_AUID
Delete all auid specific preselection specifications.
.El
.Sh EXAMPLES
The
.Xr praudit 1
utility
may be directly executed on
.Pa /dev/auditpipe
to review the default audit trail.
.Sh SEE ALSO
.Xr poll 2 ,
.Xr select 2 ,
.Xr audit 4 ,
.Xr audit_control 5 ,
.Xr audit 8 ,
.Xr auditd 8
.Sh HISTORY
The OpenBSM implementation was created by McAfee Research, the security
division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
It was subsequently adopted by the TrustedBSD Project as the foundation for
the OpenBSM distribution.
.Pp
Support for kernel audit first appeared in Mac OS X 10.3 and
.Fx 6.2 .
.Sh AUTHORS
The audit pipe facility was designed and implemented by
.An Robert Watson Aq rwatson@FreeBSD.org .
.Pp
The Basic Security Module (BSM) interface to audit records and audit event
stream format were defined by Sun Microsystems.
.Sh BUGS
See the
.Xr audit 4
manual page for information on audit-related bugs and limitations.
.Pp
The configurable preselection mechanism mirrors the selection model present
for the global audit trail.
It might be desirable to provided a more flexible selection model.
.Pp
The per-pipe audit event queue is fifo, with drops occurring if either the
user thread provides in sufficient for the record on the queue head, or on
enqueue if there is insufficient room.
It might be desirable to allow applications to select which records are
dropped, possibly in the style of preselection.
Commit	Line	Data
b0d623f7 A	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	.\"
6d2010ae	27	.Dd Oct 18, 2010
b0d623f7 A	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
6d2010ae	159	.Vt au_mask_t .
b0d623f7 A	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
6d2010ae	168	.Vt au_mask_t .
b0d623f7 A	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
6d2010ae	177	.Vt au_mask_t .
b0d623f7 A	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
6d2010ae	186	.Vt au_mask_t .
b0d623f7 A	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.
6d2010ae A	255	It might be desirable to allow applications to select which records are
6d2010ae A	256	dropped, possibly in the style of preselection.