Chapter 31 Solaris Auditing (Reference)

This chapter describes the important components of Solaris auditing. The following is a list of the reference information in this chapter.

• Audit Commands

• Files Used in the Auditing Service

• Rights Profiles for Administering Auditing

• Auditing and Solaris Zones

• Audit Classes

• Audit Plugins

• Audit Policy

• Process Audit Characteristics

• Audit Trail

• Conventions for Binary Audit File Names

• Audit Record Structure

• Audit Token Formats

For an overview of Solaris auditing, see Chapter 28, Solaris Auditing (Overview). For planning suggestions, see Chapter 29, Planning for Solaris Auditing. For procedures to configure auditing at your site, see Chapter 30, Managing Solaris Auditing (Tasks).

Audit Commands

This section provides information about the following commands:

• auditd Daemon

• audit Command

• bsmrecord Command

• auditreduce Command

• praudit Command

• auditconfig Command

auditd Daemon

The following list summarizes what the auditd daemon does.

• The auditd daemon opens and closes audit files in the directories that are specified in the audit_control file. The files are opened in order.

• The auditd daemon loads one or more plugins. Sun provides two plugins. The /lib/security/audit_binfile.so.1 plugin writes binary audit data to a file. The /lib/security audit_syslog.so.1 plugin sends text summaries of audit records to the syslogd daemon

• The auditd daemon reads audit data from the kernel and outputs the data by using an auditd plugin.

• The auditd daemon executes the audit_warn script to warn of configuration errors. The binfile.so.1 plugin executes the audit_warn script. The script, by default, sends warnings to the audit_warn email alias and to the console. The syslog.so.1 plugin does not execute the audit_warn script.

• By default, when all audit directories are full, processes that generate audit records are suspended. In addition, the auditd daemon writes a message to the console and to the audit_warn email alias. At this point, only the system administrator can fix the auditing service. The administrator can log in to write audit files to offline media, delete audit files from the system, and do other cleanup tasks.

  The audit policy can be reconfigured with the auditconfig command.

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

The auditd daemon uses the list of audit directories in the audit_control file as possible locations for creating audit files. The daemon maintains a pointer into this list of directories, starting with the first directory. Every time the auditd daemon needs to create an audit file, the daemon puts the file into the first available directory in the list. The list starts at the auditd 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.

audit Command

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

• Enable and disable auditing

• Reset the auditd daemon

• Adjust the auditing preselection mask on the local system

• Write audit records to a different audit file

For a discussion of the available options, see the audit(1M) man page.

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 audit tokens in order. With no option, the bsmrecord output displays in a terminal window. With the -h option, the output is suitable for viewing in a browser. For examples of the use of the bsmrecord command, see How to Display Audit Record Formats. Also, see the bsmrecord(1M) man page.

auditreduce Command

The auditreduce command summarizes audit records that are stored in binary format. The command can merge audit records from one or more input audit files. The command can also be used to perform a post selection of audit records. The records remain in binary format. To merge the entire audit trail, run this command on the audit server. The audit server is the system that mounts all the audit file systems for the installation. 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, /etc/security/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 file contains binary data.

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

With no arguments, the auditreduce command 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 31–1 illustrates audit data in separate directories for different hosts. Figure 31–2 illustrates audit data in separate directories for different audit servers.

Figure 31–1 Audit Trail Storage Sorted by Host

Figure 31–2 Audit Trail Storage Sorted by Server

If the partition for the /etc/security/audit directory 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 

