AUDITPIPE(4)

✨ AUDITPIPE(4) ✨ — from the Kernel Interfaces Manual, and yes it's giving very much kernel-girlie 💅

🌸 NAME 🌸

auditpipe — a pseudo-device for live audit event tracking. no cap, that's literally it 🫶

---

🦋 SYNOPSIS 🦋

options AUDIT

---

💜 DESCRIPTION 💜

Okay so, context first bestie. Audit trail files get generated by audit(4) and maintained by auditd(8), and they're genuinely a great long-term store for audit log info. Slay. But here's the thing — the current log files are owned by the audit daemon until it terminates, which makes them kinda unwieldy for live monitoring apps. Like, host-based intrusion detection? Those girlies need real-time access and the log file situation is just not it. 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. Rude honestly. 😭

So the audit facility says: don't worry bestie, I got you. It provides an audit pipe facility for applications that need direct access to live BSM audit data for real-time monitoring purposes. Audit pipes are available via a clonable special device, /dev/auditpipe, subject to the permissions on the device node, and they provide a "tee" of the audit event stream. And because the device is clonable, more than one instance of the device may be opened at a time — each device instance gives you independent access to all records. Independent! As in, your business is your business. 👑

The audit pipe device provides discrete BSM audit records. And here's the tea: 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. Specifically, when an audit pipe queue fills, records will be dropped. Periodt. 💀

Audit pipe devices are blocking by default, but they support non-blocking I/O, asynchronous I/O using SIGIO, and polled operation via select(2) and poll(2). Versatile queen.

Applications may choose to track the global audit trail, or configure local preselection parameters independent of the global audit trail parameters. Your pipe, your rules. 💅

🎀 Audit Pipe Queue Ioctls 🎀

The following ioctls retrieve and set various audit pipe record queue properties:

• AUDITPIPE_GET_QLEN — Query the current number of records available for reading on the pipe.
• AUDITPIPE_GET_QLIMIT — Retrieve the current maximum number of records that may be queued for reading on the pipe.
• AUDITPIPE_SET_QLIMIT — Set the current maximum number of records that may be queued for reading on the pipe. Heads up: the new limit must fall between the queue limit minimum and queue limit maximum, which you can query using the following two ioctls.
• AUDITPIPE_GET_QLIMIT_MIN — Query the lowest possible maximum number of records that may be queued for reading on the pipe.
• AUDITPIPE_GET_QLIMIT_MAX — Query the highest possible maximum number of records that may be queued for reading on the pipe.
• AUDITPIPE_FLUSH — Flush all outstanding records on the audit pipe. Lowkey the moment for this is right after you set your initial preselection properties, because you want to delete records queued during the configuration process that may not match the interests of the user process. Cleansing ritual ✨
• 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. Size matters, bestie 🎀

🌈 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 auditd(8). But — plot twist — 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 lets applications track events not captured in the global audit trail, and limit records presented to just the ones that are of specific interest to the application. Curated feed energy. 🦋

The following ioctls configure the preselection mode on an audit pipe:

• AUDITPIPE_GET_PRESELECT_MODE — Return the current preselect mode on the audit pipe. The ioctl argument should be of type int.
• AUDITPIPE_SET_PRESELECT_MODE — Set the current preselection mode on the audit pipe. The ioctl argument should be of type int.

Possible preselection mode values are:

• AUDITPIPE_PRESELECT_MODE_TRAIL — Use the global audit trail preselection parameters to select records for the audit pipe.
• 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.

Heads up bestie: 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. Old vibes linger, you gotta clear them out 💅

💖 Audit Pipe Local Preselection Mode Ioctls 💖

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 — Retrieve the current default preselection flags for attributable events on the pipe. These flags correspond to the flags field in audit_control(5). The ioctl argument should be of type au_mask_t.
• AUDITPIPE_SET_PRESELECT_FLAGS — Set the current default preselection flags for attributable events on the pipe. These flags correspond to the flags field in audit_control(5). The ioctl argument should be of type au_mask_t.
• AUDITPIPE_GET_PRESELECT_NAFLAGS — Retrieve the current default preselection flags for non-attributable events on the pipe. These flags correspond to the naflags field in audit_control(5). The ioctl argument should be of type au_mask_t.
• AUDITPIPE_SET_PRESELECT_NAFLAGS — Set the current default preselection flags for non-attributable events on the pipe. These flags correspond to the naflags field in audit_control(5). The ioctl argument should be of type au_mask_t.
• AUDITPIPE_GET_PRESELECT_AUID — Query the current preselection masks for a specific auid on the pipe. The ioctl argument should be of type struct auditpipe_ioctl_preselect. The auid to query is specified via the ap_auid field of type au_id_t; the mask will be returned via ap_mask of type au_mask_t.
• AUDITPIPE_SET_PRESELECT_AUID — Set the current preselection masks for a specific auid on the pipe. Arguments are identical to 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 — 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 au_id_t.
• AUDITPIPE_FLUSH_PRESELECT_AUID — Delete all auid specific preselection specifications. Full reset, we love to see it ✨

---

🍓 EXAMPLES 🍓

The praudit(1) utility may be directly executed on /dev/auditpipe to review the default audit trail. Cute, right? 🎀

---

👑 SEE ALSO 👑

poll(2), select(2), audit(4), dtaudit(4), audit_control(5), audit(8), auditd(8)

---

🧚 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. Glow-up arc fr fr 💜

Support for kernel audit first appeared in FreeBSD 6.2.

---

💜 AUTHORS 💜

The audit pipe facility was designed and implemented by Robert Watson <rwatson@FreeBSD.org>. Iconic behavior. 🫶

The Basic Security Module (BSM) interface to audit records and audit event stream format were defined by Sun Microsystems.

---

💀 BUGS 💀

See the audit(4) manual page for information on audit-related bugs and limitations. Not me redirecting you, but like, genuinely, go read it. 🙈

The configurable preselection mechanism mirrors the selection model present for the global audit trail. It might be desirable to provide a more flexible selection model. (Lowkey a wishlist item, not a promise.)

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 support partial reads of records, which would be more compatible with buffered I/O as implemented in system libraries, and to allow applications to select which records are dropped, possibly in the style of preselection.

---

🌸 okay that's the whole page bestie, you ate 💅

This one's from the Debian crew, dated April 28, 2019 — AUDITPIPE(4), out. Stay audited, stay iconic. 🎀✨