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 .Fn audit:event:aue_*:commit "char *eventname" "struct audit_record *ar"
  44 .Fn audit:event:aue_*:bsm "char *eventname" "struct audit_record *ar" "const void *" "size_t"
  45 .Pp
  46 To compile this module into the kernel, place the following in your kernel
  47 configuration file:
  48 .Bd -literal -offset indent
  49 .Cd "options DTAUDIT"
  50 .Ed
  51 .Pp
  52 Alternatively, to load the module at boot time, place the following line in
  53 .Xr loader.conf 5 :
  54 .Bd -literal -offset indent
  55 dtaudit_load="YES"
  56 .Ed
  57 .Sh DESCRIPTION
  58 The DTrace
  59 .Nm dtaudit
  60 provider allows users to trace events in the kernel security auditing
  61 subsystem,
  62 .Xr audit 4 .
  63 .Xr audit 4
  64 provides detailed logging of a configurable set of security-relevant system
  65 calls, including key arguments (such as file paths) and return values that are
  66 copied race-free as the system call proceeds.
  67 The
  68 .Nm dtaudit
  69 provider allows DTrace scripts to selectively enable in-kernel audit-record
  70 capture for system calls, and then access those records in either the
  71 in-kernel format or BSM format (\c
  72 .Xr audit.log 5 )
  73 when the system call completes.
  74 While the in-kernel audit record data structure is subject to change as the
  75 kernel changes over time, it is a much more friendly interface for use in D
  76 scripts than either those available via the DTrace system-call provider or the
  77 BSM trail itself.
  78 .Ss Configuration
  79 The
  80 .Nm dtaudit
  81 provider relies on
  82 .Xr audit 4
  83 being compiled into the kernel.
  84 .Nm dtaudit
  85 probes become available only once there is an event-to-name mapping installed
  86 in the kernel, normally done by
  87 .Xr auditd 8
  88 during the boot process, if audit is enabled in
  89 .Xr rc.conf 5 :
  90 .Bd -literal -offset indent
  91 auditd_enable="YES"
  92 .Ed
  93 .Pp
  94 If
  95 .Nm dtaudit
  96 probes are required earlier in boot -- for example, in single-user mode -- or
  97 without enabling
  98 .Xr audit 4 ,
  99 they can be preloaded in the boot loader by adding this line to
 100 .Xr loader.conf 5 .
 101 .Bd -literal -offset indent
 102 audit_event_load="YES"
 103 .Ed
 104 .Ss Probes
 105 The
 106 .Fn audit:event:aue_*:commit
 107 probes fire synchronously during system-call return, giving access to two
 108 arguments: a
 109 .Vt char *
 110 audit event name, and
 111 the
 112 .Vt struct audit_record *
 113 in-kernel audit record.
 114 Because the probe fires in system-call return, the user thread has not yet
 115 regained control, and additional information from the thread and process
 116 remains available for capture by the script.
 117 .Pp
 118 The
 119 .Fn audit:event:aue_*:bsm
 120 probes fire asynchronously from system-call return, following BSM conversion
 121 and just prior to being written to disk, giving access to four arguments: a
 122 .Vt char *
 123 audit event name, the
 124 .Vt struct audit_record *
 125 in-kernel audit record, a
 126 .Vt const void *
 127 pointer to the converted BSM record, and a
 128 .Vt size_t
 129 for the length of the BSM record.
 130 .Sh IMPLEMENTATION NOTES
 131 When a set of
 132 .Nm dtaudit
 133 probes are registered, corresponding in-kernel audit records will be captured
 134 and their probes will fire regardless of whether the
 135 .Xr audit 4
 136 subsystem itself would have captured the record for the purposes of writing it
 137 to the audit trail, or for delivery to a
 138 .Xr auditpipe 4 .
 139 In-kernel audit records allocated only because of enabled
 140 .Xr dtaudit 4
 141 probes will not be unnecessarily written to the audit trail or enabled pipes.
 142 .Sh SEE ALSO
 143 .Xr dtrace 1 ,
 144 .Xr audit 4 ,
 145 .Xr audit.log 5 ,
 146 .Xr loader.conf 5 ,
 147 .Xr rc.conf 5 ,
 148 .Xr auditd 8
 149 .Sh HISTORY
 150 The
 151 .Nm dtaudit
 152 provider first appeared in
 153 .Fx 12.0 .
 154 .Sh AUTHORS
 155 This software and this manual page were developed by BAE Systems, the
 156 University of Cambridge Computer Laboratory, and Memorial University under
 157 DARPA/AFRL contract
 158 .Pq FA8650-15-C-7558
 159 .Pq Do CADETS Dc ,
 160 as part of the DARPA Transparent Computing (TC) research program.
 161 The
 162 .Nm dtaudit
 163 provider and this manual page were written by
 164 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
 165 .Sh BUGS
 166 Because
 167 .Xr audit 4
 168 maintains its primary event-to-name mapping database in userspace, that
 169 database must be loaded into the kernel before
 170 .Nm dtaudit
 171 probes become available.
 172 .Pp
 173 .Nm dtaudit
 174 is only able to provide access to system-call audit events, not the full
 175 scope of userspace events, such as those relating to login, password change,
 176 and so on.