NAME

auscan − selectively retrieves entries from the audit trail file

SYNOPSIS

auscan[-t ttyname_1[,ttyname_2,...]]
[-u uname_1[,uname_2,...]]
[-d [[mmdd]hhmm[yy]][:{[mmdd]hhmm[yy] | +hhmm}]]
[-c class_1[,class_2,...]]
[-e event_1[,event_2,...]]
[-s syscall_1[,syscall_2,...]]
[-D]
[-C]
[-S]
[-O]
[-f]
[-o output_file]
[filename ...]

DESCRIPTION

auscan is an audit trail processing tool designed to selectively retrieve records from an audit trail before they are formatted by auconvert(1M) or aureport(1M).  The audit trail examined by auscan can be an audit trail file (filename) or standard input. 

auscan may only be executed by root. 

An entry or record in the audit trail consists of the following:

1.  Header information

2.  One or more parameters

3.  One or more audit events

Records are retrieved based on the logical AND of the options specified. 

-t Specifies a list of tty names, ttyname_1,...,ttyname_n.  The tty name should be of the form /dev/ttyx or ttyx.  The name need not start with tty; if /dev/fred is Fred’s terminal (or pseudo-terminal), then /dev/fred or fred may be used.  Records are selected if they were generated on behalf of a process whose controlling tty is in the list of specified terminals.  If multiple -t options are specified, the effects will be cumulative (i.e., each option adds additional ttys without clearing previously listed terminals).  If the same tty name is specified more than once, the extra listing will be silently ignored. 

-u Specifies a list of user login names, uname_1,...,uname_n.  Event records for processes owned by the specified user(s) are selected.  If multiple -u options are specified, the effects will be cumulative (i.e., each option adds additional users without clearing previously listed users).  If the same user name is specified more than once, the extra listing will be silently ignored. 

-d Specifies all or part of a date/time combination, [mmdd]hhmm[yy], as specified in date(1).  Events that occurred within the specified time frame are selected.  If an initial time is omitted, there will be no starting time requirement.  If the second time is omitted, the ending time will be left open.  If +hhmm is specified as the second time, the amount of time specified will be added to the first time and used as the ending time. 

-c Specifies a list of audit class names, class_1,...,class_n.  Records that originate from a command or system call in the class are selected.  A class is a group of commands or system calls that perform related functions.  See audit(4) for more information about valid class names.  The list of valid class names is found in /var/security/auclass.  If multiple -c options are specified, the effects will be cumulative (i.e., each option adds additional audit classes without clearing previously listed audit classes).  If the same audit class name is specified more than once, the extra listing will be silently ignored. 

-e Specifies a list of event type names, event_1,...,event_n.  Records with the specified event type are selected.  The list of valid event types can be found in /var/security/auevent.  See audit(4) for more information about valid event type names.  If multiple -e options are specified, the effects will be cumulative (i.e., each option adds additional event types without clearing previously listed event types).  If the same event type name is specified more than once, the extra listing will be silently ignored. 

-s Specifies a list of system call names, syscall_1,..., syscall_n.  Event records associated with any of the system calls specified are selected.  If multiple -s options are specified, the effects will be cumulative (i.e., each option adds additional system calls without clearing previously listed system calls).  If the same system call name is specified more than once, the extra listing will be silently ignored. 

-D Selects event records that fail due to DAC controls. 

-C Selects event records that identify known covert channels. 

-S Selects event records that succeed. 

-O Selects event records that fail due to other or special security constraints. 

-f Causes auscan not to quit at end-of-file, but to repeatedly attempt to read the last file specified, expecting the file to grow.  The administrator can terminate auscan by issuing an interrupt (i.e., control-C or DEL) character or by sending a kill signal to the process.  If more than one input file is specified, the -f option will only apply to the last file.  This behavior is equivalent to the -f option of tail(1). 

-o Specifies the output_file for the auscan results. 

After all of the options have been processed, a summary of the selection criteria is displayed on the standard error output.  If no input files are listed, audit records will be read from standard input.  If no selection criteria are specified, auscan will copy its input files to the output file, discarding any invalid audit records.  As each input file is processed, two lines are displayed on the standard error output, showing the number of records read and the number of records written.  If a keyboard interrupt (signal SIGINT, normally delete or control-C) is received, or if a terminate signal (SIGTERM) is received, then processing will be terminated, but the summary information will still be displayed.  This is particularly useful when using the -f option to wait at the end of the file for additional input. 

Note that the files specified to be scanned must be in binary form and that the resultant output from auscan remains in binary form.  The output from auscan should be processed by auconvert to convert the file contents into text form. 