For other options and more examples, see the auditreduce(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. 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 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 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 auditing service 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 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.

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

header,173,2,settppriv(2),,example1,2003-10-13 13:46:02.174 -07:00

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

121,173,2,289,0x0000,192.168.86.166,1066077962,174352445

Example 31–1 Processing praudit Output With a Script

You might want to process 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 the praudit command. 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.

#!/bin/sh
#
## This script takes an argument of a user-specified string.
#  The sed command prefixes the header tokens with Control-A
#  The first tr command puts the audit tokens for one record 
#  onto one line while preserving the line breaks as Control-A
#
praudit | sed -e '1,2d' -e '$s/^file.*$//' -e 's/^header/^aheader/' \\
| tr '\\012\\001' '\\002\\012' \\
| grep "$1" \\ Finds the user-specified string
| tr '\\002' '\\012' Restores the original newline breaks

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.

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

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

Files Used in the Auditing Service

The auditing service uses the following files:

• system File

• syslog.conf File

• audit_class File

• audit_control File

• audit_event File

• audit_startup Script

• audit_user Database

• audit_warn Script

• bsmconv Script

system File

The /etc/system file contains commands that the kernel reads during initialization to customize the system operations. The bsmconv and bsmunconv shell scripts, which are used to activate and deactivate auditing, modify the /etc/system file. The bsmconv shell script adds the following line to the /etc/system file:

set c2audit:audit_load=1

The set c2audit:audit_load=1 entry causes the kernel module for auditing to be loaded when the system is booted. The bsmunconv shell script disables auditing when the system is rebooted. The command removes the c2audit line from the /etc/system file.

syslog.conf File

The /etc/syslog.conf file works with the audit_control file to store audit records in text format. The syslog.conf file can be configured to enable the syslog utility to store audit records. For an example, see How to Configure syslog Audit Logs.

audit_class File

The /etc/security/audit_class file defines the audit classes. Audit classes are groups of audit events. You use the class name in the audit_control file to preselect the classes whose events you want to audit. The classes accept prefixes to select only failed events or only successful events. For more information, see Audit Class Syntax.

The superuser, or an administrator in an equivalent role, can modify the definitions of audit classes. This administrator can define new audit classes, rename existing classes, or otherwise change existing classes by editing the audit_class file in a text editor. For more information, see the audit_class(4) man page.

audit_control File

The /etc/security/audit_control file on each system contains configuration information for the auditd daemon. The file enables every system to mount a remote audit file system to store their audit records.

You can specify five kinds of information in the audit_control file. Each line of information begins with a keyword.

• flags keyword – Begins the entry that preselects which classes of events are audited for all users on the system. The audit classes that are specified here determine the system-wide audit preselection mask. The audit classes are separated by commas.

• naflags keyword – Begins the entry that preselects which classes of events are audited when an action cannot be attributed to a specific user. The audit classes are separated by commas. The na event class belongs in this entry. The naflags entry can be used to log other event classes that are normally attributable but cannot be attributed. For example, if a program that starts at boot reads a file, then an fr in the naflags entry would create a record for that event.

• minfree keyword – This keyword is deprecated. Use the p_minfree attribute to the audit_binfile.so plugin.

  The p_minfree attribute defines the minimum free-space level for all audit file systems as a percentage. The percentage must be equal to 0 or greater than 0. The default is 20 percent. When an audit file system is 80 percent full, the audit data is then stored in the next available audit directory. For more information, see the audit_warn(1M) man page.

• dir keyword – This keyword is deprecated. Use the p_dir attribute to the audit_binfile.so plugin.

  The p_dir attribute lists the directory locations. Each line value defines an audit file system and directory that the system uses to store its audit files. You can specify one or more directory locations. The order of the values is significant. The auditd daemon creates audit files in the directories in the specified order. The first directory is the primary audit directory for the system. The second directory is the secondary audit directory where the auditd daemon creates audit files when the first directory becomes full, and so on. For more information, see the audit(1M) man page.

• plugin keyword – Specifies the plugin path for the plugin modules audit_binfile.so and audit_syslog.so. The audit_binfile.so module handles the creation of binary audit files. The audit_syslog.so module provides real-time conversion of Solaris audit records to text. The audit classes that are specified in the p_flags attribute of the audit_syslog.so plugin must be a subset of the preselected audit classes.

For more information about the audit_control file, see the audit_control(4) man page. For information about the plugins, see Audit Plugins and the audit_binfile(5) and audit_syslog(5) man pages.

Example 31–2 Sample audit_control File

The following is a sample audit_control file for the system noddy. noddy uses two audit file systems on the audit server blinken, and a third audit file system that is mounted from the second audit server winken. The third file system is used only when the audit file systems on blinken become full or unavailable. The minfree value of 20 percent specifies that the warning script is run when the file systems are 80 percent full. The settings specify that logins and administrative operations are to be audited. The operations are audited for success and for failure. Failures of all types, except failures to create a file system object, are to be audited. Nonattributable events are also audited. The syslog audit log records fewer audit events. This log contains text summaries of failed logins and failed administrative operations.

In the Solaris 10 release, the dir and minfree lines are deprecated. In the following example, the plugin lines do not contain a line break.

flags:lo,am,-all,^-fc
naflags:lo,nt
plugin:name=audit_binfile.so; p_minfree=20; p_dir=/var/audit/blinken/files,
/var/audit/blinken.1/files,/var/audit/winken
plugin:name=audit_syslog.so; p_flags=-lo,-am

audit_event File

The /etc/security/audit_event file contains the default audit event-class mappings. You can edit this file to change the class mappings. When you change class mappings, you must reboot the system or run the auditconfig -conf command to read the changed mappings into the kernel. For more information, see the audit_event(4) man page.

audit_startup Script

The /etc/security/audit_startup script automatically configures the auditing service when the system enters multiuser mode. The auditd daemon starts after the script performs the following tasks:

• Configures the audit event-class mappings

• Sets the audit policy options

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

audit_user Database

The /etc/security/audit_user database modifies the system-wide preselected classes for an individual user. The classes that you add to a user's entry in the audit_user database modify the settings in the audit_control file in two ways:

• By specifying audit classes that are always to be audited for this user

• By specifying audit classes that are never to be audited for this user

Each user entry in the audit_user database contains three fields:

username:always-audit-classes:never-audit-classes

The audit fields are processed in sequence.

• The always-audit-classes field turns on the auditing of the classes in that field. Use this field to modify system-wide settings. For example, putting all in the always-audit-classes field audits everything for a user.

• The never-audit-classes field turns off the auditing of the classes in that field. Use this field to override system settings. Putting all in the never-audit-classes field turns off all auditing for the user, even the audit classes that are specified in the audit_control file.

Suppose that you want to apply the system-wide audit settings to the user tamiko, except for successful reads of file system objects. Note the placement of the second colon (:) in the following audit_user entry:

tamiko:^+fr:no  modify system defaults for fr

The preceding entry means, “always audit everything, except for successful file reads.”

If you want to audit everything for user tamiko with the exception of successful file reads, you use the following entry:

tamiko:all,^+fr:no  audit everything except fr

Suppose that you want to override system defaults for successful file-reads for user tamiko. The following entry means “always audit everything, but never audit successful file reads.”

tamiko:all:+fr    override system defaults for fr

Successful events and failed events are treated separately. A process could generate more audit records for failed events than for successful events.

audit_warn Script

The /etc/security/audit_warn script notifies an email alias when the auditd daemon 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 auditd daemon detects the following conditions, the daemon invokes the audit_warn script. The script sends email to the audit_warn alias.

• An audit directory has become more full than the minfree value allows. The minfree value or soft limit is a percentage of the available space on an audit file system.

  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 auditd daemon switches automatically to the next suitable directory. The daemon writes the audit files in this new directory until the directory reaches its minfree limit. The auditd daemon then goes to each remaining directory in the order that is listed in the audit_control file. The daemon writes audit records until each directory is at its minfree limit.

• All the audit directories have reached the minfree threshold.

  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_control file have reached their minfree threshold, the auditd daemon switches back to the first directory. The daemon 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_control file. 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. Processes that would otherwise generate audit records continue to occur, but audit records are counted. Audit records are not generated. For an example of how to handle this situation, see Example 30–16 and How to Prevent Audit Trail Overflow.

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

  • ebusy – Another auditd daemon process is already running

  • tmpfile – A temporary file cannot be used

  • postsigterm – A signal was received during auditing shutdown

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

• A problem is discovered with the syntax of the audit_control file. By default, a message is sent to the console. Email is also sent to the audit_warn alias.

If the perzone audit policy is set, the non-global zone's instance of auditd calls the zone's audit_warn script. For further information, see the audit_warn(1M) man page.

bsmconv Script

The /etc/security/bsmconv script enables the auditing service. The bsmunconv command disables the auditing service. After the bsmconv script is run, you configure the audit directories and audit configuration files. Upon reboot, auditing is enabled.

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

Rights Profiles for Administering Auditing

The Solaris OS provides rights profiles for configuring the auditing service and for analyzing the audit trail.

• Audit Control – Enables a role to configure Solaris auditing. This rights profile grants authorizations to configure files that are used by the auditing service. The profile also enables a role to run audit commands. A role with the Audit Control profile can run the following commands: audit, auditd, auditconfig, bsmconv, and bsmunconv.

• Audit Review – Enables a role to analyze Solaris audit records. This rights profile grants authorization to read audit records with the praudit and auditreduce commands. A role with this rights profile can also run the auditstat command.

• System Administrator – Includes the Audit Review rights profile. A role with the System Administrator rights profile can analyze audit records.

To configure roles to handle the auditing service, see Configuring RBAC (Task Map).

Auditing and Solaris Zones

Non-global zones can be audited exactly as the global zone is audited, or nonglobal zones can set their own flags, storage, and audit policy.

When all zones are being audited identically, the configuration files in the global zone provide the settings for auditing in every zone. The +zonename policy option is useful. When this option is set, the audit records from all zones include the name of the zone. Audit records can then be postselected by zone name. To understand audit policy, see Determining Audit Policy. For an example, see How to Configure Audit Policy.

Zones can also be audited individually. When the policy option, perzone, is set in the global zone, each non-global zone runs its own audit daemon, handles its own audit queue, and specifies the content and location of its audit records. A non-global zone can also set most audit policy options. It cannot set policy that affects the entire system, so a non-global zone cannot set the ahlt or perzone policy. For further discussion, see Auditing on a System With Zones and How to Plan Auditing in Zones.

To learn about zones, see Part II, Zones, in System Administration Guide: Solaris Containers-Resource Management and Solaris Zones.

Audit Classes

System-wide defaults for Solaris auditing are preselected by specifying one or more classes of events. The classes are preselected for each system in the system's audit_control file. Anyone who uses the system is audited for these classes of events. The file is described in audit_control File.

You can configure audit classes and make new audit classes. Audit class names can be up to 8 characters in length. The class description is limited to 72 characters. Numeric and non-alphanumeric characters are allowed.

You can modify what is audited for individual users by adding audit classes to a user's entry in the audit_user database. The audit classes are also used as arguments to the auditconfig command. For details, see the auditconfig(1M) man page.

Definitions of Audit Classes

The following table shows each predefined audit class, the descriptive name for each audit class, and a short description.

You can define new classes by modifying the /etc/security/audit_class file. You can also rename existing classes. For more information, see the audit_class(4) man page.

Audit Class Syntax

Events can be audited for success, events can be audited for failure, and events can be audited for both. Without a prefix, a class of events is audited for success and for failure. With a plus (+) prefix, a class of events is audited for success only. With a minus (-) prefix, a class of events is audited for failure only. The following table shows some possible representations of audit classes.

The all class can generate large amounts of data and quickly fill audit file systems. Use the all class only if you have extraordinary reasons to audit all activities.

Audit classes that were previously selected can be further modified by a caret prefix, ^. The following table shows how the caret prefix modifies a preselected audit class.

The audit classes and their prefixes can be used in the following files and commands:

• In the flags line in the audit_control file

• In the plugin:name=audit_syslog.so; p_flags= line in the audit_control file

• In the user's entry in the audit_user database

• As arguments to auditconfig command options

See audit_control File for an example of using the prefixes in the audit_control file.

Audit Plugins

Audit plugins specify how to handle the audit records in the audit queue. The audit plugins are specified by name in the audit_control file, audit_binfile.so and audit_syslog.so. The plugins and their attributes can specify the following:

• Where to send binary data, by using the audit_binfile.so plugin, p_dir attribute

• The minimum space remaining on a disk before the administrator is warned – audit_binfile.so plugin, p_minfree attribute

• The maximum size of an audit file, by using theaudit_binfile.so plugin, p_fsize attribute

  The p_fsize attribute plugin is available starting in the Solaris 10 10/08 release.

• A selection of audit records to be sent to syslog, by using theaudit_syslog.so plugin, p_flags attribute

• The maximum number of audit records that are queued for the plugin, by using theqsize attribute

Refer to the audit_binfile(5), audit_syslog(5), and audit_control(4) man pages.

Audit Policy

Audit policy determines if additional information is added to the audit trail.

The following policies add tokens to audit records: arge, argv, group, path, seq, trail, windata_down, windata_up, and zonename.

The remaining policies do not add tokens. The ahlt and cnt policies determine what happens when kernel audit records cannot be delivered, the public policy limits auditing of public files, and the perzone policy establishes separate audit queues for non-global zones.

The effects of the different audit policy options are described in Determining Audit Policy. For a description of audit policy options, see the -setpolicy option in the auditconfig(1M) man page. For a list of available policy options, run the auditconfig -lspolicy command.

Process Audit Characteristics

The following audit characteristics are set at initial login:

• Process preselection mask – A combination of the audit classes from the audit_control file and the audit_user database. When a user logs in, the login process combines the preselected classes to establish the process preselection mask for the user's processes. The process preselection mask specifies whether events in each audit class are to generate audit records.

  The following algorithm describes how the system obtains the user's process preselection mask:

  (flags line + always-audit-classes) - never-audit-classes

  Add the audit classes from the flags line in the audit_control file to the classes from the always-audit-classes field in the user's entry in the audit_user database. Then, subtract from the total the classes from the user's never-audit-classes field.

• Audit ID – A process acquires an audit ID when the user logs in. The audit ID is inherited by all child processes that were started by the user's initial process. The audit ID helps enforce accountability. Even after a user becomes root, the audit ID remains the same. The audit ID that is saved in each audit record always allows you to trace actions back to the original user who had logged in.

• Audit Session ID – The audit session ID is assigned at login. The session ID is inherited by all child processes.

• Terminal ID (port ID, machine ID) – The terminal ID consists of the host name and the Internet address, followed by a unique number that identifies the physical device on which the user logged in. Most often, the login is through the console. The number that corresponds to the console device is 0.

Audit Trail

The audit trail is contains binary audit files. The trail is created by the auditd daemon. Once the auditing service has been enabled with the bsmconv command, the auditd daemon starts when the system is booted. The auditd daemon is responsible for collecting the audit trail data and writing the audit records.

The audit records are stored in binary format on file systems that are dedicated to audit files. Even though you can physically locate audit directories within file systems that are not dedicated to auditing, do not do so except for directories of last resort. Directories of last resort are directories where audit files are written only when no other suitable directory is available.

There is one other scenario where locating audit directories outside of dedicated audit file systems could be acceptable. You might do so in a software development environment where auditing is optional. To make full use of disk space might be more important than to keep an audit trail. However, in a security-conscious environment, the placement of audit directories within other file systems is not acceptable.

You should also consider the following factors when administering audit file systems:

• A host should have at least one local audit directory. The local directory can be used as a directory of last resort if the host is unable to communicate with the audit server.

• Mount audit directories with the read-write (rw) option. When you mount audit directories remotely, also use the intr and noac options.

• List the audit file systems on the audit server where they reside. The export list should include all systems that are being audited at the site.

Conventions for Binary Audit File Names

Each binary audit file is a self-contained collection of records. The file's name identifies the time span during which the records were generated and the system that generated them.

Binary Audit File Names

Audit files that are complete have names of the following form:

start-time.end-time.system

start-time

Is the time that the first audit record in the audit file was generated

end-time

Is the time that the last record was written to the file

system

Is the name of the system that generated the file

An audit file that is still active has a name of the following form:

start-time.not_terminated.system

For examples of not_terminated and closed audit file names, see How to Clean Up a not_terminated Audit File.

Binary Audit File Timestamps

The timestamps in file names are used by the auditreduce command to locate records within a specific time range. These timestamps are important because there can be a month's accumulation or more of audit files online. To search all the files for records that were generated in the last 24 hours would be unacceptably expensive.

The start-time and end-time are timestamps with one-second resolution. They are specified in Greenwich Mean Time (GMT). The format is four digits for the year, followed by two digits for each month, day, hour, minute, and second, as follows:

YYYYMMDDHHMMSS

The timestamps are in GMT to ensure that they sort in proper order, even across time zones. Because they are in GMT, the date and hour must be translated to the current time zone to be meaningful. Beware of this point whenever you manipulate these files with standard file commands rather than with the auditreduce command.

Audit Record Structure

An audit record is a sequence of audit tokens. Each audit token contains event information such as user ID, time, and date. A header token begins an audit record, and an optional trailer token concludes the record. Other audit tokens contain information relevant to the audit event. The following figure shows a typical audit record.

Figure 31–3 Typical Audit Record Structure

Audit Record Analysis

Audit record analysis involves postselecting records from the audit trail. You can use one of two approaches to parsing the binary data that was collected.

• You can parse the binary data stream. To parse the data stream, you need to know the order of the fields in each token, and the order of tokens in each record. You also need to know the variants of an audit record. For example, the ioctl() system call creates an audit record for “Bad file name” that contains different tokens from the audit record for “Invalid file descriptor”.

  • For a description of the order of binary data in each audit token, see the audit.log(4) man page.

  • For a description of the order of tokens in an audit record, use the bsmrecord command. Output from the bsmrecord command includes the different formats that occur under different conditions. Square brackets ([]) indicate that an audit token is optional. For more information, see the bsmrecord(1M) man page. For examples, see also How to Display Audit Record Formats.

• You can use the praudit command. Options to the command provide different text outputs. For example, the praudit -x command provides XML for input into scripts and browsers. praudit outputs do not include fields whose sole purpose is to help to parse the binary data. The outputs do not necessarily follow the order of the binary fields. Also, the order and format of praudit output is not guaranteed between Solaris releases.

  For examples of praudit output, see How to View the Contents of Binary Audit Files, and the praudit(1M) man page.

  For a description of the praudit output for each audit token, see the individual tokens in the Audit Token Formats section.

Audit Token Formats

Each audit token has a token type identifier, which is followed by data that is specific to the token. Each token type has its own format. The following table shows the token names with a brief description of each token. Obsolete tokens are maintained for compatibility with previous Solaris releases.

An audit record always begins with a header token. The header token indicates where the audit record begins in the audit trail. In the case of attributable events, the subject and the process tokens refer to the values of the process that caused the event. In the case of nonattributable events, the process token refers to the system.

acl Token

The acl token records information about Access Control Lists (ACLs).

The acl token consists of four fixed fields:

• A token ID that identifies this token as an acl token

• A field that specifies the ACL type

• An ACL value field

• A field that lists the permissions associated with this ACL

The praudit -x command shows the fields of the acl token:

<acl type="1" value="root" mode="6"/>

arbitrary Token (Obsolete)

The arbitrary token encapsulates data for the audit trail. This token consists of four fixed fields and an array of data. The fixed fields are as follows:

• A token ID that identifies this token as an arbitrary token

• A suggested print format field, such as hexadecimal

• An item size field that specifies the size of the data that is encapsulated, such as short

• A count field that provides the number of following items

The remainder of the token is composed of count of the specified type. The praudit command displays the arbitrary token as follows:

arbitrary,decimal,int,1
42

The following table shows the possible values of the print format field.

The following table shows the possible values of the item size field.

arg Token

The arg token contains information about the arguments to a system call: the argument number of the system call, the argument value, and an optional description. This token allows a 32-bit integer system-call argument in an audit record.

The arg token has five fields:

• A token ID that identifies this token as an arg token

• An argument ID that tells which system call argument that the token refers to

• The argument value

• The length of the descriptive text string

• The text string

The praudit -x command shows the fields of the arg token:

<argument arg-num="2" value="0x0" desc="new file uid"/>

attribute Token

The attribute token contains information from the file vnode.

The attribute token has seven fields:

• A token ID that identifies this token as an attribute token

• The file access mode and type

• The owner user ID

• The owner group ID

• The file system ID

• The node ID

• The device ID that the file might represent

For further information about the file system ID and the device ID, see the statvfs(2) man page.

The attribute token usually accompanies a path token. The attribute token is produced during path searches. If a path-search error occurs, there is no vnode available to obtain the necessary file information. Therefore, the attribute token is not included as part of the audit record. The praudit -x command shows the fields of the attribute token:

<attribute mode="100644" uid="adm" gid="adm" fsid="136" nodeid="2040" device="0"/>

cmd Token

The cmd token records the list of arguments and the list of environment variables that are associated with a command.

The cmd token contains the following fields:

• A token ID that identifies this token as a cmd token

• A count of the command's arguments

• The argument list

• The length of the next field

• The content of the arguments

• A count of the environment variables

• The list of environment variables

• The length of the next field

• The content of the environment variables

The praudit -x command shows the fields of the cmd token. The following is a truncated cmd token. The line is wrapped for display purposes.

<cmd><arge>WINDOWID=6823679</arge>
<arge>COLORTERM=gnome-terminal</arge>
<arge>...LANG=C</arge>...<arge>HOST=machine1</arge>
<arge>LPDEST=printer1</arge>...</cmd>

exec_args Token

The exec_args token records the arguments to an exec() system call. The exec_args token has two fixed fields:

• A token ID field that identifies this token as an exec_args token

• A count that represents the number of arguments that are passed to the exec() system call

The remainder of this token is composed of count strings. The praudit -x command shows the fields of the exec_args token:

<exec_args><arg>/usr/bin/sh</arg><arg>/usr/bin/hostname</arg></exec_args>

The exec_args token is output only when the argv audit policy option is active.

exec_env Token

The exec_env token records the current environment variables to an exec() system call. The exec_env token has two fixed fields:

• A token ID field that identifies this token as an exec_env token

• A count that represents the number of arguments that are passed to the exec() system call

The remainder of this token is composed of count strings. The praudit -x command shows the fields of the exec_env token. The line is wrapped for display purposes.

<exec_env><env>_=/usr/bin/hostname</env>
<env>DTXSERVERLOCATION=local</env><env>SESSIONTYPE=altDt</env>
<env>LANG=C</env><env>SDT_NO_TOOLTALK=1</env><env>SDT_ALT_HELLO=/bin/true</env>
<env>PATH=/usr/bin:/usr/openwin/bin:/usr/ucb</env>
<env>OPENWINHOME=/usr/openwin</env><env>LOGNAME=jdoe</env><env>USER=jdoe</env>
<env>DISPLAY=:0</env><env>SHELL=/bin/csh</env><env>START_SPECKEYSD=no</env>
<env>SDT_ALT_SESSION=/usr/dt/config/Xsession2.jds</env><env>HOME=/home/jdoe</env>
<env>SDT_NO_DTDBCACHE=1</env><env>PWD=/home/jdoe</env><env>TZ=US/Pacific</env>
</exec_env>

The exec_env token is output only when the arge audit policy option is active.

exit Token (Obsolete)

The exit token records the exit status of a program. The exit token contains the following fields:

• A token ID that identifies this token as an exit token

• A program exit status as passed to the exit() system call

• A return value that describes the exit status or that provides a system error number

The praudit command displays the exit token as follows:

exit,Error 0,0

file Token

The file token is a special token that is generated by the auditd daemon. The token marks the beginning of a new audit file and the end of an old audit file as the old file is deactivated. The initial file token identifies the previous file in the audit trail. The final file token identifies the next file in the audit trail. The auditd daemon builds a special audit record that contains this token to “link” together successive audit files into one audit trail.

The praudit -x command shows the fields of the file token. This token identifies the next file in the audit trail. The line is wrapped for display purposes.

<file iso8601="2009-04-08 14:18:26.200 -07:00">
/var/audit/machine1/files/20090408211826.not_terminated.machine1</file>

group Token (Obsolete)

This token has been replaced by the the groups token. See groups Token.

groups Token

The groups token replaces the group token. The groups token records the group entries from the process's credential.

The groups token has two fixed fields:

• A token ID field that identifies this token as a groups token

• A count that represents the number of groups that are contained in this audit record

The remainder of this token is composed of count group entries.

The praudit -x command shows the fields of the groups token:

<group><gid>staff</gid><gid>other</gid></group>

The groups token is output only when the group audit policy option is active.

header Token

The header token is special in that it marks the beginning of an audit record. The header token combines with the trailer token to bracket all the other tokens in the record.

The header token has eight fields:

• A token ID field that identifies this token as a header token

• A byte count of the total length of the audit record, including both the header and the trailer tokens

• A version number that identifies the version of the audit record structure

• The audit event ID that identifies the audit event that the record represents

• The ID modifier that identifies special characteristics of the audit event

  The ID modifier field has the following flags defined:

  0x4000 PAD_NOTATTR nonattributable event 0x8000 PAD_FAILURE failed audit event

• The address type, either IPv4 or IPv6

• The machine's IP address

• The time and date that the record was created

On 64-bit systems, the header token is displayed with a 64-bit timestamp, in place of the 32-bit timestamp.

The praudit command displays the header token as follows:

header,69,2,su,,machine1,2009-04-08 13:11:58.209 -07:00

The praudit -x command displays the fields of the header token at the beginning of the audit record. The line is wrapped for display purposes.

<record version="2" event="su" host="machine1" 
iso8601="2009-04-08 13:11:58.209 -07:00">

in_addr Token

The in_addr token contains an Internet Protocol address. Since the Solaris 8 release, the Internet address can be displayed in IPv4 format or IPv6 format. The IPv4 address uses 4 bytes. The IPv6 address uses 1 byte to describe the address type, and 16 bytes to describe the address.

The in_addr token has three fields:

• A token ID that identifies this token as an in_addr token

• The IP address type, either IPv4 or IPv6

• An IP address

The praudit -x command shows the content of the in_addr token:

<ip_address>machine1</ip_address>

ip Token (Obsolete)

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

• A token ID that identifies this token as an ip token

• A copy of the IP header, that is, all 20 bytes

The praudit command displays the ip token as follows:

ip address,0.0.0.0

The IP header structure is defined in the /usr/include/netinet/ip.h file.

ipc Token

The ipc token contains the System V IPC message handle, semaphore handle, or shared-memory handle that is used by the caller to identify a particular IPC object.

The ipc token has three fields:

• A token ID that identifies this token as an ipc token

• A type field that specifies the type of IPC object

• The handle that identifies the IPC object

The IPC object identifiers violate the context-free nature of the Solaris audit tokens. No global “name” uniquely identifies IPC objects. Instead, IPC objects are identified by their handles. The handles are valid only during the time that the IPC objects are active. However, the identification of IPC objects should not be a problem. The System V IPC mechanisms are seldom used, and the mechanisms all share the same audit class.

The following table shows the possible values for the IPC object type field. The values are defined in the /usr/include/bsm/audit.h file.

The praudit -x command shows the fields of the ipc token:

<IPC ipc-type="shm" ipc-id="15"/>

ipc_perm Token

The ipc_perm token contains a copy of the System V IPC access permissions. This token is added to audit records that are generated by IPC shared-memory events, IPC semaphore events, and IPC message events.

The ipc_perm token has eight fields:

• A token ID that identifies this token as an ipc_perm token

• The user ID of the IPC owner

• The group ID of the IPC owner

• The user ID of the IPC creator

• The group ID of the IPC creator

• The access mode of the IPC

• The sequence number of the IPC

• The IPC key value

The praudit -x command shows the fields of the ipc_perm token. The line is wrapped for display purposes.

<IPC_perm uid="jdoe" gid="staff" creator-uid="jdoe" 
creator-gid="staff" mode="100600" seq="0" key="0x0"/>

The values are taken from the ipc_perm structure that is associated with the IPC object.

iport Token

The iport token contains the TCP or UDP port address.

The iport token has two fields:

• A token ID that identifies this token as an iport token

• The TCP or UDP port address

The praudit command displays the iport token as follows:

ip port,0xf6d6

opaque Token (Obsolete)

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

• A token ID that identifies this token as an opaque token

• A byte count of the data

• An array of byte data

The praudit command displays the opaque token as follows:

opaque,12,0x4f5041515545204441544100

path Token

The path token contains access path information for an object.

The path token contains the following fields:

• A token ID that identifies this token as an path token

• The path length

• The absolute path to the object that is based on the real root of the system

The praudit command displays the path token, without the second field, as follows:

path,/etc/security/audit_user

The praudit -x command shows the content of the path token:

<path>/etc/security/audit_user</path>

The following figure shows the format of a path token.

Figure 31–4 path Token Format

path_attr Token

The path_attr token contains access path information for an object. The access path specifies the sequence of attribute file objects below the path token object. Systems calls such as openat() access attribute files. For more information on attribute file objects, see the fsattr(5) man page.

The path_attr token contains the following fields:

• A token ID that identifies this token as a path_attr token

• A count that represents the number of sections of attribute file paths

• count null-terminated strings

The praudit command displays the path_attr token as follows:

path_attr,1,attr_file_name

privilege Token

The privilege token records the use of privileges on a process. The privilege token is not recorded for privileges in the basic set. If a privilege has been removed from the basic set by administrative action, then the use of that privilege is recorded. For more information on privileges, see Privileges (Overview)

The privilege token contains the following fields:

• A token ID that identifies this token as a privilege token

• The length of the following field

• The name of privilege set

• The length of the following field

• The list of privileges

The praudit -x command shows the fields of the privilege token. The line is wrapped for display purposes.

<privilege set-type="Effective">file_chown,file_dac_read,
file_dac_write,net_privaddr,proc_exec,proc_fork,proc_setid</privilege>

process Token

The process token contains information about a user who is associated with a process, such as the recipient of a signal.

The process token has nine fields:

• A token ID that identifies this token as a process token

• The audit ID

• The effective user ID

• The effective group ID

• The real user ID

• The real group ID

• The process ID

• The audit session ID

• A terminal ID that consists of a device ID and a machine ID

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The process token fields for the session ID, the real user ID, or the real group ID might be unavailable. The value is then set to -1.

Any token that contains a terminal ID has several variations. The praudit command hides these variations. So, the terminal ID is handled the same way for any token that contains a terminal ID. The terminal ID is either an IP address and port number, or a device ID. A device ID, such as the serial port that is connected to a modem, can be zero. The terminal ID is specified in one of several formats.

The terminal ID for device numbers is specified as follows:

• 32-bit applications – 4-byte device number, 4 bytes unused

• 64-bit applications – 8-byte device number, 4 bytes unused

In releases prior to the Solaris 8 release, the terminal ID for port numbers is specified as follows:

• 32-bit applications – 4-byte port number, 4-byte IP address

• 64-bit applications – 8-byte port number, 4-byte IP address

Since the Solaris 8 release, the terminal ID for port numbers is specified as follows:

• 32-bit with IPv4 – 4-byte port number, 4-byte IP type, 4-byte IP address

• 32-bit with IPv6 – 4-byte port number, 4-byte IP type, 16-byte IP address

• 64-bit with IPv4 – 8-byte port number, 4-byte IP type, 4-byte IP address

• 64-bit with IPv6 – 8-byte port number, 4-byte IP type, 16-byte IP address

The praudit -x command shows the fields of the process token. The line is wrapped for display purposes.

<process audit-uid="-2" uid="root" gid="root" ruid="root" 
rgid="root" pid="9" sid="0" tid="0 0 0.0.0.0"/>

The following figure shows the format of a process token.

Figure 31–5 process Token Format

return Token

The return token contains the return status of the system call (u_error) and the process return value (u_rval1).

The return token has three fields:

• A token ID that identifies this token as a return token

• The error status of the system call

• The return value of the system call

The return token is always returned as part of kernel-generated audit records for system calls. In application auditing, this token indicates exit status and other return values.

The praudit command displays the return token for a system call as follows:

return,failure: Operation now in progress,-1

The praudit -x command shows the fields of the return token:

<return errval="failure: Operation now in progress" retval="-1/">

sequence Token

The sequence token contains a sequence number. The sequence number is incremented every time an audit record is added to the audit trail. This token is useful for debugging.

The sequence token has two fields:

• A token ID that identifies this token as a sequence token

• A 32-bit unsigned long field that contains the sequence number

The praudit command shows the field of the sequence token:

sequence,1292

The praudit -x command shows the content of the sequence token:

<sequence seq-num="1292"/>

The sequence token is output only when the seq audit policy option is active.

socket Token

The socket token contains information that describes an Internet socket. In some instances, the token has four fields:

• A token ID that identifies this token as a socket token

• A socket type field that indicates the type of socket referenced, either TCP, UDP, or UNIX

• The local port

• The local IP address

The praudit command displays this instance of the socket token as follows:

socket,0x0002,0x83b1,localhost

In most instances, the token has eight fields:

• A token ID that identifies this token as a socket token

• The socket domain

• A socket type field that indicates the type of socket referenced, either TCP, UDP, or UNIX

• The local port

• The address type, either IPv4 or IPv6

• The local IP address

• The remote port

• The remote IP address

Since the Solaris 8 release, the Internet address can be displayed in IPv4 format or IPv6 format. The IPv4 address uses 4 bytes. The IPv6 address uses 1 byte to describe the address type, and 16 bytes to describe the address.

The praudit command displays the socket token as follows:

socket,0x0002,0x0002,0x83cf,example1,0x2383,server1.Subdomain.Domain.COM

The praudit -x command shows the fields of the socket token. The line is wrapped for display purposes.

<socket sock_domain="0x0002" sock_type="0x0002" lport="0x83cf" 
laddr="example1" fport="0x2383" faddr="server1.Subdomain.Domain.COM"/>

subject Token

The subject token describes a user who performs or attempts to perform an operation. The format is the same as the process token.

The subject token has nine fields:

• A token ID that identifies this token as a subject token

• The audit ID

• The effective user ID

• The effective group ID

• The real user ID

• The real group ID

• The process ID

• The audit session ID

• A terminal ID that consists of a device ID and a machine ID

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The subject token fields for the session ID, the real user ID, or the real group ID might be unavailable. The value is then set to -1.

Any token that contains a terminal ID has several variations. The praudit command hides these variations. So, the terminal ID is handled the same way for any token that contains a terminal ID. The terminal ID is either an IP address and port number, or a device ID. A device ID, such as the serial port that is connected to a modem, can be zero. The terminal ID is specified in one of several formats.

The terminal ID for device numbers is specified as follows:

• 32-bit applications – 4-byte device number, 4 bytes unused

• 64-bit applications – 8-byte device number, 4 bytes unused

In releases prior to the Solaris 8 release, the terminal ID for port numbers is specified as follows:

• 32-bit applications – 4-byte port number, 4-byte IP address

• 64-bit applications – 8-byte port number, 4-byte IP address

Since the Solaris 8 release, the terminal ID for port numbers is specified as follows:

• 32-bit with IPv4 – 4-byte port number, 4-byte IP type, 4-byte IP address

• 32-bit with IPv6 – 4-byte port number, 4-byte IP type, 16-byte IP address

• 64-bit with IPv4 – 8-byte port number, 4-byte IP type, 4-byte IP address

• 64-bit with IPv6 – 8-byte port number, 4-byte IP type, 16-byte IP address

The subject token is always returned as part of kernel-generated audit records for system calls. The praudit command displays the subject token as follows:

subject,jdoe,root,root,root,root,1631,1421584480,8243 65558 machine1

The praudit -x command shows the fields of the subject token. The line is wrapped for display purposes.

<subject audit-uid="jdoe" uid="root" gid="root" ruid="root" 
rgid="root" pid="1631" sid="1421584480" tid="8243 65558 machine1"/>

The following figure shows the format of the subject token.

Figure 31–6 subject Token Format

text Token

The text token contains a text string.

The text token has three fields:

• A token ID that identifies this token as a text token

• The length of the text string

• The text string itself

The praudit -x command shows the content of the text token:

<text>booting kernel</text>

trailer Token

The two tokens, header and trailer, are special in that they distinguish the end points of an audit record and bracket all the other tokens. A header token begins an audit record. A trailer token ends an audit record. The trailer token is an optional token. The trailer token is added as the last token of each record only when the trail audit policy option has been set.

When an audit record is generated with trailers turned on, the auditreduce command can verify that the trailer correctly points back to the record header. The trailer token supports backward seeks of the audit trail.

The trailer token has three fields:

• A token ID that identifies this token as a trailer token

• A pad number to aid in marking the end of the record

• The total number of characters in the audit record, including both the header and trailer tokens

The praudit command displays the trailer token as follows:

trailer,136

uauth Token

The uauth token records the use of authorization with a command or action.

The uauth token contains the following fields:

• A token ID that identifies this token as a uauth token

• The length of the text in the following field

• A list of authorizations

The praudit command displays the uauth token as follows:

use of authorization,solaris.admin.printer.delete

upriv Token

The upriv token records the use of privilege with a command or action.

The praudit -x command shows the fields of the upriv token:

<use_of_privilege result="successful use of priv">proc_setid</use_of_privilege>

zonename Token

The zonename token records the zone in which the audit event occurred. The string “global” indicates audit events that occur in the global zone.

The zonename token contains the following fields:

• A token ID that identifies this token as a zonename token

• The length of the text in the following field

• The name of the zone

The praudit -x command shows the content of the zonename token:

<zone name="graphzone"/>