DTRACE_AUDIT(4)

💖 DTRACE_AUDIT 💖 — the dtrace_audit page from the Kernel Interfaces Manual, bestie edition

okay so. sit down. hydrate. we're talking about dtrace_audit, and it's a DTrace provider for tracing audit(4) events, and honestly? it's giving observability excellence. 🦋

---

✨ NAME ✨

dtrace_audit — a DTrace provider for tracing audit(4) events 💅

---

🌸 SYNOPSIS 🌸

audit:event:aue_*:commit(char *eventname, struct audit_record *ar);

audit:event:aue_*:bsm(char *eventname, struct audit_record *ar,
    const void *, size_t);

so like, if you want this thing baked into your kernel 🍓, you drop this line into your kernel configuration file:

options DTAUDIT

orrrrr, alternate route, main character energy: load the module at boot time by putting this line in loader.conf(5):

dtaudit_load="YES"

both are valid, pick your fighter 💜

---

🎀 DESCRIPTION 🎀

The DTrace dtaudit provider lets users trace events in the kernel security auditing subsystem, audit(4). And audit(4)?? It provides detailed logging of a configurable set of security-relevant system calls — including key arguments (such as file paths) and return values that are copied race-free as the system call proceeds. no cap. 🔥

So what the dtaudit provider gives you is this: DTrace scripts can selectively enable in-kernel audit-record capture for system calls, and then access those records in either the in-kernel format or the BSM format (audit.log(5)) when the system call completes. Bestie, heads up on this next part though — the in-kernel audit record data structure is subject to change as the kernel changes over time. That's a real caveat, not a vibe. But it is a much more friendly interface for use in D scripts than either those available via the DTrace system-call provider or the BSM trail itself. so it's still iconic, just know what you're signing up for 🙈

⚙️ Configuration ⚙️

The dtaudit provider relies on audit(4) being compiled into the kernel. The dtaudit probes become available only once there is an event-to-name mapping installed in the kernel — normally done by auditd(8) during the boot process, if audit is enabled in rc.conf(5):

auditd_enable="YES"

But like, what if you need dtaudit probes earlier in boot? For example, in single-user mode? Or without enabling audit(4) at all? 👀 You can preload them in the boot loader by adding this line to loader.conf(5):

audit_event_load="YES"

slay. early access unlocked. 💅

🔍 Probes 🔍

The audit:event:aue_*:commit() probes fire synchronously during system-call return, giving access to two arguments: a char * audit event name, and the struct audit_record * in-kernel audit record. And because the probe fires in system-call return, the user thread has not yet regained control — so additional information from the thread and process remains available for capture by the script. obsessed with the timing on that fr fr 😭

The audit:event:aue_*:bsm() probes fire asynchonously from system-call return, following BSM conversion and just prior to being written to disk, giving access to four arguments: a char * audit event name, the struct audit_record * in-kernel audit record, a const void * pointer to the converted BSM record, and a size_t for the length of the BSM record. four whole arguments. she's thorough. 👑

---

🧚 IMPLEMENTATION NOTES 🧚

okay so this part matters. When a set of dtaudit probes are registered, corresponding in-kernel audit records will be captured and their probes will fire — regardless of whether the audit(4) subsystem itself would have captured the record for the purposes of writing it to the audit trail, or for delivery to an auditpipe(4). 💀

But here's the good news, the little mercy: in-kernel audit records allocated only because of enabled dtaudit(4) probes will not be unnecessarily written to the audit trail or enabled pipes. no extra clutter. we love a clean exit. ✨

---

🌈 SEE ALSO 🌈

• dtrace(1)
• audit(4)
• audit.log(5)
• loader.conf(5)
• rc.conf(5)
• auditd(8)

(the whole friend group 🫶)

---

⭐ HISTORY ⭐

The dtaudit provider first appeared in FreeBSD 12.0. a whole era. 💜

---

👑 AUTHORS 👑

This software and this manual page were developed by BAE Systems, the University of Cambridge Computer Laboratory, and Memorial University under DARPA/AFRL contract (FA8650-15-C-7558) (“CADETS”), as part of the DARPA Transparent Computing (TC) research program.

The dtaudit provider and this manual page were written by Robert Watson <rwatson@FreeBSD.org>. 🎀

---

💀 BUGS 💀

Because audit(4) maintains its primary event-to-name mapping database in userspace, that database must be loaded into the kernel before dtaudit probes become available. no database, no probes, that's the rule bestie 😭

dtaudit is only able to provide access to system-call audit events — not the full scope of userspace events, such as those relating to login, password change, and so on. so like, know its limits. it's not doing everything, it's doing this, and it's doing it well. 🙈

---

and that's the whole page!! 💖 this one came from the Debian build, dated April 28, 2019 — mwah, thanks for reading, ily, go trace something cute. periodt. 🌸🦋✨