EXAMPLE

To select audit records associated with:

Users fred or sally

Using audit classes open (open(2)), link (link(2)), or login (login(1))

Which failed because of DAC failures

Reading audit records from /usr/spool/audit/monday

Sending output to fred.sally

the following command would be used:

auscan -u fred,sally -c open,link,login \
-D -o fred.sally /usr/spool/audit/monday

The output of this command on standard error would be:

Selection criteria are:
Reasons: DAC Failure
Audit classes: link login open
Users: fred sally
auscan: processing /usr/spool/audit/monday
auscan: xxx records read
auscan: yyy records selected
auscan: processing complete

DIAGNOSTICS

auscan prints all diagnostics on standard error.  The exit code will be zero (0) if no errors were encountered, 1 if there was an error in option processing, or 2 if one of the files could not be opened. 

The following error messages are generated during option processing.  All are fatal:

auscan: xxx is not a block or char device
The device specified with a -t option is not a block or character device. 

auscan: xxx is not a system call
The system call name specified with a -s option is not a valid system call name.  Consult sys/syscall.h for a complete list of system calls. 

auscan: aborting due to fatal option error
One or more option processing errors was encountered, so the scan will not take place.

auscan: can’t open xxx for writing
The output file specified with the -o option could not be opened for writing. 

auscan: cannot stat xxx
The device name specified with the -t option could not be located. 

auscan: ending date is before starting date
The starting and ending dates specified by the -d option were such that the ending date was before the starting date. 

auscan: event xxx is not in audit event type file
The event name specified with the -e option is not a valid event name.  See /var/security/auevent for a complete list of valid event names. 

auscan: class xxx is not in audit class file
The class name specified with the -c option is not a valid class name.  See /var/security/auclass for a complete list of valid class names. 

auscan: invalid date format xxx
The date specified with the -d option is in an invalid format. 

auscan: invalid null tty name
A null terminal name was specified using the -t option (by having two adjacent commas, a leading comma, or a trailing comma in the terminal list). 

auscan: invalid null username
A null user name was specified using the -u option (by having two adjacent commas, a leading comma, or a trailing comma in the user name list). 

auscan: invalid null system call
A null system call name was specified using the -s option (by having two adjacent commas, a leading comma, or a trailing comma in the system call list). 

auscan: invalid null event type
A null event type name was specified using the -e option (by having two adjacent commas, a leading comma, or a trailing comma in the event type list). 

auscan: invalid null audit class
A null audit class name was specified using the -c option (by having two adjacent commas, a leading comma, or a trailing comma in the audit class name list). 

auscan: no date value provided
The -d option was specified, but neither a starting nor an ending date were provided. 

auscan: too many terminals; maximum is xxx
Too many terminal names were specified; the maximum is 15.

auscan: too many users; maximum is xxx
Too many user names were specified; the maximum is 15.

auscan: too many event types; maximum is xxx
Too many event type names were specified; the maximum is 15.

auscan: user xxx is not in passwd file
The user specified with the -u option is not listed in the password file. 

The following error messages are generated during file processing:

auscan: couldn’t open xxx
The specified audit file could not be opened.  The scan terminates.

auscan: error writing record xxx
There was an error when writing the output record specified.  This typically indicates that the file system was full or an I/O error occurred.  The scan continues.

auscan: audit class file error: class xxx out of range
An error was detected in the audit class file: a class number xxx was found that is outside the allowable range of audit class numbers.  The scan continues. 

The following informational messages are generated during file processing:

auscan: xxx records read
The scan read the specified number of audit records.

auscan: xxx records selected
The scan wrote the specified number of audit records.

auscan: interrupt!
A SIGINT or SIGTERM signal was received, causing the auscan process to cease processing the current file.  This is always followed by the processing aborted message (below). 

auscan: processing xxx
The file whose name is shown is being processed.

auscan: processing aborted
Processing was aborted because of a SIGINT or SIGTERM signal. The file being processed is aborted, and any additional files are skipped.

auscan: processing complete
Processing of all files has been completed.

auscan: processing standard input
Because no input files were specified, the input will come from standard input.

auscan: will wait at end of file (-f option)
The -f option was specified, so auscan will wait for additional input when it reaches the end of the current input file. 

FILES

/etc/passwd To verify user names

/var/security/auevent To convert audit event type names

/var/security/auclass To convert audit class names

/dev/tty∗ To get terminal information

SEE ALSO

date(1), auconvert(1M), auclass(4), audit(4), auevent(4)

(Security Enhancement)