NAME

auditreduce - Merge and select audit records from audit-trail files

SYNOPSIS

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

AVAILABILITY

SUNWcsu

DESCRIPTION

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

The merge function merges into a single output file the audit records from one or more input audit-trail files. Assuming that the records in an audit-trail file are sorted in chronological order (oldest first), auditreduce maintains this order 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. [See audit_control(4TSOL) for details of the structure of the audit root.] Without the -R or the -S option, audit_root_dir defaults to /etc/security/audit. Using the file-selection options enables selection of some subset of these files or files from another directory or files named explicitly on the command line.

The select function allows selection of audit records on the basis of criteria relating to the record's content. [See audit.log(4TSOL) 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:

start-time. end-time. suffix

where start-time is the 14-character time stamp showing when the file was opened, endtime is the 14-character time stamp showing when the file was closed, and suffix is either the name of the machine that generated the audit-trail file or some other meaningful suffix , such as all if the file contains a combined group of records from many machines. The end-time may be the literal string not_terminated, to indicate that the audit system is still writing to the file. Time stamps take the form yyyymmddhhmmss (year, month, day, hour, minute, second). The time stamps 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 time stamp. This option effectively disables the -a ,-b, and -d recordselection options. This option is useful in preventing the loss of records if the -D option is used to delete the input files after they are processed. However, if another option forbids a record's selection, -A will not override that option.

-C

Process only complete files. Files whose file-name end-time time stamp is not_terminated are not processed. (The audit system is currently writing to such a file.) This option is useful in preventing the loss of records if -D is used to delete the input files after they are processed. This option does not apply to files specified on the command line.

-D suffix

Delete input files after they are processed. The files are deleted only if the entire run is successful. If auditreduce detects an error while reading a file, then that file is not deleted. Specifying -D implies -A, -C, and -O also. suffix is given to the -O option to help 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

Select records from files with machine as the file-name suffix. If -M is not specified, all files are processed regardless of suffix. -M can be used also to allow selection of records from files that contain combined records from many machines and have a common suffix (such as all). Contrast this option with -h, which uses the content of an audit record to select where a particular audit record was collected.

-O suffix

Direct output stream to a file in the current audit_root_dir with the indicated suffix. suffix may alternatively contain a full path name. If so, the last component is taken as the suffix, ahead of which the time stamps (yyyymmddhhmmss) will be placed, ahead of which the remainder of the pathname will be placed for the name of the output file.

If the -O option is not specified, the output is sent to the standard output. When it places time stamps in the file name, auditreduce uses the times of the first and last records in the merge as the start-time and endtime.

-Q

Quiet. Suppress notification about errors with input files.

-R pathname

