Auditing Features

The following features of Solaris BSM auditing are provided to interpret the audit records:

• The audit ID assigned to a user's processes stays the same even when the user ID changes

• Each session has an Audit Session ID
• Full pathnames are saved in audit records

Because each audit record contains an audit ID that identifies the user who generated the event, and because full pathnames are recorded in audit records, you can look at individual audit records and get meaningful information without looking back through the audit trail.

Audit User ID

Solaris BSM processes have an additional user identification attribute not associated with processes in the standard SunOS: the audit ID. A process acquires its audit ID at login time, and this audit ID is inherited by all child processes.

Audit Session ID

Solaris BSM processes have an audit session ID assigned at login time. The ID is inherited by all child processes.

Self-contained Audit Records

The Solaris BSM audit records contain all the relevant information about an event and do not require you to refer to other audit records to interpret what occurred. For example, an audit record describing a file event contains the file's full pathname starting at the root directory, and a time and date stamp of the file's opening or closing.

Tools for Merging, Selecting, Viewing, and Interpreting Audit Records

Solaris BSM provides two tools that allow you to merge, select, view and interpret audit records. The tools can be used directly or in conjunction with third party application programs.

• The auditreduce(1M) command allows you to choose sets of records to examine. For instance, you can select all records from the past 24 hours to generate a daily report; you can select all records generated by a specific user to examine that user's activities; or you can select all records caused by a specific event type to see how often that type occurs.

• The praudit(1M) command allows you to display audit records interactively and create very basic reports. praudit displays records in one of several human-readable but otherwise non-interpreted forms. You may accomplish more sophisticated display and reporting by post-processing the output from praudit (with sed(1) or awk(1), for instance), or by writing programs that interpret and process the binary audit records.

The following sections describe the audit record format, the praudit, and auditreduce commands in more detail, and provide some hints and procedures for using the tools.

Audit Record Format

A Solaris BSM audit record consists of a sequence of audit tokens, each of which describes an attribute of the system.

Appendix A gives a detailed description of each audit token. The appendix also lists all the audit records generated by Solaris BSM auditing. The definitions are sorted in order of the short descriptions, and three cross-reference tables translate event classes, numbers, and names to event descriptions.

Binary Format Audit records are stored and manipulated in binary form; however, the byte order and size of data is predetermined to simplify compatibility between different machines.

Audit Event Type Each auditable event in the system generates a particular type of audit record. The audit record for each event has certain tokens within the record that describe the event. An audit record does not describe the audit event class to which the event belongs; that mapping is determined by an external table, the file audit_event(4).

Audit token Types Each token starts with a one-byte token type, followed by one or more data elements in an order determined by the type. The different audit records are distinguished by event type and different sets of tokens within the record.

Some tokens, such as the text token, contain only a single data element, while others, such as the process token, contain several (including the audit user ID, real user ID, and effective user ID).

Order of Audit Tokens

Each audit record begins with a header token and ends (optionally) with a trailer token. One or more tokens between the header and trailer describe the event. For user-level and kernel events, the tokens describe the process that performed the event, the object(s) on which it was performed, and the object's tokens, such as the owner or mode.

Each user-level and kernel event typically has at least the following tokens:

• Header
• Subject
• Return
• Trailer

although the trailer token is optional, depending on the trail policy that can be set with the auditconfig(1M) command.

Human-readable Audit Record Format

This section shows each audit record format as it appears in the output produced by the praudit command. This section also gives a short description of each audit token. For a complete description of each field in each token, see Appendix A "Audit Record Descriptions."

The following token examples show the form that praudit produces by default. Examples are also provided of praudit's raw (-r) and short (-s) options. When praudit displays an audit token, it begins with the token type, followed by the data from the token. Each data field from the token is separated from other fields by a comma. However, if a field (such as a pathname) contains a comma, this cannot be distinguished from a field-separating comma. Use a different field separator or the output will contain commas. The token type is displayed by default as a name, like "header", or in -r format as a decimal number ("18").

The individual tokens are described in the following order.

headeropaque

trailerpath arbitrary

arg

attrprocess

return

exitseq

file

groupssocket

subject

in_addrtext

ip

ipc

ipc_perm

iport

Header Token

Every audit record begins with a header token. The header token gives information common to all audit records. The fields are:

