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);
To compile this module into the kernel, place the following in your kernel configuration file:
options DTAUDIT
Alternatively, to load the module at boot time, place the following line in loader.conf(5):
dtaudit_load="YES"
DESCRIPTION
The DTracedtaudit
provider allows users to trace events
in the kernel security auditing subsystem,
audit(4). audit(4) 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. The
dtaudit
provider allows DTrace scripts to selectively
enable in-kernel audit-record capture for system calls, and then access those
records in either the in-kernel format or BSM format
(audit.log(5)) when the system call completes. While the in-kernel audit
record data structure is subject to change as the kernel changes over time, 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.
Configuration
The dtaudit
provider relies on
audit(4) being compiled into the kernel.
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"
If dtaudit
probes are required earlier in
boot -- for example, in single-user mode -- or without enabling
audit(4), they can be preloaded in the boot loader by adding this
line to
loader.conf(5).
audit_event_load="YES"
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. Because
the probe fires in system-call return, the user thread has not yet regained
control, and additional information from the thread and process remains
available for capture by the script.
The
audit:event:aue_*:bsm
()
probes fire asynchronously 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.
IMPLEMENTATION NOTES
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 a
auditpipe(4). In-kernel audit records allocated only because
of enabled dtaudit(4) probes will not be unnecessarily written to the
audit trail or enabled pipes.
SEE ALSO
dtrace(1), audit(4), audit.log(5), loader.conf(5), rc.conf(5), auditd(8)
HISTORY
The dtaudit
provider first appeared in
FreeBSD 12.0.
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.
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.