share/man/man4/dtrace_audit.4

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2019 Robert N. M. Watson
   5 .\"
   6 .\" This software was developed by BAE Systems, the University of Cambridge
   7 .\" Computer Laboratory, and Memorial University under DARPA/AFRL contract
   8 .\" FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent Computing
   9 .\" (TC) research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd April 28, 2019
  35 .Dt DTRACE_AUDIT 4
  36 .Os
  37 .Sh NAME
  38 .Nm dtrace_audit
  39 .Nd A DTrace provider for tracing
  40 .Xr audit 4
  41 events
  42 .Sh SYNOPSIS
  43 .Pp
  44 .Fn audit:event:aue_*:commit "char *eventname" "struct audit_record *ar"
  45 .Fn audit:event:aue_*:bsm "char *eventname" "struct audit_record *ar" "const void *" "size_t"
  46 .Pp
  47 To compile this module into the kernel, place the following in your kernel
  48 configuration file:
  49 .Pp
  50 .Bd -literal -offset indent
  51 .Cd "options DTAUDIT"
  52 .Ed
  53 .Pp
  54 Alternatively, to load the module at boot time, place the following line in
  55 .Xr loader.conf 5 :
  56 .Bd -literal -offset indent
  57 dtaudit_load="YES"
  58 .Ed
  59 .Sh DESCRIPTION
  60 The DTrace
  61 .Nm dtaudit
  62 provider allows users to trace events in the kernel security auditing
  63 subsystem,
  64 .Xr audit 4 .
  65 .Xr audit 4
  66 provides detailed logging of a configurable set of security-relevant system
  67 calls, including key arguments (such as file paths) and return values that are
  68 copied race-free as the system call proceeds.
  69 The
  70 .Nm dtaudit
  71 provider allows DTrace scripts to selectively enable in-kernel audit-record
  72 capture for system calls, and then access those records in either the
  73 in-kernel format or BSM format (\c
  74 .Xr audit.log 5 )
  75 when the system call completes.
  76 While the in-kernel audit record data structure is subject to change as the
  77 kernel changes over time, it is a much more friendly interface for use in D
  78 scripts than either those available via the DTrace system-call provider or the
  79 BSM trail itself.
  80 .Ss Configuration
  81 The
  82 .Nm dtaudit
  83 provider relies on
  84 .Xr audit 4
  85 being compiled into the kernel.
  86 .Nm dtaudit
  87 probes become available only once there is an event-to-name mapping installed
  88 in the kernel, normally done by
  89 .Xr auditd 8
  90 during the boot process, if audit is enabled in
  91 .Xr rc.conf 5 :
  92 .Bd -literal -offset indent
  93 auditd_enable="YES"
  94 .Ed
  95 .Pp
  96 If
  97 .Nm dtaudit
  98 probes are required earlier in boot -- for example, in single-user mode -- or
  99 without enabling
 100 .Xr audit 4 ,
 101 they can be preloaded in the boot loader by adding this line to
 102 .Xr loader.conf 5 .
 103 .Bd -literal -offset indent
 104 audit_event_load="YES"
 105 .Ed
 106 .Ss Probes
 107 The
 108 .Fn audit:event:aue_*:commit
 109 probes fire synchronously during system-call return, giving access to two
 110 arguments: a
 111 .Vt char *
 112 audit event name, and
 113 the
 114 .Vt struct audit_record *
 115 in-kernel audit record.
 116 Because the probe fires in system-call return, the user thread has not yet
 117 regained control, and additional information from the thread and process
 118 remains available for capture by the script.
 119 .Pp
 120 The
 121 .Fn audit:event:aue_*:bsm
 122 probes fire asynchonously from system-call return, following BSM conversion
 123 and just prior to being written to disk, giving access to four arguments: a
 124 .Vt char *
 125 audit event name, the
 126 .Vt struct audit_record *
 127 in-kernel audit record, a
 128 .Vt const void *
 129 pointer to the converted BSM record, and a
 130 .Vt size_t
 131 for the length of the BSM record.
 132 .Sh IMPLEMENTATION NOTES
 133 When a set of
 134 .Nm dtaudit
 135 probes are registered, corresponding in-kernel audit records will be captured
 136 and their probes will fire regardless of whether the
 137 .Xr audit 4
 138 subsystem itself would have captured the record for the purposes of writing it
 139 to the audit trail, or for delivery to a
 140 .Xr auditpipe 4 .
 141 In-kernel audit records allocated only because of enabled
 142 .Xr dtaudit 4
 143 probes will not be unnecessarily written to the audit trail or enabled pipes.
 144 .Sh SEE ALSO
 145 .Xr dtrace 1 ,
 146 .Xr audit 4 ,
 147 .Xr audit.log 5 ,
 148 .Xr loader.conf 5 ,
 149 .Xr rc.conf 5 ,
 150 .Xr auditd 8
 151 .Sh HISTORY
 152 The
 153 .Nm dtaudit
 154 provider first appeared in
 155 .Fx 12.0 .
 156 .Sh AUTHORS
 157 This software and this manual page were developed by BAE Systems, the
 158 University of Cambridge Computer Laboratory, and Memorial University under
 159 DARPA/AFRL contract
 160 .Pq FA8650-15-C-7558
 161 .Pq Do CADETS Dc ,
 162 as part of the DARPA Transparent Computing (TC) research program.
 163 The
 164 .Nm dtaudit
 165 provider and this manual page were written by
 166 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
 167 .Sh BUGS
 168 Because
 169 .Xr audit 4
 170 maintains its primary event-to-name mapping database in userspace, that
 171 database must be loaded into the kernel before
 172 .Nm dtaudit
 173 probes become available.
 174 .Pp
 175 .Nm dtaudit
 176 is only able to provide access to system-call audit events, not the full
 177 scope of userspace events, such as those relating to login, password change,
 178 and so on.