• a token ID
• the record length in bytes, including the header and trailer tokens
• an audit record structure version number
• an event ID identifying the type of audit event
• an event ID modifier with descriptive information about the event type
• the time and date the record was created

When displayed by praudit in default format, a header token looks like the following example from ioctl(2):

header,240,1,ioctl(2),es,Tue Sept  1 16:11:44 1992, + 270000 msec

In praudit's -s format, the event description (ioctl(2)in the default praudit example above) is replaced with the event name ("AUE_IOCTL"), like this:

header,240,1,AUE_IOCTL,es,Tue Sept 1 16:11:44 1992, + 270000 msec

In praudit's -r format, all fields are displayed as numbers (that may be decimal, octal, or hex), where "158" is the event number for this event.

20,240,1,158,0003,699754304, + 270000 msec

Note that praudit displays the time to milli-second resolution.

Trailer Token

This token marks the end of an audit record and allows backward seeks of the audit trail. The fields are:

• token ID
• a pad number that marks the end of the record (does not show)
• the total number of audit record characters including the header and trailer tokens.

A trailer token is displayed by praudit as follows:

trailer,136

Arbitrary Token

This token encapsulates data for the audit trail. The item array may have a number of items. The fields are:

• token ID
• a suggested format, such as decimal
• a size of encapsulated data, such as int
• a count of the data array items
• an item array.

An arbitrary token is displayed by praudit as follows:

arbitrary,decimal,int,1 42

Arg Token

This token contains system call argument information. A 32 bit integer system call argument is allowed in an audit record. The fields are:

• token ID
• an argument ID of the relevant system call argument
• the argument value
• the length of an optional descriptive text string (does not show)
• an optional text string.

An arg token is displayed by praudit as follows:

argument,1,0x00000000,addr

Attr Token

This token contains information from the file vnode. Attr is usually produced during path searches and accompanies a path token, but is not included in the event of a path-search error. The fields are:

• token ID
• the file access mode and type
• the owner user ID
• the owner group ID
• the file system ID
• the i-node ID
• the device ID that the file might represent.

An attr token is displayed by praudit as follows:

attribute,100555,root,staff,1805,13871,-4288

Exit Token

An exit token records the exit status of a program. The fields are:

• token ID
• a program exit status as passed to the exit(2) system call
• a return value that describes the exit status or indicates a system error number.

An exit token is displayed by praudit as follows:

exit,Error 0,0

File Token

This token is generated by the audit daemon to mark the beginning of a new audit trail file and the end of an old file as the old file is deactivated. The audit record containing this token links together successive audit files into one audit trail. The fields are:

• token ID
• a time and date stamp of a file opening or closing
• a byte count of the file name (does not show)
• the file name

A file token is displayed by praudit as follows:

file,Tue Sep 1 13:32:42 1992, + 79249 msec, /baudit/localhost/files/19920901202558.19920901203241.quisp

Groups Token

A groups token records the groups entries from a process's credential. The fields are:

• token ID
• an array of groups entries of size NGROUPS_MAX (16).

A groups token is displayed by praudit as follows:

group,staff,wheel,daemon,kmem,bin,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1

In_addr Token

An in_addr token gives a machine Internet Protocol address. The fields are:

• token ID
• an internet address.

An in_addr token is displayed by praudit as follows:

ip addr,129.150.113.7

Ip Token

The ip token contains a copy of an Internet Protocol header. The fields are:

• token ID
• a 20 byte copy of an IP header.

An ip token is displayed by praudit as follows:

ip address,0.0.0.0

Ipc Token

This token contains the System V IPC message/semaphore/shared-memory handle used by a caller to identify a particular IPC object. The fields are:

• token ID
• an IPC object type identifier
• the IPC object handle.

An ipc token is displayed by praudit as follows:

IPC,msg,3

Ipc_perm Token

An ipc_perm token contains a copy of the System V IPC access information. Audit records for shared memory, semaphore, and message IPCs have this token added. The fields are:

• token ID
• the IPC owner's user ID
• the IPC owner's group ID
• the IPC creator's user ID
• the IPC creator's group ID
• the IPC access modes
• the IPC sequence number
• the IPC key value.

An ipc_perm token is displayed by praudit as follows:

IPC perm,root,wheel,root,wheel,0,0,0x00000000

Iport Token

This token contains a TCP (or UDP) address. The fields are:

• token ID
• a TCP/UDP address.

An iport token is displayed by praudit as follows:

