1.\" Copyright (c) 2004 Apple Inc.
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.\" 3.  Neither the name of Apple Inc. ("Apple") nor the names of
13.\"     its contributors may be used to endorse or promote products derived
14.\"     from this software without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
20.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
24.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
25.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26.\" POSSIBILITY OF SUCH DAMAGE.
27.\"
28.Dd January 24, 2004
29.Dt AUDITREDUCE 1
30.Os
31.Sh NAME
32.Nm auditreduce
33.Nd "select records from audit trail files"
34.Sh SYNOPSIS
35.Nm
36.Op Fl A
37.Op Fl a Ar YYYYMMDD Ns Op Ar HH Ns Op Ar MM Ns Op Ar SS
38.Op Fl b Ar YYYYMMDD Ns Op Ar HH Ns Op Ar MM Ns Op Ar SS
39.Op Fl c Ar flags
40.Op Fl d Ar YYYYMMDD
41.Op Fl e Ar euid
42.Op Fl f Ar egid
43.Op Fl g Ar rgid
44.Op Fl j Ar id
45.Op Fl m Ar event
46.Op Fl o Ar object Ns = Ns Ar value
47.Op Fl r Ar ruid
48.Op Fl u Ar auid
49.Op Fl v
50.Op Ar
51.Sh DESCRIPTION
52The
53.Nm
54utility selects records from the audit trail files based on the specified
55criteria.
56Matching audit records are printed to the standard output in
57their raw binary form.
58If no
59.Ar file
60argument is specified, the standard input is used
61by default.
62Use the
63.Xr praudit 1
64utility to print the selected audit records in human-readable form.
65.Pp
66The options are as follows:
67.Bl -tag -width indent
68.It Fl A
69Select all records.
70.It Fl a Ar YYYYMMDD Ns Op Ar HH Ns Op Ar MM Ns Op Ar SS
71Select records that occurred after or on the given datetime.
72.It Fl b Ar YYYYMMDD Ns Op Ar HH Ns Op Ar MM Ns Op Ar SS
73Select records that occurred before the given datetime.
74.It Fl c Ar flags
75Select records matching the given audit classes specified as a comma
76separated list of audit flags.
77See
78.Xr audit_control 5
79for a description of audit flags.
80.It Fl d Ar YYYYMMDD
81Select records that occurred on a given date.
82This option cannot be used with
83.Fl a
84or
85.Fl b .
86.It Fl e Ar euid
87Select records with the given effective user ID or name.
88.It Fl f Ar egid
89Select records with the given effective group ID or name.
90.It Fl g Ar rgid
91Select records with the given real group ID or name.
92.It Fl j Ar id
93Select records having a subject token with matching ID, where ID is a process ID.
94.It Fl m Ar event
95Select records with the given event name or number. This option can
96be used more then once to select records of multiple event types.
97See
98.Xr audit_event 5
99for a description of audit event names and numbers.
100.It Fl o Ar object Ns = Ns Ar value
101.Bl -tag -width ".Cm msgqid"
102.It Cm file
103Select records containing path tokens, where the pathname matches
104one of the comma delimited extended regular expression contained in
105given specification.
106Regular expressions which are prefixed with a tilde
107.Pq Ql ~
108are excluded
109from the search results.
110These extended regular expressions are processed from left to right,
111and a path will either be selected or deslected based on the first match.
112.Pp
113Since commas are used to delimit the regular expressions, a backslash
114.Pq Ql \e
115character should be used to escape the comma if it is a part of the search
116pattern.
117.It Cm msgqid
118Select records containing the given message queue ID.
119.It Cm pid
120Select records containing the given process ID.
121.It Cm semid
122Select records containing the given semaphore ID.
123.It Cm shmid
124Select records containing the given shared memory ID.
125.El
126.It Fl r Ar ruid
127Select records with the given real user ID or name.
128.It Fl u Ar auid
129Select records with the given audit ID.
130.It Fl v
131Invert sense of matching, to select records that do not match.
132.El
133.Sh EXAMPLES
134To select all records associated with effective user ID root from the audit
135log
136.Pa /var/audit/20031016184719.20031017122634 :
137.Bd -literal -offset indent
138auditreduce -e root \e
139    /var/audit/20031016184719.20031017122634
140.Ed
141.Pp
142To select all
143.Xr setlogin 2
144events from that log:
145.Bd -literal -offset indent
146auditreduce -m AUE_SETLOGIN \e
147    /var/audit/20031016184719.20031017122634
148.Ed
149.Pp
150Output from the above command lines will typically be piped to a new trail
151file, or via standard output to the
152.Xr praudit 1
153command.
154.Pp
155Select all records containing a path token where the pathname contains
156.Pa /etc/master.passwd :
157.Bd -literal -offset indent
158auditreduce -o file="/etc/master.passwd" \e
159    /var/audit/20031016184719.20031017122634
160.Ed
161.Pp
162Select all records containing path tokens, where the pathname is a TTY
163device:
164.Bd -literal -offset indent
165auditreduce -o file="/dev/tty[a-zA-Z][0-9]+" \e
166    /var/audit/20031016184719.20031017122634
167.Ed
168.Pp
169Select all records containing path tokens, where the pathname is a TTY
170except for
171.Pa /dev/ttyp2 :
172.Bd -literal -offset indent
173auditreduce -o file="~/dev/ttyp2,/dev/tty[a-zA-Z][0-9]+" \e
174    /var/audit/20031016184719.20031017122634
175.Ed
176.Sh SEE ALSO
177.Xr praudit 1 ,
178.Xr audit_control 5 ,
179.Xr audit_event 5
180.Sh HISTORY
181The OpenBSM implementation was created by McAfee Research, the security
182division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
183It was subsequently adopted by the TrustedBSD Project as the foundation for
184the OpenBSM distribution.
185.Sh AUTHORS
186.An -nosplit
187This software was created by McAfee Research, the security research division
188of McAfee, Inc., under contract to Apple Computer Inc.
189Additional authors include
190.An Wayne Salamon ,
191.An Robert Watson ,
192and SPARTA Inc.
193.Pp
194The Basic Security Module (BSM) interface to audit records and audit event
195stream format were defined by Sun Microsystems.
196