Audit Commands

This section provides information about the commands that are used with the auditing service.

The Audit Daemon

The following list summarizes what the audit daemon, auditd, does.

• auditd opens and closes audit log files in the directories that are specified in the audit_control file, in the order in which they are specified.

• auditd reads audit data from the kernel and writes the data to an audit log file.

• auditd executes the audit_warn script when the audit directories fill past limits that are specified in the audit_control file. The script, by default, sends warnings to the audit_warn mail alias and to the console.

• By default, when all audit directories are full, processes that generate audit records are suspended. In addition, the auditd command writes a message to the console and to the audit_warn mail alias. The audit policy can be reconfigured with the auditconfig command. At this point, only the system administrator fix the auditing mechanism. The administrator can log in to write audit files to tape, can delete audit files from the system, and can do other cleanup.

The auditd daemon can be started automatically when the machine is brought up to multiuser mode, or you can start it from the command line. When the audit daemon is started, it determines the amount of free space necessary for audit log files.

The daemon uses the list of audit directories in the audit_control file as possible locations for creating audit files. The audit daemon maintains a pointer into this list of directories, starting with the first directory. Every time the audit daemon needs to create an audit file, it puts the file into the first available directory in the list. The list starts at the audit daemon's current pointer. You can reset the pointer to the beginning of the list by running the audit -s command. The audit -n command instructs the daemon to switch to a new audit file. The new file is created in the same directory as the current file.

The audit Command

The audit command controls the actions of the audit daemon. The audit command can do the following tasks:

• Enable and disable auditing

• Reset the audit daemon

• Adjust the auditing preselection mask on the local machine

• Write audit records to a different audit log file

See the audit(1M) man page for a discussion of the available options.

The bsmrecord Command

The bsmrecord command displays the format of audit events that are defined in the /etc/security/audit_event file. The output includes the event's audit ID, audit class, audit flag, and the record's tokens in order. With no option, the bsmrecord output displays well in a terminal window. With the -h option, the output is suitable for viewing in a browser. See How to Display Audit Record Formats for examples of its use. For more information, see the bsmrecord(1M) man page.

The auditreduce Command

Use the auditreduce command to merge audit records from one or more input audit files. The command can also be used to perform a post selection of audit records. See the auditreduce(1M) man page. To merge the entire audit trail, run this command on the audit server. The audit server is the machine that mounts all the audit file systems for the installation.

The auditreduce command enables you to track all auditable actions on multiple machines from a single location. The command can read the logical combination of all audit files as a single audit trail. You must identically configure all machines at a site for auditing, and create servers and local directories for the audit log files. The auditreduce command ignores how the records were generated or where they are stored. Without options, the auditreduce command merges audit records from all the audit files in all of the subdirectories in the audit root directory. Typically, /etc/security/audit is the audit root directory. The auditreduce command sends the merge result to standard output. You can also place the result into a single, chronologically ordered output file. The file contains binary data.

The auditreduce command also can select particular types of records for analysis. The merging functions and selecting functions of the auditreduce command are logically independent. auditreduce captures data from the input files as the records are read, before the files are merged and then written to disk.

The praudit command makes the binary output of the auditreduce command readable.

By specifying options to the auditreduce command, you can also do the following:

• Request audit records that were generated by only certain audit flags

• Request audit records that were generated by one particular user

• Request audit records that were generated on specific dates

With no arguments, auditreduce checks the subdirectories within the /etc/security/audit directory, the default audit root directory. The command checks for a files directory in which the start-time.end-time.hostname files reside. The auditreduce command is very useful when audit data resides in separate directories. Figure 23–1 illustrates audit data in separate directories for different hosts. Figure 23–2) illustrates audit data in separate directories for different audit servers.

Figure 23–1 Audit Trail Storage Sorted by Host

Figure 23–2 Audit Trail Storage Sorted by Server

If the partition for /etc/security/audit is very small, you might not store audit data in the default directory. You can pass the auditreduce command another directory by using the -R option:

# auditreduce -R /var/audit-alt 

You can also specify a particular subdirectory by using the -S option:

# auditreduce -S /var/audit-alt/host1 

You can direct auditreduce to process only certain audit log files by specifying them as command arguments:

# auditreduce /var/audit/egret/files/2001*.2001*egret

For other options and additional examples, see the auditreduce(1M) man page.

The praudit Command

The praudit command reads audit records in binary format from standard input and displays the records in a presentable format. The input can be piped from the auditreduce command or from a single audit file. Input can also be produced with the cat command to concatenate several files, or the tail command for a current audit file.

The praudit command can generate five output formats:

• Default – The default option displays one audit token per line. The default option displays the audit event by its description, such as ioctl(2), and displays any value that could be text in text format. For example, a user is displayed as the user name, not as the user ID.

• –l option – The long option displays one audit record per line. The -d option changes the delimiter used between token fields, and between tokens. The default delimiter is a comma.

• –r option – The raw option displays as a number any value that could be numeric. For example, a user is displayed by user ID, Internet addresses are in hexadecimal format, and modes are in octal format. The audit event is displayed as its event number, such as 158.

• –s option – The short option displays the audit event by its table name, for example, AUE_IOCTL. The option displays the other tokens as the default option displays them.

• –x option – The XML option displays the audit record in XML format. This option is useful as input to browsers, or as input to scripts that manipulate XML.

  The XML is described by a DTD that the audit subsystem provides. Solaris software also provides a style sheet. The DTD and the style sheet are in the /usr/share/lib/xml directory.

In the default output format of praudit, each record is easily identified as a sequence of audit tokens. Each token is on a separate line. Each record begins with a header token. You could, for example, further process the output with the awk command.

Here is the default output from the praudit command for a header token:

header,240,1,ioctl(2),es,Tue Sept  7 16:11:44 1999, + 270 msec

Here is the output from the praudit -r command for the same header token:

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

Example—Processing praudit Output With a Script

Sometimes, you might want to manipulate output from the praudit command as lines of text. For example, you might want to select records that the auditreduce command cannot select. You can use a simple shell script to process the output of praudit. The following simple example script puts one audit record on one line, searches for a user-specified string, then returns the audit file to its original form. Specifically, the script does the following:

1. Marks the header tokens by prefixing them with Control-A

2. Combines all the audit tokens for one record onto one line while preserving the line breaks as Control-A

3. Runs the grep command

4. Restores the original newline breaks

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

Note that the ^a in the script is Control-A, not the two characters ^ and a. The prefix distinguishes the header token from the string header that might appear as text.

The auditconfig Command

The auditconfig command provides a command-line interface to retrieve and set audit configuration parameters. The auditconfig command can do the following tasks:

• Display, check, and configure audit policy

• Determine if auditing is turned on or turned off

• Turn auditing off and turn auditing on

• Manage the audit directory and the audit file

• Manage the audit queue

• Get and set preselection masks

• Get and set audit event to audit class mappings

• Get and set configuration information, such as session ID and audit ID

• Configure audit characteristics for a process, a shell, and a session

• Reset audit statistics

See the auditconfig(1M) man page for a discussion of the command options.