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
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"
46 To compile this module into the kernel, place the following in your kernel
48 .Bd -literal -offset indent
52 Alternatively, to load the module at boot time, place the following line in
54 .Bd -literal -offset indent
60 provider allows users to trace events in the kernel security auditing
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.
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
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
83 being compiled into the kernel.
85 probes become available only once there is an event-to-name mapping installed
86 in the kernel, normally done by
88 during the boot process, if audit is enabled in
90 .Bd -literal -offset indent
96 probes are required earlier in boot -- for example, in single-user mode -- or
99 they can be preloaded in the boot loader by adding this line to
101 .Bd -literal -offset indent
102 audit_event_load="YES"
106 .Fn audit:event:aue_*:commit
107 probes fire synchronously during system-call return, giving access to two
110 audit event name, and
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.
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
123 audit event name, the
124 .Vt struct audit_record *
125 in-kernel audit record, a
127 pointer to the converted BSM record, and a
129 for the length of the BSM record.
130 .Sh IMPLEMENTATION NOTES
133 probes are registered, corresponding in-kernel audit records will be captured
134 and their probes will fire regardless of whether the
136 subsystem itself would have captured the record for the purposes of writing it
137 to the audit trail, or for delivery to a
139 In-kernel audit records allocated only because of enabled
141 probes will not be unnecessarily written to the audit trail or enabled pipes.
152 provider first appeared in
155 This software and this manual page were developed by BAE Systems, the
156 University of Cambridge Computer Laboratory, and Memorial University under
160 as part of the DARPA Transparent Computing (TC) research program.
163 provider and this manual page were written by
164 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
168 maintains its primary event-to-name mapping database in userspace, that
169 database must be loaded into the kernel before
171 probes become available.
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,