ip port,0xf6d6

Opaque Token

The opaque token contains unformatted data as a sequence of bytes. The fields are:

• token ID
• a byte count of the data array
• an array of byte data.

An opaque token is displayed by praudit as follows:

opaque,12,0x4f5041515545204441544100

Path Token

A path token contains access path information for an object. The fields are:

• token ID
• a byte count of the path length (does not show)
• an absolute path.

A path token is displayed by praudit as follows:

path,/an/anchored/path/name/to/test/auditwrite/AW_PATH

Process Token

The process token contains information describing a process. The fields are:

• token ID
• the user audit ID
• the effective user ID
• the effective group ID
• the real user ID
• the real group ID
• the process ID
• the session ID
• a terminal ID made up of

  · a device ID

  · a machine ID.

A process token is displayed by praudit as follows:

process,root,root,wheel,root,wheel,0,0,0,0.0.0.0

Return Token

A return token gives the return status of the system call and the process return value. This token is always returned as part of kernel generated audit records for system calls. The fields are:

• token ID
• the system call error status
• the system call return value.

A return token is displayed by praudit as follows:

return,success,0

Seq Token

This token is optional and contains an increasing sequence number used for debugging. The token is added to each audit record when AUDIT_SEQ is active. The fields are:

• token ID
• a 32 bit unsigned long sequence number.

A seq token is displayed by praudit as follows:

sequence,1292

Socket Token

A socket token describes an Internet socket. The fields are:

• token ID
• a socket type field (TCP/UDP/UNIX)
• the local port address
• the local Internet address
• the remote port address
• the remote Internet address.

A socket token is displayed by praudit as follows:

socket,0x0000,0x0000,0.0.0.0,0x0000,0.0.0.0

Subject Token

This token describes a subject (process). The fields are:

• token ID
• the user audit ID
• the effective user ID
• the effective group ID
• the real user ID
• the real group ID
• the process ID
• the session ID
• a terminal ID made up of

  · a device ID

  · a machine ID.

A subject token is displayed by praudit as follows:

subject,cjc,cjc,staff,cjc,staff,424,223,0 0 quisp

Text Token

A text token contains a text string. The fields are:

• token ID
• the length of the text string (does not show)
• a text string.

A text token is displayed by praudit as follows:

text,aw_test_token

Using the auditreduce Command

The auditreduce command merges together audit records from one or more input audit files. You would usually enter this command from the machine on which all the audit trail files for the entire distributed system are mounted.

Without options, auditreduce merges the entire audit trail (all of the audit files in all of the subdirectories in the audit root/etc/security/audit directory) and sends the merged file to standard output.

The praudit command, described in "Using praudit" makes the records human-readable.

The following are some of the capabilities provided by options to the auditreduce command.

• Give output containing audit records generated only by certain audit flags.
• Show audit records generated by one particular user.
• Collect audit records generated on specific dates.

How auditreduce Helps In a Distributed System

When multiple machines running Solaris BSM are administered as part of a distributed system, each machine performs auditable events, and each machine writes audit records to its own machine-specific audit file. This simplifies software and is robust in the face of machine failures. However, unless a tool existed to make it easier, you would have to look at every one of the files to determine a particular user's actions.

The auditreduce(1M) command makes the job of maintaining the whole audit trail practical. Using auditreduce (or, shell scripts you write yourself to provide a higher-level interface), you can read the logical combination of all audit files in the system as a single audit trail, without regard to how the records were generated or where they are stored.

The auditreduce program operates on the audit records produced by the audit daemon. Records from one or more audit files are selected and merged into a single, chronologically ordered output file. The merging and selecting functions of auditreduce are logically independent. auditreduce selects messages from the input files as the records are read, before the files are merged and written to disk. Refer to the auditreduce(1M) man page.

auditreduce Examples

This section describes a few common uses of auditreduce to analyze and manage data.

Example 1: How to Display the Whole Audit Log

To display the whole audit trail at once, pipe the output of auditreduce into praudit.

# auditreduce | praudit

Example 2: How to Print the Whole Audit Log

With a pipe to lpr, the output goes to the printer.

# auditreduce | praudit | lpr

Example 3: How to Display User Activity on a Selected Data

In the following example, the system administrator checks to see when a user named fred logged in and logged out on April 13, 1990, by requesting the lo message class. The short-form date is in the form yymmdd. (The long form is described on the auditreduce(1M) man page.)

