AUDITREDUCE(8) Maintenance Commands and Procedures AUDITREDUCE(8)

NAME

auditreduce - merge and select audit records from audit trail files

SYNOPSIS

auditreduce [options] [audit-trail-file]...

DESCRIPTION

auditreduce allows you to select or merge records from audit trail
files. Audit files can be from one or more machines.


The merge function merges together audit records from one or more
input audit trail files into a single output file. The records in an
audit trail file are assumed to be sorted in chronological order
(oldest first) and this order is maintained by auditreduce in the
output file.


Unless instructed otherwise, auditreduce will merge the entire audit
trail, which consists of all the audit trail files in the directory
structure audit_root_dir/*/files. Unless specified with the -R or -S
option, audit_root_dir defaults to /etc/security/audit. By using the
file selection options it is possible to select some subset of these
files, or files from another directory, or files named explicitly on
the command line.


The select function allows audit records to be selected on the basis
of numerous criteria relating to the record's content (see
audit.log(5) for details of record content). A record must meet all
of the record-selection-option criteria to be selected.

Audit Trail Filename Format

Any audit trail file not named on the command line must conform to
the audit trail filename format. Files produced by the audit system
already have this format. Output file names produced by auditreduce
are in this format. It is:

start-time.end-time.suffix


where start-time is the 14-character timestamp of when the file was
opened, end-time is the 14-character timestamp of when the file was
closed, and suffix is the name of the machine which generated the
audit trail file, or some other meaningful suffix (for example, all,
if the file contains a combined group of records from many machines).
The end-time can be the literal string not_terminated, to indicate
that the file is still being written to by the audit system.
Timestamps are of the form yyyymmddhhmmss (year, month, day, hour,
minute, second). The timestamps are in Greenwich Mean Time (GMT).

OPTIONS

File Selection Options

The file selection options indicate which files are to be processed
and certain types of special treatment.

-A

All of the records from the input files will be selected
regardless of their timestamp. This option effectively disables
the -a, -b, and -d options. This is useful in preventing the loss
of records if the -D option is used to delete the input files
after they are processed. Note, however, that if a record is not
selected due to another option, then -A will not override that.


-C

Only process complete files. Files whose filename end-time
timestamp is not_terminated are not processed (such a file is
currently being written to by the audit system). This is useful
in preventing the loss of records if -D is used to delete the
input files after they are processed. It does not apply to files
specified on the command line.


-D suffix

Delete input files after they are read if the entire run is
successful. If auditreduce detects an error while reading a file,
then that file is not deleted. If -D is specified, -A, -C and -O
are also implied. suffix is given to the -O option. This helps
prevent the loss of audit records by ensuring that all of the
records are written, only complete files are processed, and the
records are written to a file before being deleted. Note that if
both -D and -O are specified in the command line, the order of
specification is significant. The suffix associated with the
latter specification is in effect.


-M machine

Allows selection of records from files with machine as the
filename suffix. If -M is not specified, all files are processed
regardless of suffix. -M can also be used to allow selection of
records from files that contain combined records from many
machines and have a common suffix (such as all).


-N

Select objects in new mode.This flag is off by default, thus
retaining backward compatibility. In the existing, old mode,
specifying the -e, -f, -g, -r, or -u flags would select not only
actions taken with those IDs, but also certain objects owned by
those IDs. When running in new mode, only actions are selected.
In order to select objects, the -o option must be used.


-O suffix

Direct output stream to a file in the current audit_root_dir with
the indicated suffix. suffix can alternatively contain a full
pathname, in which case the last component is taken as the
suffix, ahead of which the timestamps will be placed, ahead of
which the remainder of the pathname will be placed. If the -O
option is not specified, the output is sent to the standard
output. When auditreduce places timestamps in the filename, it
uses the times of the first and last records in the merge as the
start-time and end-time.


-Q

Quiet. Suppress notification about errors with input files.


-R pathname

Specify the pathname of an alternate audit root directory
audit_root_dir to be pathname. Therefore, rather than using
/etc/security/audit/*/files by default, pathname/*/files will be
examined instead.

Note -

The root file system of any non-global zones must not be
referenced with the -R option. Doing so might damage the global
zone's file system, might compromise the security of the global
zone, and might damage the non-global zone's file system. See
zones(7).


-S server

This option causes auditreduce to read audit trail files from a
specific location (server directory). server is normally
interpreted as the name of a subdirectory of the audit root,
therefore auditreduce will look in audit_root_dir/server/files
for the audit trail files. But if server contains any `/'
characters, it is the name of a specific directory not
necessarily contained in the audit root. In this case,
server/files will be consulted. This option allows archived files
to be manipulated easily, without requiring that they be
physically located in a directory structure like that of
/etc/security/audit.


-V

Verbose. Display the name of each file as it is opened, and how
many records total were written to the output stream.

Record Selection Options

The record selection options listed below are used to indicate which
records are written to the output file produced by auditreduce.


Multiple arguments of the same type are not permitted.

-a date-time

Select records that occurred at or after date-time. The date-time
argument is described under Option Arguments, below. date-time is
in local time. The -a and -b options can be used together to form
a range.


-b date-time

Select records that occurred before date-time.


-c audit-classes

Select records by audit class. Records with events that are
mapped to the audit classes specified by audit-classes are
selected. Audit class names are defined in audit_class(5). Using
the audit flags, one can select records based upon success and
failure criteria.


-d date-time

Select records that occurred on a specific day (a 24-hour period
beginning at 00:00:00 of the day specified and ending at
23:59:59). The day specified is in local time. The time portion
of the argument, if supplied, is ignored. Any records with
timestamps during that day are selected. If any hours, minutes,
or seconds are given in time, they are ignored. -d can not be
used with -a or -b.


-e effective-user

Select records with the specified effective-user.


-f effective-group

Select records with the specified effective-group.


-g real-group

Select records with the specified real-group.


-j subject-ID

Select records with the specified subject-ID where subject-ID is
a process ID.


-l label

Select records with the specified label (or label range), as
explained under "Option Arguments," below. This option is
available only if the system is configured with Trusted
Extensions.


-m event

Select records with the indicated event. The event is the literal
string or the event number.


-o object_type=objectID_value

Select records by object type. A match occurs when the record
contains the information describing the specified object_type and
the object ID equals the value specified by objectID_value. The
allowable object types and values are as follows:

file=pathname

Select records containing file system objects with the
specified pathname, where pathname is a comma separated list
of regular expressions. If a regular expression is preceded
by a tilde (~), files matching the expression are excluded
from the output. For example, the option
file=~/usr/openwin,/usr,/etc would select all files in /usr
or /etc except those in /usr/openwin. The order of the
regular expressions is important because auditreduce
processes them from left to right, and stops when a file is
known to be either selected or excluded. Thus the option
file= /usr, /etc, ~/usr/openwin would select all files in
/usr and all files in /etc. Files in /usr/openwin are not
excluded because the regular expression /usr is matched
first. Care should be given in surrounding the pathname with
quotes so as to prevent the shell from expanding any tildes.


filegroup=group

Select records containing file system objects with group as
the owning group.


fileowner=user

Select records containing file system objects with user as
the owning user.


msgqid=ID

Select records containing message queue objects with the
specified ID where ID is a message queue ID.


msgqgroup=group

Select records containing message queue objects with group as
the owning or creating group.


msgqowner=user

Select records containing message queue objects with user as
the owning or creating user.


pid=ID

Select records containing process objects with the specified
ID where ID is a process ID. Process are objects when they
are receivers of signals.


procgroup=group

Select records containing process objects with group as the
real or effective group.


procowner=user

Select records containing process objects with user as the
real or effective user.


semid=ID

Select records containing semaphore objects with the
specified ID where ID is a semaphore ID.


semgroup=group

Select records containing semaphore objects with group as the
owning or creating group.


semowner=user

Select records containing semaphore objects with user as the
owning or creating user.


shmid=ID

Select records containing shared memory objects with the
specified ID where ID is a shared memory ID.


shmgroup=group

Select records containing shared memory objects with group as
the owning or creating group.


shmowner=user

Select records containing shared memory objects with user as
the owning or creating user.


sock=port_number|machine

Select records containing socket objects with the specified
port_number or the specified machine where machine is a
machine name as defined in hosts(5).


fmri=service instance

Select records containing fault management resource
identifier (FMRI) objects with the specified service
instance. See smf(7).


-r real-user

Select records with the specified real-user.


-s session-id

Select audit records with the specified session-id.


-u audit-user

Select records with the specified audit-user.


-z zone-name

Select records from the specified zone name. The zone name
selection is case-sensitive.


When one or more filename arguments appear on the command line, only
the named files are processed. Files specified in this way need not
conform to the audit trail filename format. However, -M, -S, and -R
must not be used when processing named files. If the filename is
``-'' then the input is taken from the standard input.

Option Arguments

audit-trail-file

An audit trail file as defined in audit.log(5). An audit trail
file not named on the command line must conform to the audit
trail file name format. Audit trail files produced as output of
auditreduce are in this format as well. The format is:

start-time . end-time . suffix

start-time is the 14 character time stamp denoting when the file
was opened. end-time is the 14 character time stamp denoting when
the file was closed. end-time can also be the literal string
not_terminated, indicating the file is still be written to by the
audit daemon or the file was not closed properly (a system crash
or abrupt halt occurred). suffix is the name of the machine that
generated the audit trail file (or some other meaningful suffix;
for example, all would be a good suffix if the audit trail file
contains a combined group of records from many machines).


date-time

The date-time argument to -a, -b, and -d can be of two forms: An
absolute date-time takes the form:

yyyymmdd [ hh [ mm [ ss ]]]

where yyyy specifies a year (with 1970 as the earliest value), mm
is the month (01-12), dd is the day (01-31), hh is the hour
(00-23), mm is the minute (00-59), and ss is the second (00-59).
The default is 00 for hh, mm and ss.

An offset can be specified as: +n d|h|m| s where n is a number of
units, and the tags d, h, m, and s stand for days, hours, minutes
and seconds, respectively. An offset is relative to the starting
time. Thus, this form can only be used with the -b option.


event

The literal string or ordinal event number as found in
audit_event(5). If event is not found in the audit_event file it
is considered invalid.


group

The literal string or ordinal group ID number as found in
group(5). If group is not found in the group file it is
considered invalid. group can be negative.


label

The literal string representation of a MAC label or a range of
two valid MAC labels. To specify a range, use x;y where x and y
are valid MAC labels. Only those records that are fully bounded
by x and y will be selected. If x or y is omitted, the default
uses ADMIN_LOW or ADMIN_HIGH respectively. Notice that quotes
must be used when specifying a range.


pathname

A regular expression describing a pathname.


user

The literal username or ordinal user ID number as found in
passwd(5). If the username is not found in the passwd file it is
considered invalid. user can be negative.

EXAMPLES

Example 1: The auditreduce command

praudit(8) is available to display audit records in a human-readable
form.


This will display the entire audit trail in a human-readable form:


% auditreduce | praudit


If all the audit trail files are being combined into one large file,
then deleting the original files could be desirable to prevent the
records from appearing twice:


% auditreduce -V -D /etc/security/audit/combined/all


This displays what user milner did on April 13, 1988. The output is
displayed in a human-readable form to the standard output:


% auditreduce -d 19880413 -u milner | praudit


The above example might produce a large volume of data if milner has
been busy. Perhaps looking at only login and logout times would be
simpler. The -c option will select records from a specified class:


% auditreduce -d 19880413 -u milner -c lo | praudit


To see milner's login/logout activity for April 13, 14, and 15, the
following is used. The results are saved to a file in the current
working directory. Notice that the name of the output file will have
milnerlo as the suffix, with the appropriate timestamp prefixes.
Notice also that the long form of the name is used for the -c option:


% auditreduce -a 19880413 -b +3d -u milner -c login_logout -O milnerlo


To follow milner's movement about the file system on April 13, 14,
and 15 the chdir record types could be viewed. Notice that in order
to get the same time range as the above example we needed to specify
the -b time as the day after our range. This is because 19880416
defaults to midnight of that day, and records before that fall on
0415, the end-day of the range.


% auditreduce -a 19880413 -b 19880416 -u milner -m AUE_CHDIR | praudit


In this example, the audit records are being collected in summary
form (the login/logout records only). The records are being written
to a summary file in a different directory than the normal audit root
to prevent the selected records from existing twice in the audit
root.


% auditreduce -d 19880330 -c lo -O /etc/security/audit_summary/logins


If activity for user ID 9944 has been observed, but that user is not
known to the system administrator, then the command in the following
example searches the entire audit trail for any records generated by
that user. auditreduce queries the system about the current validity
of ID 9944 and displays a warning message if it is not currently
active:


% auditreduce -O /etc/security/audit_suspect/user9944 -u 9944


To get an audit log of only the global zone:


% auditreduce -z global

FILES

/etc/security/audit/server/files/*

location of audit trails, when stored

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+


The command invocation is Stable. The binary file format is Stable.
The binary file contents is Unstable.

SEE ALSO

audit.log(5), audit_class(5), group(5), hosts(5), passwd(5),
attributes(7), smf(7), praudit(8)

DIAGNOSTICS

auditreduce displays error messages if there are command line errors
and then exits. If there are fatal errors during the run, auditreduce
displays an explanatory message and exits. In this case, the output
file might be in an inconsistent state (no trailer or partially
written record) and auditreduce displays a warning message before
exiting. Successful invocation returns 0 and unsuccessful invocation
returns 1.


Since auditreduce might be processing a large number of input files,
it is possible that the machine-wide limit on open files will be
exceeded. If this happens, auditreduce displays a message to that
effect, give information on how many file there are, and exit.


If auditreduce displays a record's timestamp in a diagnostic message,
that time is in local time. However, when filenames are displayed,
their timestamps are in GMT.

BUGS

Conjunction, disjunction, negation, and grouping of record selection
options should be allowed.

NOTES

The -z option should be used only if the audit policy zonename is
set. If there is no zonename token, then no records will be selected.

March 6, 2017 AUDITREDUCE(8)