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  DTrace  dtaudit  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 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.

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.

Debian                                           April 28, 2019                                  DTRACE_AUDIT(4)