Use pathname in place of the audit root directory audit_root_dir. Examine pathname/* /filesrather than using /etc/security/audit/* /filesby default.

-S server

This option causes auditreduce to read audit-trail files from a specific location (server directory). Because server is normally interpreted as the name of a subdirectory of the audit root, auditreduce will look in audit_root_dir/server/files for the audit-trail files.

However, if server contains any slash (/) 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 state the total number of records that were written to the output stream.

Record-Selection Options

The record-selection options listed are used to indicate which records auditreduce writes to the output file.

NOTE: 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 subsequently under Option Arguments . date-time is 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; select only records with events that are mapped to the audit classes specified by audit-classes. Auditclass names are defined in audit_class(4TSOL). The audit-classes can be a comma-separated list of audit flags like those described in audit_control(4TSOL). Using the audit flags, one can use success and failure as selection criteria.

-d date-time

Select records that occurred on a specific day (a 24-hour period beginning at 00:00:00 and ending at 23:59:59 of the day specified). The day specified is in local time. The time portion of the argument, if supplied, is ignored; any records with time stamps during that day are selected. If any hours, minutes, or seconds are given in time, they are ignored. -d cannot 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.

-h hostmachine

Select records generated on hostmachine using the content of the audit record, not the audit-file name. Contrast this option with -M ,which bases selection on file name.

-i information-label

Select records with the specified information-label, which may be a range as explained under Option Arguments ,information-label.

-j subject-ID

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

-m event

Select records with the indicated event. The event is either 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.These are allowable object types and values:

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 pre-

ceded 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 reg-

ular 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. Sur-

round the pathname with quotes to prevent the shell from

expanding any tildes.

msgqid=ID

Select records containing message-queue objects with the

specified ID where ID is a message queue ID .

pid=ID Select records containing process objects with the specified

ID where ID is a process ID .NOTE: Processes are objects

when they are receivers of signals.

semid=ID

Select records containing semaphore objects with the

specified ID where ID is a semaphore ID .

shmid=ID

Select records containing shared memory objects with the

specified ID where ID is a shared memory ID .

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(4).

-r real-user

Select records with the specified real-user.

-s sensitivity-label

Select records with the specified sensitivity-label, which may be a range as explained under Option Arguments, sensitivity-label.

-u audit-user

Select records with the specified audit-user.

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 file-name format. However, -M ,-S, and -R may not be used when processing named files. If the filename is hyphen (-), then the input is taken from the standard input.

Option Arguments

audit-trail-file

An audit-trail file as defined in audit.log(4TSOL). 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:

start-time. end-time. suffix

start-time is the 14-character time stamp denoting when the file was opened. end-time is either the 14-character time stamp denoting when the file was closed or the literal string not_terminated, indicating either that the audit daemon is still writing to the file or that the file was not closed properly (a system crash or abrupt halt occurred). suffix is either 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 audittrail file contains a combined group of records from many machines.

date-time

The date-time argument to -a ,-b, and -d can be absolute or offset. An absolute date-time takes the form:

yyyymmdd [ hh [ mm [ ss ] ] ]

where yyyy is a year (1970 at the earliest), 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 for hh ,mm, and ss is 00 .

An offset can be specified as +nd|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. Because an offset is relative to the starting time, this form can be used only with the -b option.

event

The literal string or ordinal event number as found in

audit_event(4TSOL). If not found in the audit_event file, event is considered invalid.

group

The literal string or ordinal group ID number as found in group(4). If not found in the group file, group is considered invalid. group may be negative.

information-label The literal string representation of either an exact, valid information

label or a range of two valid information labels

To specify a range, use [x]:[y] where x and y are valid information 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.

pathname

A regular expression describing a path name

sensitivity-label

The literal string representation of an sensitivity label or a range of two

valid sensitivity labels.

To specify a range, use [x]:[y] where x and y are valid sensitivity 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.

user

The literal user name or ordinal user ID number as found in passwd(4). If not found in the passwd file, the user name is considered invalid. user may be negative.

RETURN VALUES

Upon success, auditreduce returns 0 .Upon failure, auditreduce returns 1 .

EXAMPLES

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

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, delete the original files to prevent the records from appearing twice:

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

Print what user wetmore did on April 13, 1988; and display the output in a humanreadable form to the standard output:

% auditreduce -d 19880413 -u wetmore | praudit

Because the previous example may produce a large volume of data if wetmore has been busy, look at only login and logout times:

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

The -c option selects records from a specified class.

Record wetmore 'slogin/logout activity for April 13, 14, and 15 in a file in the current working directory:

% auditreduce -a 19880413 -b +3d -u wetmore -c lo -O wetmorelo

The output file has wetmorelo as the suffix and the appropriate time-stamp prefixes. Note that the short form (lo) of the audit-event name is used for the -c option.

Viewing his directory changes (chdir) tracks wetmore 'smovement about the file system on April 13, 14, and 15. To get the same time range as the previous example, you need to specify the -b time as the day after the range 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 wetmore -m AUE_CHDIR | prau-
dit

Determine whether wetmore accessed any highly classified information at SECRET A B ,a valid label on the system:

% auditreduce -a 19880413 -b +3d -u wetmore -s "SECRET A
B:ADMIN_HIGH" | praudit

Collect the audit records in summary form (the login/logout records only). The records are being written to a summary file in a different directory from 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

Activity for user ID 9944 has been observed, but that user is not known to the system administrator. Search the entire audit trail for any records generated by that user. auditreduce will query the system as to the current validity of ID 9944, and print a warning message if it is not currently active:

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

SUMMARY OF TRUSTED

The Trusted Solaris system has added these record-selection options to this command: -h hostmachine, -i information-label, and -s sensitivity-label. These option arguments have been added: information-label and sensitivity-label. The EXAMPLES section shows how to audit a user for access to data at a specific sensitivity label.

SOLARIS CHANGES

FILES

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

Storage location of audit trails

SEE ALSO

praudit(1MTSOL), audit.log(4TSOL), audit_class(4TSOL), audit_control(4TSOL), group(4), hosts(4), passwd(4), Trusted Solaris Audit Administration Manual

DIAGNOSTICS

If there are command-line errors, auditreduce prints error messages and then exits. If there are fatal errors during the run, auditreduce prints an explanatory message and exits. In this case, the output file may be in an inconsistent state (missing a trailer or containing a partially written record) and auditreduce prints a warning message before exiting.

Because auditreduce may be processing a large number of input files, it is possible that the machinewide limit on open files may be exceeded. If it is, auditreduce prints a message to that effect, gives information on how many file there are, and exits.

If auditreduce prints a record's time stamp in a diagnostic message, that time is local time. However, when file names are displayed, their time stamps are in GMT.

NOTES

This functionality is active only if the audit module has been enabled. By default, auditing is enabled in the Trusted Solaris environment. See Trusted Solaris Audit Administration Manual for how to disable and enable auditing.

BUGS

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