share/man/man4/audit.4

   1 .\" Copyright (c) 2006 Robert N. M. Watson
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 6, 2006
  28 .Os
  29 .Dt AUDIT 4
  30 .Sh NAME
  31 .Nm audit
  32 .Nd Security Event Audit
  33 .Sh SYNOPSIS
  34 .Cd "options AUDIT"
  35 .Sh DESCRIPTION
  36 Security Event Audit is a facility to provide fine-grained, configurable
  37 logging of security-relevant events, and is intended to meet the requirements
  38 of the Common Criteria (CC) Common Access Protection Profile (CAPP)
  39 evaluation.
  40 The
  41 .Fx
  42 audit facility implements the de facto industry standard BSM API, file
  43 formats, and command line interface, first found in the Solaris operating
  44 system.
  45 Information on the user space implementation can be found in
  46 .Xr libbsm 3 .
  47 .Pp
  48 Audit support is enabled at boot, if present in the kernel, using an
  49 .Xr rc.conf 5
  50 flag.
  51 The audit daemon,
  52 .Xr auditd 8 ,
  53 is responsible for configuring the kernel to perform audit, pushing
  54 configuration data from the various audit configuration files into the
  55 kernel.
  56 .Ss Audit Special Device
  57 The kernel audit facility provides a special device,
  58 .Pa /dev/audit ,
  59 which is used by
  60 .Xr auditd 8
  61 to monitor for audit events, such as requests to cycle the log, low disk
  62 space conditions, and requests to terminate auditing.
  63 This device is not intended for use by applications.
  64 .Ss Audit Pipe Special Devices
  65 While audit trail files maintained by
  66 .Xr auditd 8
  67 provide a reliable long-term store for audit log information, current log
  68 files are owned by the audit daemon until terminated making them somewhat
  69 unwieldy for live montoring applications such as host-based intrusion
  70 detection.
  71 For example, the log may be cycled and new records written to a new file
  72 without notice to applications that may be accessing the file.
  73 .Pp
  74 The audit facility provides an audit pipe facility for applications requiring
  75 direct access to live BSM audit data for the purposes of real-time
  76 monitoring.
  77 Audit pipes are available via a clonable special device,
  78 .Pa /dev/auditpipe ,
  79 subject to the permissions on the device node, and provide a
  80 .Qq tee
  81 of the audit event stream.
  82 As the device is clonable, more than one instance of the device may be opened
  83 at a time; each device instance will provide access to all records.
  84 .Pp
  85 The audit pipe device provides discreet BSM audit records; if the read buffer
  86 passed by the application is too small to hold the next record in the
  87 sequence, it will be dropped.
  88 Unlike audit data written to the audit trail, the reliability of record
  89 delivery is not guaranteed.
  90 In particular, when an audit pipe queue fills, records will be dropped.
  91 Audit pipe devices are blocking by default, but support non-blocking I/O,
  92 asynchronous I/O using SIGIO, and support for polled operation via
  93 .Xr select 2
  94 and
  95 .Xr poll 2 .
  96 .Sh SEE ALSO
  97 .Xr auditreduce 1 ,
  98 .Xr praudit 1 ,
  99 .Xr audit 2 ,
 100 .Xr auditctl 2 ,
 101 .Xr auditon 2 ,
 102 .Xr getaudit 2 ,
 103 .Xr getauid 2 ,
 104 .Xr poll 2 ,
 105 .Xr select 2 ,
 106 .Xr setaudit 2 ,
 107 .Xr setauid 2 ,
 108 .Xr libbsm 3 ,
 109 .Xr audit.log 5 ,
 110 .Xr audit_class 5 ,
 111 .Xr audit_control 5 ,
 112 .Xr audit_event 5 ,
 113 .Xr audit_user 5 ,
 114 .Xr audit_warn 5 ,
 115 .Xr rc.conf 5 ,
 116 .Xr audit 8 ,
 117 .Xr auditd 8
 118 .Sh AUTHORS
 119 This software was created by McAfee Research, the security research division
 120 of McAfee, Inc., under contract to Apple Computer Inc.
 121 Additional authors include Wayne Salamon, Robert Watson, and SPARTA Inc.
 122 .Pp
 123 The Basic Security Module (BSM) interface to audit records and audit event
 124 stream format were defined by Sun Microsystems.
 125 .Pp
 126 This manual page was written by
 127 .An Robert Watson Aq rwatson@FreeBSD.org .
 128 .Sh HISTORY
 129 The OpenBSM implementation was created by McAfee Research, the security
 130 division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
 131 It was subsequently adopted by the TrustedBSD Project as the foundation for
 132 the OpenBSM distribution.
 133 .Pp
 134 Support for kernel audit first appeared in
 135 .Fx 6.1 .
 136 .Sh BUGS
 137 The audit facility in
 138 .Fx
 139 is considered experimental, and production deployment should occur only after
 140 careful consideration of the risks of deploying experimental software.
 141 .Pp
 142 The
 143 .Fx
 144 kernel does not fully validate that audit records submitted by user
 145 applications are syntactically valid BSM; as submission of records is limited
 146 to privileged processes, this is not a critical bug.
 147 .Pp
 148 Instrumentation of auditable events in the kernel is not complete, as some
 149 system calls do not generate audit records, or generate audit records with
 150 incomplete argument information.
 151 .Pp
 152 Mandatory Access Control (MAC) labels, as provided by the
 153 .Xr mac 4
 154 facility, are not audited as part of records involving MAC decisions.