2 .\" SPDX-License-Identifier: BSD-2-Clause
4 .\" Copyright (c) 2019 Robert N. M. Watson
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.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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.
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
39 .Nd A DTrace provider for tracing
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"
47 To compile this module into the kernel, place the following in your kernel
50 .Bd -literal -offset indent
54 Alternatively, to load the module at boot time, place the following line in
56 .Bd -literal -offset indent
62 provider allows users to trace events in the kernel security auditing
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.
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
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
85 being compiled into the kernel.
87 probes become available only once there is an event-to-name mapping installed
88 in the kernel, normally done by
90 during the boot process, if audit is enabled in
92 .Bd -literal -offset indent
98 probes are required earlier in boot -- for example, in single-user mode -- or
101 they can be preloaded in the boot loader by adding this line to
103 .Bd -literal -offset indent
104 audit_event_load="YES"
108 .Fn audit:event:aue_*:commit
109 probes fire synchronously during system-call return, giving access to two
112 audit event name, and
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.
121 .Fn audit:event:aue_*:bsm
122 probes fire asynchronously from system-call return, following BSM conversion
123 and just prior to being written to disk, giving access to four arguments: a
125 audit event name, the
126 .Vt struct audit_record *
127 in-kernel audit record, a
129 pointer to the converted BSM record, and a
131 for the length of the BSM record.
132 .Sh IMPLEMENTATION NOTES
135 probes are registered, corresponding in-kernel audit records will be captured
136 and their probes will fire regardless of whether the
138 subsystem itself would have captured the record for the purposes of writing it
139 to the audit trail, or for delivery to a
141 In-kernel audit records allocated only because of enabled
143 probes will not be unnecessarily written to the audit trail or enabled pipes.
154 provider first appeared in
157 This software and this manual page were developed by BAE Systems, the
158 University of Cambridge Computer Laboratory, and Memorial University under
162 as part of the DARPA Transparent Computing (TC) research program.
165 provider and this manual page were written by
166 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
170 maintains its primary event-to-name mapping database in userspace, that
171 database must be loaded into the kernel before
173 probes become available.
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,