Audit Commands

This section provides information about the following commands and scripts:

• audit Command

• audit_warn Script

• auditconfig Command

• auditrecord Command

• auditreduce Command

• auditstat Command

• praudit Command

audit Command

The audit command controls the actions of the audit service. The audit service is enabled and refreshed with the audit -s command and disabled with the audit -t command. The audit -n command is used to start a new audit file for the audit_binfile plugin.

For more information, see the audit(1M) man page.

audit_warn Script

The /etc/security/audit_warn script notifies an email alias when the audit service encounters an unusual condition while writing audit records. You can customize this script for your site to warn of conditions that might require manual intervention. Or, you could specify how to handle those conditions automatically.

For all error conditions, the audit_warn script writes a message to syslog with the severity of daemon.alert. You can use syslog.conf to configure console display of syslog messages.

The audit_warn script also sends a message to the audit_warn email alias. You set up this alias as part of audit configuration.

When the audit service detects the following local conditions, the service invokes the audit_warn script. The script sends email to the audit_warn alias.

• An internal error occurs. Possible internal errors include the following:

  • tmpfile – A temporary file cannot be used

  • plugin name – An error occurred during execution of the name plugin

• For the audit_binfile plugin, the audit service detects the following conditions:

  • An audit directory has become more full than the p_minfree value allows. This soft limit is a percentage of the available space on the file system that holds the audit files.

    The audit_warn script is invoked with the string soft and the name of the directory whose available space is below the minimum value. The audit service automatically switches to the next suitable directory. The service writes the audit files in this new directory until the directory reaches its soft limit. The service then goes to each remaining directory in the order that is listed for the audit_binfile plugin. The plugin writes audit records until each directory reaches its soft limit.

  • All the audit directories have reached the soft limit.

    The audit_warn script is invoked with the string allsoft. A message is written to the console. Email is also sent to the audit_warn alias.

    When all audit directories that are listed in the audit service have reached their soft limit, the audit service switches back to the first directory. The audit_binfile plugin writes audit records until the directory becomes completely full.

  • An audit directory has become completely full with no space remaining.

    The audit_warn script is invoked with the string hard and the name of the directory. A message is written to the console. Email is also sent to the audit_warn alias.

    The auditd daemon switches automatically to the next suitable directory with any space available. The auditd daemon goes to each remaining directory in the order that is listed in the audit service. The daemon writes audit records until each directory is full.

  • All the audit directories are completely full. The audit_warn script is invoked with the string allhard as an argument.

    By default, a message is written to the console. Email is also sent to the audit_warn alias. By default audit policy, processes that would otherwise generate audit records continue to occur, but audit records are counted. Audit records are not generated. For alternative policy settings, see Audit Policies for Asynchronous and Synchronous Events. For an example of how to handle this situation, see Example 30-6 and How to Prevent Audit Trail Overflow.

For further information, see the audit_warn(1M) man page.

auditconfig Command

The auditconfig command retrieves and sets audit configuration parameters. The auditconfig command can do the following tasks:

• Determine if auditing is turned on or turned off

• Display and configure audit policy

• Get and set preselection masks

• Get and set plugin values

• Set audit directories for the audit_binfile plugin

• Manage the audit queue

• Verify audit event to audit class mappings

• Get and set audit parameters, such as session ID and audit ID

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

• Display and reset audit statistics

For a description of the command options, see the auditconfig(1M) man page.

auditrecord Command

The auditrecord command displays the definition of audit events in the /etc/security/audit_event file. The output includes the event's ID, audit class, and the record's audit tokens in order. For examples, see How to Display Audit Record Definitions. Also, see the auditrecord(1M) man page.

auditreduce Command

The auditreduce command post-selects and merges audit records that are stored in binary format. The command can merge audit records from one or more input audit files. The records remain in binary format. For more information, see the auditreduce(1M) man page.

The auditreduce command enables you to track all audited actions on multiple systems 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 systems at a site for auditing, and create servers and local directories for the audit files. The auditreduce command ignores how the records were generated or where the records 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, /var/audit is the audit root directory. The auditreduce command sends the merged results to standard output. You can also place the results into a single, chronologically ordered output file.

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

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

• Request audit records that were generated by specified audit classes

• Request audit records that were generated by one particular user

• Request audit records that were generated on specific dates

For a full list of options, see the auditreduce(1M) man page.

With no arguments, the auditreduce command checks the subdirectories within the /var/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 31-1 illustrates audit data in separate directories for different hosts.

Figure 31-1 Audit Trail Storage Sorted by Host

If the file system for the /var/audit directory is not used to store audit data, 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 

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

auditstat Command

The auditstat command displays kernel audit statistics. For example, the command can display the number of records in the kernel audit queue, the number of dropped records, and the number of audit records that user processes produced in the kernel as a result of system calls. For a description of the available options, see the auditstat(1M) man page.

praudit Command

The praudit command makes the binary output of the auditreduce command readable. 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 or a list of audit files. Input can also be produced with the tail -0f command for a current audit file.

The praudit command can generate four output formats. A fifth option, -l (long), prints one audit record per line of output. The default is to place one audit token per line of output. The -d option changes the delimiter that is used between token fields and between tokens. The default delimiter is a comma.

• Default – The praudit command with no options displays one audit token per line. The command displays the audit event by its description, such as the ioctl(2) system call. Any value that can be displayed as text is displayed in text format. For example, a user is displayed as the user name, not as the user ID.

• –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 numeric 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 service provides. Oracle 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 the praudit command, each record is easily identified as a sequence of audit tokens. Each token is presented on a separate line. Each record begins with a header token. You could, for example, further process the output with the awk command, as in Example 30-35. For sample output, see How to View the Contents of Binary Audit Files.