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