# auditreduce -d 900413 -u fred -c lo | praudit

Example 4: How to Copy Login/Logout Messages to a Single File

In this example, login/logout messages for a particular day are summarized into a file. The target file is written in a directory other than the normal audit root. This is the command line:

# auditreduce -c lo -d 870413 -O /usr/audit_summary/logins

The -O option creates an audit file with 14-character timestamps for both start-time and end-time, and the suffix "logins":

/usr/audit_summary/19870413000000.19870413235959.logins

Example 5: How to Clean Up a not_terminated Audit File

Occasionally, if an audit daemon dies while its audit file is still open, or a server becomes inaccessible and forces the machine to switch to a new server, an audit file remains in which the end-time in the file name remains the string not_terminated, even though the file is no longer used for audit records. When such a file is found, you can manually verify that the file is no longer in use and clean it up by specifying the name of the file with the correct options. The following screen example shows the commands:

# auditreduce -O machine 19870413120429.not_terminated.<machine>

This creates a new audit file with the correct name (both timestamps), the correct suffix (machine, explicitly specified), and copies all the messages into it.

Other Useful auditreduce Options

auditreduce has many additional options described in the man page. Note that the upper case options select operations or parameters for files, and the lower case options select parameters for records. This subsection shows how to make use of two more useful options.

The date-time options -b and -a allow specifying records before or after a particular day/time. A day begins at yyyymmdd00:00:00 and ends at yyyymmdd23:59:59. The six parameters of a day are: year, month, day, hour, minute, and second. The digits (19) of the year are assumed and need not be specified.

If -a is not specified, auditreduce defaults to 00:00:00, January 1, 1970. If -b is not specified, auditreduce defaults to the current time of day (GMT). The -d option selects a particular 24-hour period, as shown in "Example 4: How to Copy Login/Logout Messages to a Single File" on page 55.

The auditreduce -a command with the date shown in the following screen example sends all audit records created after midnight on 7/15/91 to praudit.

# auditreduce -a 91071500:00:00 | praudit

The auditreduce -b command with the same date shown above sends all audit records created before midnight on 7/15/91 to praudit.

# auditreduce -b 91071500:00:00 | praudit

The message type selection for auditreduce (-m option) accepts either numeric message identifiers or AUE_xxxxx codes. Auditreduce rejects an incorrect format, but does not describe the correct format.

Using praudit

The praudit command reads audit records from standard input and displays them on standard output in human-readable form. Usually, the input is either piped from auditreduce or a single audit file. Input may also be produced with cat(1) to concatenate several files or tail(1) for a current audit file.

praudit can generate three output formats: default, short (-s option), and raw (-r option). By default, output is produced with one token per line. The -l option requests a whole record on each line. The -d option changes the delimiter used between token fields, and between tokens if -l is also specified.

In -s format, the type is the audit event table name for the event (such as "AUE_IOCTL), and in -r format, it is the event number (in this case, 158). That is the only distinction between -s and default format. In -r format, all numeric values (user IDs, group IDs, etc.) are displayed numerically (in decimal, except for Internet addresses, which are in hex, and for modes, which are in octal). Here is the output from praudit for a header token:

header,240,1,ioctl(2),es,Tue Sept 1 16:11:44 1992, + 270000 msec

And here is the output from praudit -r for the same header token:

20,240,1,158,0003,699754304, + 270000 msec

It is sometimes useful to manipulate praudit's output as lines of text, for instance to perform selections that cannot be done with auditreduce. A simple shell script can process the output of praudit. The following example is called praudit_grep):

#!/bin/sh
praudit | sed -e '1,2d' -e '$s/^file.*$//' -e 's/^header/^Aheader/' \\
| tr '\\012\\001' '\\002\\012' \\
| grep "$1" \\
| tr '\\002' '\\012'

The example script marks the header tokens by prefixing them with Control-A. (Note that the "^A" is a literal Control-A, not the two characters "^" and "A". Prefixing is necessary to distinguish them from the string "header" that might appear as text in praudit's output.) The script then combines all the tokens for a record onto one line while preserving the line breaks as Control-A, runs grep, and restores the original newlines.

Note that in praudit's default output format, each record can always be identified unambiguously as a sequence of tokens (each on a separate line) beginning with a "header" token and ending with a "trailer" token. Each record, therefore, is easily identified and processed with awk, for instance.