AUDITPIPE(4) | Device Drivers Manual | AUDITPIPE(4) |
auditpipe
—
pseudo-device for live audit event tracking
pseudo-device auditpipe
#include
<security/audit/audit_ioctl.h>
While audit trail files generated with audit(4) and maintained by 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.
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, /dev/auditpipe, subject to the permissions on the device node, and provide a "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.
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 SIGIO
, and polled operation via
select(2) and
poll(2).
Applications may choose to track the global audit trail, or configure local preselection parameters independent of the global audit trail parameters.
The following ioctls retrieve and set various audit pipe record queue properties:
AUDITPIPE_GET_QLEN
AUDITPIPE_GET_QLIMIT
AUDITPIPE_SET_QLIMIT
AUDITPIPE_GET_QLIMIT_MIN
AUDITPIPE_GET_QLIMIT_MAX
AUDITPIPE_FLUSH
AUDITPIPE_GET_MAXAUDITDATA
By default, the audit pipe facility configures pipes to present records matched by the system-wide audit trail, configured by 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.
The following ioctls configure the preselection mode on an audit pipe:
AUDITPIPE_GET_PRESELECT_MODE
AUDITPIPE_SET_PRESELECT_MODE
Possible preselection mode values are:
AUDITPIPE_PRESELECT_MODE_TRAIL
AUDITPIPE_PRESELECT_MODE_LOCAL
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.
The following ioctls configure the preselection parameters used
when an audit pipe is configured for the
AUDITPIPE_PRESELECT_MODE_LOCAL
preselection
mode.
AUDITPIPE_GET_PRESELECT_FLAGS
AUDITPIPE_SET_PRESELECT_FLAGS
AUDITPIPE_GET_PRESELECT_NAFLAGS
AUDITPIPE_SET_PRESELECT_NAFLAGS
AUDITPIPE_GET_PRESELECT_AUID
AUDITPIPE_SET_PRESELECT_AUID
AUDITPIPE_GET_PRESELECT_AUID
, except that the
caller should properly initialize the ap_mask field
to hold the desired preselection mask.AUDITPIPE_DELETE_PRESELECT_AUID
AUDITPIPE_FLUSH_PRESELECT_AUID
The praudit(1) utility may be directly executed on /dev/auditpipe to review the default audit trail.
poll(2), select(2), audit(4), audit_control(5), audit(8), auditd(8)
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.
Support for kernel audit first appeared in Mac OS X 10.3 and FreeBSD 6.2.
The audit pipe facility was designed and implemented by Robert Watson ⟨rwatson@FreeBSD.org⟩.
The Basic Security Module (BSM) interface to audit records and audit event stream format were defined by Sun Microsystems.
See the audit(4) manual page for information on audit-related bugs and limitations.
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.
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.
October 18, 2010 | macOS 14.6 |