Part IV Auditing and Device Management

Chapter 20 BSM (Overview)

The Basic Security Module (BSM) provides two security features. The first feature is an auditing mechanism, which includes tools to assist with the analysis of the auditing data. The second feature is a device-allocation mechanism, which provides the required object-reuse characteristics for removable devices or assignable devices.

This chapter introduces the concepts behind BSM. The following is a list of the information in this chapter.

• What Is Auditing?

• How Does Auditing Work?

• How Is Auditing Related to Security?

• BSM Terminology

• Device Allocation

What Is Auditing?

Auditing is the collection of data about the use of machine resources. The audit data provides a record of security-related system events. This data can then be used to assign responsibility to actions that take place on a host. Successful auditing starts with two security features: identification and authentication. At login, after a user supplies a user name and password, a unique audit ID is associated with the user's process. The audit ID is inherited by every process that is started during the login session. Even if a user changes identity, all user actions are tracked with the same audit ID. See the su(1M) man page.

The auditing subsystem makes the following possible:

• Monitor security-relevant events that take place on the host

• Record the events in a network-wide audit trail

• Detect misuse or unauthorized activity

• Review patterns of access, and see the access histories of individuals and objects

• Discover attempts to bypass the protection mechanisms

• Discover which users are using root capabilities

During system configuration, you select which activities to monitor. You can also fine-tune the degree of auditing that is done for individual users.

After audit data is collected, audit-reduction and interpretation tools allow you to examine interesting parts of the audit trail. For example, you can choose to review audit records for individual users or specific groups. You can examine all records for a certain type of event on a specific day. Or you can select records that were generated at a certain time of day.

How Does Auditing Work?

Auditing is the generation of audit records when specified events occur. Most commonly, events that generate audit records include the following:

• System startup and system shutdown

• Login and logout

• Process creation or process destruction, or thread creation or thread destruction

• Opening, closing, creating, destroying, or renaming of objects

• Use of root capabilities or role capabilities

• Identification, and authentication actions

• Discretionary Access Control (DAC) changes by a process or user

• Installation-specific administrative actions

Audit records are generated from three sources:

• By an application

• As a result of an asynchronous event

• As a result of a process system call

Once the relevant event information has been captured, the information is formatted into an audit record. The record is then placed in a kernel buffer known as the audit queue. From this temporary location within the kernel, audit records are written to audit files. Where the audit files are located is determined by entries in the audit_control file. The location can include multiple partitions on the same machine, partitions on different machines, or partitions on machines on different but linked networks. The collection of audit files that are linked together is considered an audit trail.

Audit records accumulate in audit files chronologically. Contained in each audit record is information that identifies the event, what caused the event, the time of the event, and other relevant information.

How Is Auditing Related to Security?

To secure a computer system, especially a system on a network, is complex. Security requires mechanisms that control activities before system processes or user processes begin. Security requires tools that monitor activities as the activities occur. Security also requires reports of activities after the activities have happened. Initial configuration of Solaris auditing requires that parameters be set before users log in or machine processes begin. Most auditing activities involve monitoring current events and reporting those events that meet the specified parameters. How Solaris auditing monitors and reports these events is discussed in detail in Chapter 21, Audit Planning and Chapter 22, Managing the BSM Service (Tasks).

Auditing cannot prevent hackers from unauthorized entry. However, the audit subsystem can report, for example, that a specific user performed specific actions at a specific time and date. The audit report can identify the user by entry path and user name. Such information can be reported immediately to your terminal and to a file for later analysis. Thus, the audit subsystem provides data that helps you determine the following:

• How system security was compromised

• What loopholes need to be closed to ensure the desired level of security

BSM Terminology

The following terms are used to describe the BSM service. Some definitions include pointers to more complete descriptions.

Audit Events

Security-relevant system actions can be audited. These auditable actions are defined as audit events. Audit events are listed in the /etc/security/audit_event file. Each auditable event is defined in the file by a symbolic name, an event number, a set of preselection classes, and a short description. See the audit_event(4) man page.

There are several categories of audit events. The primary distinction is between kernel-level events and user-level events. Events that are generated by the kernel are called kernel-level events. Events that are generated by applications are called user-level events. Kernel-level events have a lower audit event number than a user-level event, as shown in the following table.

Kernel-Level Audit Events

Events that are generated by the kernel are system calls. System calls have audit event numbers between 1 and 2047. The event names for kernel events begin with AUE_, followed by an uppercase mnemonic for the event. For example, the event number for the creat() system call is 4, and the event name is AUE_CREAT.

User-Level Audit Events

Events that are generated by application software are outside the kernel. Application software generates user-level events. User-level events range in number from 2048 to 65535. The event names begin with AUE_, followed by a lowercase mnemonic for the event. For example, the event number for the rlogin command is 6155, and the event name is AUE_rlogin. Table 20–2 shows general categories of user-related events.

Nonattributable Audit Events

Most events are attributable to an individual user, but some events are not. Events are nonattributable if the events occur at the kernel-interrupt level, or if the events occur before a user is identified and authenticated. Nonattributable events are auditable. The following example lists two nonattributable events from the /etc/security/audit_event file:

153:AUE_ENTERPROM:enter prom:na
6156:AUE_mountd_mount:mount:na

AUE_ENTERPROM is a kernel-level na event. AUE_mountd_mount is a user-level na event.

Audit Classes

Each audit event is also defined as belonging to an audit class or classes. Audit classes are convenient containers for large numbers of audit events. When you preselect a class to be audited, you preselect for auditing all the events in that class. Audit classes are defined in the /etc/security/audit_class file. Each entry contains the name of the class, its audit mask, and its short name.

0x00000010:fc:file create
0x00000400:na:non-attribute

The mapping of audit events to classes is configurable. These configuration changes are made in the audit_event file.

An auditable event is recorded in the audit trail when you preselect an audit class for auditing that includes the specific event. There are 32 possible audit classes. The classes include the two global classes: all and no. The audit classes are described in Table 23–1. See also the audit_class(4) man page.

Audit Flags

Audit flags are the short names for audit classes. Audit flags are used in the audit_control file to specify machine-wide defaults for auditing on the machine. The audit_control file is described in The audit_control File.

You can make exceptions to the machine-wide auditing defaults for individual users. You put audit flags in a user's entry in the audit_user file. The audit flags are also used as arguments to the auditconfig command. See the auditconfig(1M) and audit_user(4) man pages.

Audit Records and Audit Tokens

Each audit record describes the occurrence of a single audited event. The record includes information such as who did the action, which files were affected, what action was attempted, and where and when the action occurred. For example, the following line shows an audit record when processed by the praudit command:

header,81,2,login - local,,Mon May  6 16:55:48 PDT 2002, + 486 msec
subject,root,root,other,root,other,378,378,0 0 example_machine
text,successful login
return,success,0

Audit records are collected in an audit file. The set of audit files from a machine or site is called the audit trail. For a description of how audit files are handled, see the audit.log(4) man page. Audit records can be converted to a readable format by the praudit command. For examples of praudit output, see The praudit Command. See also the praudit(1M) man page.

The type of information that is saved for each audit event is defined in a set of audit tokens. Each time an audit record is created for an event, the record contains some or all of the tokens that are defined for the event. The nature of the event determines which tokens are recorded. You can generate audit record descriptions with the bsmrecord command. The following output shows the structure of the audit record that is generated when the creat() system call is used. The lines beginning with header are the audit tokens.

creat
  system call creat                see creat(2)
  event ID    4                    AUE_CREAT
  class       fc                   (0x00000010)
      header
      path
      [attribute]
      subject
      return

For more information, see How to Display Audit Record Formats. For a description of the structure of each audit token, see Audit Token Formats. The audit.log(4) man page also lists the audit tokens.

Audit Directory

An audit directory holds a collection of audit files. A typical installation uses many audit directories. The three types of audit directories are as follows:

• Primary audit directory – A directory where the audit files for a system are placed under normal conditions.

• Secondary audit directory – A directory where the audit files for a system are placed if the primary directory is full or not available.

• Directory of last resort – A local audit directory that is used if the primary audit directory and all secondary audit directories are not available.

Device Allocation

The device-allocation mechanism enables you to restrict access to a device, such as a CD-ROM. Device clean scripts erase any leftover data after a device has been used. These actions increase the security of a device. For more information, see Managing Device Allocation (Tasks) or Device Allocation Reference.

Chapter 21 Audit Planning

This chapter describes how to set up auditing for your Solaris installation. In particular, the chapter covers issues that you need to consider before you enable the auditing service. The following is a list of the planning information in this chapter:

• Handling the Audit Trail

• Deciding Who and What to Audit

• Determining Which Audit Policies to Use

• Controlling Auditing Costs

• Auditing Efficiently

For an overview of auditing, see Chapter 20, BSM (Overview). For procedures to configure auditing at your site, see Chapter 22, Managing the BSM Service (Tasks).

Handling the Audit Trail

File space for the audit trail is one of the biggest issues with auditing. Each host should have several audit directories that are configured for audit files. You should decide how to configure the audit directories as one of the first steps before you enable auditing on any hosts. The following table lists the issues that should be resolved when you plan for audit trail storage.

Deciding Who and What to Audit

You want to be selective about what kinds of activities are audited, and you want to collect useful audit information. Audit files can quickly grow to fill the available space, so you should plan what to audit.

Determining Which Audit Policies to Use

Audit policies determine the characteristics of the audit records for the local host. The policies are set by a startup script. The bsmconv script, which enables the auditing service, creates the /etc/security/audit_startup script. The audit_startup script executes the auditconfig command to establish audit policy. See the audit_startup(1M) man page.

The audit policies are disabled by default to minimize storage requirements and system processing demands. You can enable and disable audit policies dynamically with the auditconfig command. You can enable and disable the policies permanently with the audit_startup script. Use the following table to determine if the needs of your site justify the additional overhead that results from enabling one or more audit policies.

Controlling Auditing Costs

Because auditing consumes system resources, you must control the degree of detail that is recorded. When you decide what to audit, consider the following costs of auditing:

• Cost of increased processing time

• Cost of analysis of audit data

• Cost of storage of audit data

Cost of Increased Processing Time of Audit Data

The cost of increased processing time is the least significant of the costs of auditing. The first reason is that auditing generally does not occur during computation-intensive tasks, such as image processing, complex calculations, and so forth. The other reason is that the cost for single-user systems is usually small enough to ignore.

Cost of Analysis of Audit Data

The cost of analysis is roughly proportional to the amount of audit data that is collected. The cost of analysis includes the time that is required to merge and review audit records. Cost also includes the time that is required to archive the records and keep the records in a safe place.

The fewer records that you generate, the less time that is required to analyze the audit trail. Upcoming sections, Cost of Storage of Audit Data and Auditing Efficiently, describe ways to audit efficiently. You can reduce the amount of data that you collect, while still providing enough coverage to achieve your site's security goals.

Cost of Storage of Audit Data

Storage cost is the most significant cost of auditing. The amount of audit data depends on the following:

• Number of users

• Number of machines

• Amount of use

• Degree of security that is required

Because these factors vary from site to site, no formula can determine in advance the amount of disk space to set aside for audit data storage.

Full auditing, that is, with the all flag, fills up disks quickly. Even a simple task such as compiling a program could generate a large audit file. A program of modest size could generate thousands of audit records in less than a minute. For example, the audit trail of a program of five files and 5000 lines would occupy many megabytes of disk space. You judiciously use the preselection features to reduce the volume of records that are generated. For example, by omitting the fr class, you can reduce the audit volume by more than two-thirds. Efficient audit file management is also important. After the audit records are created, file management reduces the amount of storage that is required.

Before you configure auditing, you should understand the audit flags. You should understand the types of events that the flags audit. Develop a philosophy of auditing for your site that is based on sensible measures. Such measures include the amount of security that your site requires, and the types of users that you administer.

Auditing Efficiently

The techniques in this section can help you achieve your organization's security goals while auditing more efficiently:

• Randomly audit only a certain percentage of users at any one time

• Reduce the disk-storage requirements for audit files by combining, reducing, and compressing the files. Develop procedures for archiving the files, for transferring the files to removable media, and for storing the files offline.

• Monitor the audit data in real time for unusual behaviors. You can set up procedures to monitor the audit trail as the trail is generated for certain activities. You can write a script to trigger an automatic increase in the auditing of certain users or certain machines in response to detection of unusual events.

  For example, write a script that (1) monitors the creation of audit files on all the audit file servers, and (2) processes them with the tail command. See the tail(1) man page. Pipe the output of tail -0f through the praudit command. The command yields a stream of audit records as the records are generated. This stream can be analyzed for unusual message types or other indicators, and delivered to the auditor. Or, the script can be used to trigger automatic responses.

  In addition, the script should include code that (3) constantly monitors the audit directories for the appearance of new not_terminated audit files. The script should (4) also terminate outstanding tail processes when their files are no longer being written to.

Chapter 22 Managing the BSM Service (Tasks)

This chapter presents procedures that are designed to help you set up and manage a Solaris environment that includes auditing. This chapter also includes instructions for administering the audit trail and for administering device allocation. The following is a list of the task maps in this chapter.

• Managing the BSM Service (Task Map)

• Configuring Audit Files (Task Map)

• Configuring the Auditing Service (Task Map)

• Managing Audit Records (Task Map)

• Adding an Allocatable Device (Task Map)

For an overview of auditing, see Chapter 20, BSM (Overview). For planning suggestions, see Chapter 21, Audit Planning.

Managing the BSM Service (Task Map)

The following task map shows the major tasks that are required to administer the BSM service.

Configuring Audit Files (Task Map)

Before you enable auditing on your network, you might want to edit the audit configuration files. Many of the following procedures require you to restart the service or reboot the local system. You should make as many of these changes as possible before you start the service.

The following task map describes the tasks in this section.

How to Select Audit Flags

Audit flags are defined in the /etc/security/audit_control file. The audit flags select which classes of audit records are written to the audit log.

1. Become superuser or assume an equivalent role.

2. (Optional) Save a backup copy of the audit_control file.

   # cp /etc/security/audit_control /etc/security/audit_control.save

3. Add new entries to the audit_control file.

   Each entry has the following format:

   title:string

   title

   Defines the type of line. Options are dir:, flags:, minfree:, or naflags:.

   string

   Lists specific data that is associated with the line type.

4. Instruct the audit daemon to read the new audit_control file.

   The audit daemon stores the information internally. To use the new information, either reboot the system or type the following command:

   # audit -s

Example—Changing the Location of the Audit Trail File

Lines that start with dir: define which audit file systems can be used to store audit trail files. In this example, two additional locations for audit trail files are defined.

# cat /etc/security/audit_control
dir:/etc/security/audit/host.1/files
dir:/etc/security/audit/host.2/files
dir:/var/audit
flags:
minfree:10
naflags:lo

Example—Changing Audit Flags for All Users

The flags line in the audit_control file defines which classes of events are audited for all users on the host. The classes are separated by commas, with no spaces. In this example, the events in the lo class are audited for all users.

# cat /etc/security/audit_control
dir:/var/audit
flags:lo
minfree:10
naflags:lo

Example—Changing the Soft Limit for Warnings

The minfree line in the audit_control file defines the minimum free-space level for all audit file systems. In this example, the soft limit is set so that a warning is issued when only 10 percent of the file system is available.

# cat /etc/security/audit_control
dir:/var/audit
flags:
minfree:10
naflags:lo

Example—Changing Auditing of Nonattributable Events

The naflags: line in the audit_control file defines which classes of nonattributable events are audited for all users on the host. The classes are separated by commas, with no spaces. In this example, the na event class was added.

# cat /etc/security/audit_control
dir:/var/audit
flags:
minfree:10
naflags:lo,na

How to Change Users' Audit Characteristics

Definitions for each user are stored in the /etc/security/audit_user file. These definitions are exceptions to the flags in the audit_control file.

1. Become superuser or assume an equivalent role.

2. (Optional) Save a backup copy of the audit_user file.

   # cp /etc/security/audit_user /etc/security/audit_user.save

3. Add new entries to the audit_user file.

   Each entry has the following format:

   username:always:never

   username

   Selects the name of the user to be audited.

   always

   Selects the list of audit classes that should always be audited.

   never

   Selects the list of audit classes that should never be audited.

   You can specify multiple flags by separating the audit classes with commas. For more information about audit flags, see Audit Classes and Their Audit Flags.

4. Make the new data available to the auditing daemon.

   To use the new data, you can reboot the system. You can also have the user log out and then log back in again.

Example—Changing Auditing for One User

This example shows an entry that causes audit records to be generated any time that the user sue accesses any programs in the login class (lo).

# grep sue /etc/security/audit_user
sue:lo:

Example—Creating an Audit Admin Login

If all the audit partitions are full and logins are audited, then users might not be able to log in to a host. To avoid this situation, you can set up a special account that is not audited. The special account could log in to the host even when the audit partitions are full, and fix the problem with the full partitions. In this example, the account auditadm is defined so that no auditing takes place.

# grep auditadm /etc/security/audit_user
auditadmin:no:yes

The user who is selected to use the audit admin account might need to be monitored in another way.

How to Add Audit Classes

Audit classes are defined in the /etc/security/audit_class file.

1. Become superuser or assume an equivalent role.

2. (Optional) Save a backup copy of the audit_class file.

   # cp /etc/security/audit_class /etc/security/audit_class.save

3. Add new entries to the audit_class file.

   Each entry has the following format:

   0xnumber:name:description

   0x

   Identifies number as hexadecimal.

   number

   Defines the unique audit class mask.

   name

   Defines the two-letter name of the audit class.

   description

   Defines the descriptive name of the audit class.

4. Make the new data available to the BSM service .

   To use the new data, either reboot the system, or type the following command:

   # auditconfig -conf

Example—Setting a New Audit Class

In this example, add an entry to the audit_class file that resembles the following entry. The entry creates a new audit class that is called ta.

0x01000000:ta:test application

How to Change an Audit Event's Class Membership

Event-class mappings are defined in the /etc/security/audit_event file.

1. Become superuser or assume an equivalent role.

2. (Optional) Save a backup copy of the audit_event file.

   # cp /etc/security/audit_event /etc/security/audit_event.orig

3. Change the class to which particular events belong by changing the flag of the events.

   Each entry has the following format:

   number:event:program:flag

   number

   Defines the audit event ID.

   event

   Defines the name of the audit event.

   program

   Defines the system call or user-level program executable that triggers the creation of an audit record.

   flag

   Defines the two-letter name of the audit class.

4. Make the new data available to the BSM service.

   To use the new data, either reboot the system, or type the following commands:

   # auditconfig -conf # audit -s

Example—Creating a Site-Specific Audit Event Mapping

In this example, you define a new class, and then add events to that class. To use the mapping, put the new class in the audit_control file, then reboot the system.

1. In the audit_class file, define a site-specific class to collect just those audit events that you want to monitor.

   0x00000800:sc:site class

2. In the audit_event file, change a set of audit events to the new class.

   26:AUE_SETGROUPS:setgroups(2):sc 27:AUE_SETPGRP:setpgrp(2):sc 40:AUE_SETREUID:setreuid(2):sc 41:AUE_SETREGID:setregid(2):sc 214:AUE_SETEGID:setegid(2):sc 215:AUE_SETEUID:seteuid(2):sc

3. Use the new flag in the audit_control file. The following entry audits logins, and audits all successful invocations of the events in the sc class.

   flags:lo,+sc

4. To ensure that the new configuration audits all processes, reboot the system. Or, you can use the following set of commands to ensure that each user who uses the machine is correctly audited. auid is the user ID.

   # auditconfig -conf # audit -s # setumask auid lo,+sc

How to Add Audit Events

Audit event definitions are stored in the /etc/security/audit_event file.

1. Become superuser or assume an equivalent role.

2. (Optional) Save a backup copy of the audit_event file.

   # cp /etc/security/audit_event /etc/security/audit_event.save

3. Add new entries to the audit_event file.

   Each entry has the following format:

   number:name:description:classes

   number

   Defines a unique audit event number, which must start after 32767.

   name

   Defines the unique audit event name.

   description

   Describes the audit event. Often includes the name of the man page for the audit event.

   classes

   Selects the audit classes that include this event.

4. Make the new data available to the auditing daemon.

   To use the new data, either reboot the system, or type the following command:

   # auditconfig -conf

Example—Adding a New Audit Event

This example shows an entry that defines a new audit event for a local application.

# grep localapp /etc/security/audit_event
32768:AUE_localapp:localapp(1):ta

Configuring the Auditing Service (Task Map)

This section covers the tasks that are required to configure and enable the auditing service. The following task map describes the tasks that are required to configure the auditing service.

How to Create Partitions for Auditing

The following procedure shows how to create partitions for audit files, as well as the corresponding file systems and directories. Skip steps as necessary, depending on if you already have an empty partition, or if you have already mounted an empty file system.

1. Become superuser or assume an equivalent role.

2. Determine the amount of disk space that is required.

   Assign at least 200 Mbytes of disk space per host. However, the disk space requirements are based on how much auditing you perform. So, your requirements might be far greater than this figure. Remember to include a partition for a directory of last resort.

3. Create dedicated audit partitions, as needed.

   This step is most easily done during server installation. You can also create the partitions on disks that have not yet been mounted on the server. For complete instructions on how to create the partitions, see “Creating a UFS File System” in System Administration Guide: Basic Administration.

   # newfs /dev/rdsk/cwtxdysz

   where /dev/rdsk/cwtxdysz is the raw device name for the partition.

   If the local host is to be audited, create an audit directory of last resort for the local host as well.

4. Create mount points for each new partition.

   # mkdir /var/audit/server-name.n

   Where server-name.n is the name of the server plus a number that identifies each partition. The number is optional, but the number is useful when there are many audit directories.

5. Add entries to automatically mount the new partitions.

   Add a line to the /etc/vfstab file that resembles the following:

   /dev/dsk/cwtxdysz /dev/rdsk/cwtxdysz /var/audit/server-name.n ufs 2 yes

6. (Optional) Remove the minimum free space threshold on each partition.

   If you use the default configuration, a warning is generated when the directory is 80 percent full. The warning removes the reason to reserve free space on the partition.

   # tunefs -m 0 /var/audit/server-name.n

7. Mount the new audit partitions.

   # mount /var/audit/server-name.n

8. Create audit directories on the new partitions.

   # mkdir /var/audit/server-name.n/files

9. Correct the permissions on the mount points and new directories.

   # chmod -R 750 /var/audit/server-name.n/files

10. (Optional) On a file server, define the file systems to be made available to other hosts.

    Often, disk farms are installed to store the audit records. If an audit directory is to be used by several systems, then the directory must be shared through the NFS service. Add an entry that resembles the following for each directory to the /etc/dfs/dfstab file.

    share -F nfs /var/audit/server-name.n/files

11. (Optional) On a file server, restart the NFS service.

    If this command is the first share command or set of share commands that you have initiated, the NFS daemons are probably not running. The following commands kill the daemons and restart the daemons. Refer to “Setting Up NFS Services” in System Administration Guide: Resource Management and Network Services for more information about the NFS service.

    # /etc/init.d/nfs.server stop # /etc/init.d/nfs.server start

Example—Creating an Audit Directory of Last Resort

All systems that run the auditing subsystem should have a local file system that can be used if no other file system is available. In this example, a file system is being added to a system that is named egret. Since this file system is only used locally, none of the steps for a file server are followed.

# newfs /dev/rdsk/c0t2d0
# mkdir /var/audit/egret
# grep egret /etc/vfstab
/dev/dsk/c0t2d0s1  /dev/rdsk/c0t2d0s1  /var/audit/egret ufs  2  yes  -
# tunefs -m 0 /var/audit/egret
# mount /var/audit/egret
# mkdir /var/audit/egret/files
# chmod -R 750 /var/audit/egret/files

Example—Creating New Audit Partitions

In this example, a new file system is created on two new disks that are to be used by other systems in the network.

# newfs /dev/rdsk/c0t2d0
# newfs /dev/rdsk/c0t2d1
# mkdir /var/audit/egret.1
# mkdir /var/audit/egret.2
# grep egret /etc/vfstab
/dev/dsk/c0t2d0s1  /dev/rdsk/c0t2d0s1  /var/audit/egret.1 ufs  2  yes  -
/dev/dsk/c0t2d1s1  /dev/rdsk/c0t2d1s1  /var/audit/egret.2 ufs  2  yes  -
# tunefs -m 0 /var/audit/egret.1
# tunefs -m 0 /var/audit/egret.2
# mount /var/audit/egret.1
# mount /var/audit/egret.2
# mkdir /var/audit/egret.1/files
# mkdir /var/audit/egret.2/files
# chmod -R 750 /var/audit/egret.1/files /var/audit/egret.2/files
# grep egret /etc/dfs/dfstab
 share -F nfs /var/audit/egret.1/files
 share -F nfs /var/audit/egret.2/files
# /etc/init.d/nfs.server stop
# /etc/init.d/nfs.server start

How to Configure the audit_warn Alias

The audit_warn script generates mail to an alias that is called audit_warn. To send this mail to a valid email address, you can follow either of the following options:

1. Become superuser or assume an equivalent role.

2. Configure the audit_warn mail alias.

   OPTION 1 –

   Replace the audit_warn alias with another mail account in the audit_warn script.

   After you replace audit_warn with the root account, the line that sends the email message would resemble the following:

   /usr/ucb/mail -s "$SUBJECT" root

   Ten lines in the audit_warn script require this change.

   OPTION 2 –

   Redirect the audit_warn email to another mail account.

   In this case, you would add the audit_warn alias to the appropriate mail aliases file. You could add the alias to the local /etc/mail/aliases file or to the mail_aliases database in the name space. The new entry would resemble the following if the root mail account was made a member of the audit_warn alias:

   audit_warn: root

How to Enable or Disable an Audit Policy

Audit policies determine the characteristics of the audit records for the local host. By default, all audit policies are disabled. You need to enable any audit policies that you want to use. For a description of each policy, see Audit Policies.

You can inspect, enable, or disable the current audit policy with the auditon() system call at the program level. Or, to do the same task, you can run the auditconfig command. You can also modify the policy options to the auditconfig command in the audit_startup script to make more permanent audit policy changes.

1. Become superuser or assume an equivalent role.

2. (Optional) Review the existing audit policies.

   Ensure that you are aware of all the policies that are being used before you change any policies. The following command lists the enabled policies:

   # auditconfig -lspolicy

3. Enable or disable the audit policy.

   # auditconfig -setpolicy flagpolicyname

   flag

   A flag value of + enables the policy. A flag value of - disables the policy.

   policyname

   Selects the policy to be enabled or to be disabled.

   The policy is in effect until the next boot, or until the policy is modified by the auditconfig -setpolicy command.

Example—Setting the cnt Policy

The cnt policy can be set so that if the audit partitions become full, then processes are not blocked. The records are discarded when the partitions are full, but the system still functions. The cnt policy keeps a count of the number of discarded audit records. The cnt policy should not be set if security is paramount, since unrecorded events can occur if the file system is full.

The following command enables the cnt policy:

# auditconfig -setpolicy +cnt

To maintain the policy across reboots, you should place the auditconfig -setpolicy +cnt command in the audit_startup file.

How to Enable Auditing

This task starts the auditing service. If the service has been configured, then rebooting the host also starts the service.

1. Become superuser or assume an equivalent role.

2. Bring the system into single-user mode.

   # /etc/telinit 1

   See the telinit(1M) man page for more information.

3. Run the script to configure the system to run auditing.

   Go to the /etc/security directory, and execute the bsmconv script there. The script sets up a standard Solaris machine to run auditing after a reboot. See the bsmconv(1M) man page.

   # cd /etc/security # ./bsmconv

4. Bring the system into multiuser mode.

   # /etc/telinit 6

   The startup file /etc/security/audit_startup causes the audit daemon to run automatically when the system enters multiuser mode.

How to Disable Auditing

If auditing is no longer required at some point, you can disable the auditing subsystem by running the bsmunconv command. See the bsmconv(1M) man page.

1. Become superuser or assume an equivalent role.

2. Bring the system into single-user mode.

   # /etc/telinit 1

   See the telinit(1M) man page for more information.

3. Run the script to disable auditing.

   Change to the /etc/security directory, and execute the bsmunconv script there.

   # cd /etc/security # ./bsmunconv

4. Bring the system into multiuser mode.

   # /etc/telinit 6

Managing Audit Records (Task Map)

By managing the audit trail, you can monitor the actions of users on your network. Auditing can generate large amounts of data. The following tasks show you how to work with all this data.

The following task map describes the tasks in this section.

How to Display Audit Record Formats

The bsmrecord command displays the audit id, audit class, selection mask, and record format of an audit event. The command operates on records in the audit_class and audit_event files.

The -a option in the following command lists all audit event record formats. The -h option puts the list in HTML format. The resulting file can be displayed in a browser.

Use the bsmrecord command to put the format of all audit event records in an HTML file.

% bsmrecord -a -h > audit.events.html

You can display the *html file in a browser. Use the browser's Find tool to find specific records.

See the bsmrecord(1M) man page for more information.

Example—Displaying the Audit Record Formats of a Program

In this example, the format of all audit records that are generated by the login program are displayed.

% bsmrecord -p login

terminal login
  program     /usr/sbin/login      see login(1)
  event ID    6152                 AUE_login
  class       lo                   (0x00001000)
      header
      subject
      text                         error message or "successful login"
      return

login: logout
  program     /usr/sbin/login      see login(1)
  event ID    6153                 AUE_logout
  class       lo                   (0x00001000)
      header
      subject
      text                         "logout" username
      return

rlogin
  program     /usr/sbin/login      see login(1) - rlogin
  event ID    6155                 AUE_rlogin
  class       lo                   (0x00001000)
      header
      subject
      text                         success/fail message
      return

telnet login
  program     /usr/sbin/login      see login(1) - telnet
  event ID    6154                 AUE_telnet
  class       lo                   (0x00001000)
      header
      subject
      text                         success/fail message
      return

Example—Displaying the Audit Record Formats of an Audit Class

In this example, the format of all audit records in the fd class are displayed.

% bsmrecord -c fd

ftruncate
    Not used.

truncate
    Not used.

unlink
  system call unlink               see unlink(2)
  event ID    6                    AUE_UNLINK
  class       fd                   (0x00000020)
      header
      path
      [attribute]
      subject
      return

How to Merge Audit Records

This task shows you how to merge all audit files in all the audit directories. Follow these steps when you want to analyze the contents of the audit trail.

1. Become superuser or assume an equivalent role.

2. Change directories to the primary audit directory.

   # cd /etc/security/audit/server-name.1/files

   The merged file is placed in the /etc/security/audit/server-name.1/files directory. This directory is a protected directory.

3. Merge the audit records.

   # auditreduce > merged.log

   All directories that are listed in the dir: lines of the audit_control file on server-name are merged. The merged records are then placed in the merged.log file in the current directory.

Example—Displaying the Entire Audit Trail

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

# auditreduce | praudit

Example—Printing the Entire Audit Trail

With a pipe to the lp command, the output goes to the printer.

# auditreduce | praudit | lp

Example—Combining and Reducing Audit Files

Use the auditreduce command with the -O option to combine several audit files into one file and to save the files in a specified output file. auditreduce can do this type of combination and deletion automatically. See the -C and -D options in the auditreduce(1M) man page. However, you can select the files manually to good effect. Use the find command, then use auditreduce to combine just the named set of files.

When used in this way, the auditreduce command merges all the records from its input files into a single output file. The input files should then be deleted. In addition, the output file should be kept in a directory that is named /etc/security/audit/server-name/files so that auditreduce can find the output file.

# auditreduce -O combined-filename

The auditreduce command can also reduce the number of records in its output file. The command can eliminate the less interesting records as it combines the input files. For example, you might use the auditreduce command to retain only the login and logout records in audit files that are over a month old. If you need to retrieve the complete audit trail, you could recover the trail from backup tapes.

# auditreduce -O daily.summary -b 19990413 -c lo; compress *daily.summary
# mv *daily.summary /etc/security/summary.dir

Example—Displaying User Activity From a Selected Date

In the following example, the system administrator checks to see when user tamiko logged in and logged out on April 13, 1999. The administrator requests the lo event class. The short-form date is in the form yymmdd. The long form is described in the auditreduce(1M) man page.

# auditreduce -d 990413 -u tamiko -c lo | praudit

Example—Copying Selected Records to a Single File

In this example, login and logout messages for a particular day are selected from the audit trail. The messages are merged into a target file. The target file is written in a directory other than the normal audit root directory.

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

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

/usr/audit_summary/19990413000000.19990413235959.logins

Example—Cleaning Up a not_terminated Audit File

Occasionally, 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. In such instances, an audit file remains with the string not_terminated as the end-time, even though the file is no longer used for audit records. When you find such a file, you can manually verify that the file is no longer in use. You can clean up the open file by specifying the name of the file with the correct options.

# audit -s
19990414121112.not_terminated.egret
# auditreduce -O egret 19990413120429.not_terminated.egret

The audit command checks the name of the current audit file. The auditreduce command creates a new audit file with the correct name and correct timestamps. The correct name includes the correct suffix (egret). The auditreduce then copies all the records into the file.

How to Display Audit Records

1. Become superuser or assume an equivalent role.

2. Change directories to an audit files directory, such as /usr/audit_summary/logins.

   # cd /usr/audit_summary/logins

3. Read a file by using the praudit command.

   # praudit 19990413000000.19990413235959.logins | more

Example—Putting Audit Records in XML Format

In this example, the audit records are converted to XML format. XML format can be displayed in a browser. The format can also be used to create a report.

# praudit -x 19990413000000.19990413235959.logins > 19990413.logins.xml

The *xml file can be displayed in a browser. The contents of the file can be operated on by a script to extract the relevant information.

How to Prevent Audit Trail Overflow

If your security policy requires that all audit data be saved, do the following:

1. Set up a schedule to regularly archive audit files. Set up a schedule to delete the archived audit files from the audit file system.

2. Manually archive audit files by backing up the files on tape. You can also move the files to an archive file system.

3. Store context-sensitive information that is necessary to interpret audit records, along with the audit trail.

4. Keep records of which audit files are moved offline.

5. Store the archived tapes appropriately.

6. Reduce the volume of audit data that you store by creating summary files.

   You can extract summary files from the audit trail by using options to the auditreduce command. The summary files then contain only records for certain specified types of audit events. For examples, see Example—Combining and Reducing Audit Files and Example—Copying Selected Records to a Single File.

Managing Device Allocation (Tasks)

You can use device allocation to decrease the security risk that is associated with various removable media.

Adding an Allocatable Device (Task Map)

The following task map describes the major steps that are required to define a new allocatable device.

How to Set Up Lock Files for an Allocatable Device

The lock files are zero-length files that are created in the /etc/security/dev directory. One file is created for each allocatable device. If no lock file exists for a device, the device cannot be allocated, so no one can access the device.

1. Become superuser or assume an equivalent role.

2. Obtain the device name for the device from its entry in the device_maps file by using the dminfo command.

   See The device_maps File and the dminfo(1M) and device_maps(4) man pages. For example, the device name for device type st is st0. In the next step, you use the device name as the name of the lock file.

3. Create an empty lock file for the device by using the touch command.

   Use the device name for the file name in place of device-name.

   # cd /etc/security/dev # touch device-name # chmod 600 device-name # chown bin device-name # chgrp bin device-name

How to Change Which Devices Can Be Allocated

This procedure defines which devices can be used with the device allocation mechanism.

1. Become superuser or assume an equivalent role.

2. Determine which devices are listed in the /etc/security/device_allocate file.

3. Decide if there are devices that are not in the device_allocate file, yet should be made allocatable.

4. Edit the device_allocate file and add the new device.

   Each entry should use the following format:

   device-name;device-type;;;;program

   device-name

   Specifies the name of the device

   device-type

   Specifies the device type

   program

   Specifies the purge program to be run

How to Allocate a Device

1. Become superuser or assume an equivalent role.

2. Use the allocate command with a device that is specified by device name.

   sar1% allocate st0

You can also allocate a device by device type by using the -g option to the allocate command.

If the command cannot allocate the device, an error message is displayed in the console window. For a list of allocation error messages, see the allocate(1) man page.

Example—Allocating a Printer

Only the user who ran the allocate command can use the printer.

sarl% allocate /dev/lp/chestnut

How to Deallocate a Device

Deallocation enables other users to allocate and use the device when you are finished.

1. Deallocate a device by using the deallocate command followed by the device file name.

   sar1% deallocate st0

Example—Deallocating a Printer

To deallocate a printer that is named chestnut, type the following command:

# deallocate /dev/lp/chestnut

Example—Forcing a Deallocation

Devices that a user has allocated are not automatically deallocated when the process terminates or when this user logs out. You most commonly need to use the following form of the deallocate command when a user forgets to deallocate a specific device. The following command deallocates the device so that others users can allocate the device.

# deallocate -F st0

Example—Deallocating All Devices

You can deallocate all devices only at system initialization time.

# deallocate -I

Chapter 23 BSM Service (Reference)

This chapter describes the important components of the BSM service, which are the auditing subsystem and the device allocation mechanism.

The auditing mechanism helps you detect potential security breaches by revealing suspicious or abnormal patterns of system usage. The auditing mechanism also provides a means to trace suspect actions back to a particular user, thus serving as a deterrent. If users know that their activities are likely to be audited, they might be less likely to attempt malicious activities.

The following is a list of the reference information in this chapter.

• Audit Commands

• Audit Service Files

• Audit Administration Profiles

• Audit Classes and Their Audit Flags

• Audit Policies

• Process Audit Characteristics

• Audit Trail

• Naming Conventions for Audit Files

• Audit Record Structure

• Audit Token Formats

• Device Allocation Reference

For an overview of auditing, see Chapter 20, BSM (Overview). For planning suggestions, see Chapter 21, Audit Planning. For procedures to configure auditing at your site, see Chapter 22, Managing the BSM Service (Tasks).

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.

Audit Service Files

Auditing uses the following files:

• The /etc/system File

• The audit_class File

• The audit_control File

• The audit_data File

• The audit_event File

• The audit_startup Script

• The audit_user File

• The audit_warn Script

The /etc/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 command causes the auditing module, a kernel module, 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.

The audit_class File

The /etc/security/audit_class file contains definitions of the existing audit classes. Audit classes are groups of audit events. Each class has an associated audit flag, which is the short name that stands for the class. You use the short name in the audit_control file to preselect the classes whose events you want to audit. The flags accept prefixes for finer–grained selection. See Audit Flag Syntax for more information.

The root user, 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. See the audit_class(4) man page for more information. For descriptions of the audit flags, see Definitions of Audit Flags.

The audit_control File

An /etc/security/audit_control file on each machine is read by the audit daemon. See the audit_control(4) man page. The audit_control file is located in the /etc/security directory. Each machine has its own local audit_control file. The file enables every machine to mount their audit file systems from different locations or in a different order. For example, the primary audit file system for machineA might be the secondary audit file system for machineB.

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

• The audit flags line begins with flags:. The line contains the audit flags that preselect which classes of events are audited for all users on the machine. The audit flags specified here are referred to as the machine-wide audit flags or the machine-wide audit preselection mask. Audit flags are separated by commas, with no spaces.

• The nonattributable flags line begins with naflags:. The line contains the audit flags that preselect which classes of events are audited when an action cannot be attributed to a specific user. The flags are separated by commas, with no spaces.

• The audit threshold line begins with minfree:. The line defines the minimum free-space level for all audit file systems. The minfree percentage must be greater than or equal to 0. The default is 20 percent. When an audit file system is 80 percent filled, the audit data is then stored in the next available audit directory. See the audit_warn(1M) man page.

• The directory definition lines begin with dir:. Each line defines an audit file system and directory that the machine uses to store its audit log files. You can define one or more directory definition lines. The order of the dir: lines 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 machine. The second directory is the secondary audit directory where the audit daemon creates audit trail files when the first directory becomes full, and so forth. See the audit(1M) man page.

An audit_control file is created during the configuration process on each machine.

When you make changes to the audit_control file, you then run the audit -s command to instruct the audit daemon to reread the file.

The audit -s command does not change the preselection mask for existing processes. Use auditconfig, setaudit, or auditon for existing processes. See the getaudit(2) and auditconfig(1M) man pages for more information.

Sample audit_control File

The following is a sample audit_control file for the machine dopey. dopey 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 filled. The flags 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. Non-attributable events are also audited.

flags:lo,am,-all,^-fc
naflags:lo,nt
minfree:20
dir:/etc/security/audit/blinken/files
dir:/etc/security/audit/blinken.1/files
#
# Audit filesystem used when blinken fills up
#
dir:/etc/security/audit/winken 

The audit_data File

When the auditd daemon starts on each machine, it creates the file /etc/security/audit_data. The format of the file consists of a single entry with the two fields separated by a colon. See the audit_data(4) man page. The first field is the audit daemon's process ID. The second field is the path name of the audit file to which the audit daemon is currently writing audit records. Here is an example:

# cat /etc/security/audit_data
116:/etc/security/audit/blinken.1/files/19990320100002.not_terminated.dopey

The audit_event File

The /etc/security/audit_event file contains the default event-to-class mappings.You can edit this file to change the class mappings. However, if you do so, you must reboot the system or run auditconfig -conf to read the changed mappings into the kernel. See the audit_event(4) man page.

The audit_startup Script

The /etc/security/audit_startup script automatically starts the audit daemon when the system enters multiuser mode. The script is invoked as part of the startup sequence, just prior to the execution of the audit daemon. See the audit_startup(1M) man page for more information.

A default audit_startup script that automatically configures the event-to-class mappings and sets the audit policies. The script is created during the BSM package installation.

The audit_user File

To audit some users differently from others, you can edit the /etc/security/audit_user file to add audit flags for individual users. If specified, these flags are combined with the system-wide flags in the audit_control file to determine which classes of events to audit for that user. The flags that you add to the user's entry in the audit_user file modify the defaults from the audit_control file in two ways:

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

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

Each user entry in the audit_user file contains three fields.

• The username field

• The always-audit field

• The never-audit field

The audit fields are processed in sequence. The always-audit field turns on the auditing of the classes in that field. The never-audit field turns off the auditing of the classes in that field.

Avoid the common mistake of leaving the all audit flag in the never-audit field. This mistake causes all auditing to be turned off for that user, which overrides the flags that are set in the always-audit field. The flag also overrides machine-wide audit flags set in the audit_control file.

The never-audit flags for a user override the system defaults. You might not want to overrride system defaults. For example, suppose you want to audit everything for user tamiko for except for successful reads of file system objects. This strategy audits almost everything for a user. However, the strategy generates about three-quarters of the audit data that would be produced if all data reads were audited. You also want to apply the system defaults to tamiko. Here are two possible audit_user entries:

The correct entry:

tamiko:all,^+fr:

The incorrect entry:

tamiko:all:+fr

The first example means, “always audit everything except for successful file-reads.” The second example means, “always audit everything, but never audit successful file-reads.” The second example is incorrect because the never-audit field would override the system defaults. The first example achieves the desired effect: the always-audit flags include the exception to the all flag. Since no flag is in the never-audit field, the system defaults from the audit_control file are not overridden here.

Successful events and failed events are treated separately. A process could generate more audit records when an error occurs than when an event is successful.

The audit_warn Script

Whenever the audit daemon encounters an unusual condition while writing audit records, it invokes the /etc/security/audit_warn script. See the audit_warn(1M) man page. 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, audit_warn writes a message to the console. audit_warn also sends a message to the audit_warn mail alias. You should set up this alias when you enable auditing.

When audit daemon detects the following conditions, it invokes the audit_warn script.

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

  The audit_warn script is invoked with the string soft and the name of the directory whose available space has gone below the minimum value. The audit 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 audit 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. Mail 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 audit 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. Mail is also sent to the audit_warn alias.

  The audit daemon switches automatically to the next suitable directory with any space available. The audit 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.

  In the default configuration, a message is written to the console. Mail is also sent to the audit_warn alias. The processes that generate audit records are suspended. The audit daemon goes into a loop, waiting for space to become available, and resumes processing audit records when that happens. While audit records are not being processed, no auditable activities occur. Every process that attempts to generate an audit record is suspended. For this reason, you should set up a separate audit administration account that could operate without any auditing enabled. Then, you could continue operations without being suspended.

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

  • ebusy – Another audit daemon process is already running

  • tmpfile – A temporary file cannot be used

  • auditsvc – The auditsvc() system call fails

  • postsigterm – A signal was received during auditing shutdown

  Mail is sent to the audit_warn alias.

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

Audit Administration Profiles

The Solaris operating environment provides profiles for configuring the audit service and for analyzing the audit trail.

• Audit Control – Profile that enables a role to configure Solaris auditing. The profile grants authorizations to configure auditing files and to run auditing commands. Roles with the Audit Control profile can run the following commands: audit, auditd, auditconfig, bsmconv, and bsmunconv.

• Audit Review – Profile that enables a role to analyze Solaris auditing records. The profile grants authorization to read audit records with the praudit and auditreduce commands. The role can also run the auditstat command.

• System Administrator – Profile that includes the Audit Review profile. A role with the System Administrator profile can analyze audit records.

To assign a profile to a role, see Creating Roles.

Audit Classes and Their Audit Flags

Audit flags indicate classes of events to audit. Machine-wide defaults for auditing are specified for all users on each machine by flags in the audit_control file. The file is described in The audit_control File.

You can modify what is audited for individual users by putting audit flags in a user's entry in the audit_user file. The audit flags are also used as arguments to the auditconfig command. See the auditconfig(1M) man page.

Definitions of Audit Flags

The following table shows each predefined audit class. The table shows the audit flag, the long name, and a short description. The audit flag is the short name that stands for the class. You use these audit flags in the auditing configuration files to specify which classes of events to audit. You also use them as arguments to auditing commands, such as auditconfig. You can define new classes by modifying the audit_class file. You can also rename existing classes. See the audit_class(4) man page for more information.

Audit Flag Syntax

The prefixes to the audit flags determine whether a class of events is audited for success, or for failure. Without a prefix, a class is audited for success and for failure. The following table shows the format of the audit flag and some possible representations.

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

Prefixes That Modify Audit Flags

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

The prefixes to the audit flags can be used in the following files and commands:

• In the flags line in the audit_control file

• In flags field in the user's entry in the audit_user file

• With arguments to the auditconfig command

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

Audit Policies

Audit policies determine if additional information is added to the audit trail. The audit policies are described in Determining Which Audit Policies to Use.

Process Audit Characteristics

The following audit characteristics are set at initial login:

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

  The algorithm for obtaining the process preselection mask is described in the following equation:

  user's process preselection mask = (flags: line + always-audit flags) - never-audit flags

  Add the audit flags from the flags: line in the audit_control file to the flags from the always-audit field in the user's entry in the audit_user file. Then, subtract from the total the flags from the user's never-audit 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 descendant 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 and the number that corresponds to the console device is 0.

Audit Trail

The audit trail is created by the audit daemon. The audit daemon starts on each machine when the machine is brought up. After the auditd daemon starts at boot time, it is responsible for collecting the audit trail data and writing the audit records into audit files, which are also called audit log files. For a description of the file format, see the audit.log(4) man page. See also the auditd(1M) man page.

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 there is no other suitable directory 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, audit directories within other file systems is not acceptable.

You should also consider the following factors.

• 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 machines in the configuration.

Naming Conventions for Audit Files

Each 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 machine that generated them.

Audit File Naming

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

start-time.finish-time.machine 

where

• start-time – Is the time that the first audit record in the audit file was generated.

• finish-time – Is the time that the last record was written to the file.

• machine – Is the name of the machine that generated the file.

For an example of these names, see Example of a Closed Audit File Name.

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

start-time.not_terminated.machine

How Audit File Names Are Used

The time stamps in file names are used by the auditreduce command to locate records within a specific time range. These time stamps 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.

Time-Stamp Format and Interpretation

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 a daylight savings time boundary. 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.

Example of a File Name for a Still-Active File

The format of a file name of a still-active file is as follows:

YYYYMMDDHHMMSS.not_terminated.machine

Here is an example:

19990327225243.not_terminated.dopey

The audit log files are named by the beginning date. So, in the example above the audit file was created in 1999, on March 27, at 10:52:43 p.m, GMT. The not_terminated in the file name means either that the file is still active or that the auditd daemon was unexpectedly interrupted. The name dopey at the end is the host name of the machine whose audit data is being collected.

Example of a Closed Audit File Name

The format of the name of a closed audit log file is as follows:

YYYYMMDDHHMMSS.YYYYMMDDHHMMSS.hostname

Here is an example:

19990320005243.19900327225351.dopey

In this example, the audit log file was created in 1999, on March 20, at 12:52:43 a.m., GMT. The file was closed March 27, at 10:53:51 p.m., GMT. The name dopey at the end is the host name of the machine whose audit data was collected.

Whenever auditd is unexpectedly interrupted, the audit file that is open at the time retains the not_terminated file name designation. For example, when a machine is writing to a remotely mounted audit file, the file server can become inaccessible. When the mounted audit file cannot be reached, the not_terminated designation remains in the file's name. When service is restored, the audit daemon opens a new audit file and keeps the old audit file name intact.

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 auditable event. The following figure shows a typical audit record.

Figure 23–3 Typical Audit Record Structure

Audit Token Formats

Each token has a token type identifier 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 description of each token.

An audit record always contains a header token. The header token indicates where the audit record begins in the audit trail. Every audit record contains a subject token, except for audit records from some nonattributable events. In the case of attributable events, these two tokens refer to the values of the process that caused the event. In the case of asynchronous events, the process tokens refer to the system.

acl Token

The acl token records information about Access Control Lists. This 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 ID field

• A field that lists the permissions associated with this ACL

The praudit command displays the acl token as follows:

acl,tpanero,staff,0755

The following figure shows the format of the acl token.

Figure 23–4 acl Token Format

arbitrary Token

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 format field, such as hexadecimal

• A 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 one or more items of the specified type. The praudit command displays the arbitrary token as follows:

arbitrary,decimal,int,1
42

The following figure shows the format of the arbitrary token.

Figure 23–5 arbitrary Token Format

The following table shows the possible values of the print format field. Table 23–5.

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 command displays the arg token as follows:

argument,1,0x00000000,addr

The following figure shows the format of the arg token.

Figure 23–6 arg Token Format

attr Token

The attr token contains information from the file vnode. This token has seven fields:

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

• The file access mode and type

• The owner user ID

• The owner group ID

• The file system ID

• The inode ID

• The device ID the file might represent

See the statvfs(2) man page for further information about the file system ID and the device ID.

The attr token usually accompanies a path token. The attr token is produced during path searches. In the event of a path-search error, there is no vnode available to obtain the necessary file information. Therefore, the attr token is not included as part of the audit record. The praudit command displays the attr token as follows:

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

The following figure shows the format of an attr token.

Figure 23–7 attr Token Format

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 zero or more null-terminated strings. The praudit command displays the exec_args token as follows:

vi,/etc/security/audit_user

The following figure shows the format of an exec_args token.

Figure 23–8 exec_args Token Format

The exec_args token is output only when the audit policy argv 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 zero or more null-terminated strings. The praudit command displays the exec_env token as follows:

exec_env,25,
GROUP=staff,HOME=/export/home/matrix,HOST=mestrix,HOSTTYPE=sun4u,HZ=100,
LC_COLLATE=en_US.ISO8859-1,LC_CTYPE=en_US.ISO8859-1,LC_MESSAGES=C,
LC_MONETARY=en_US.ISO8859-1,LC_NUMERIC=en_US.ISO8859-1,
LC_TIME=en_US.ISO8859-1,LOGNAME=matrix,MACHTYPE=sparc,
MAIL=/var/mail/matrix,OSTYPE=solaris,PATH=/usr/sbin:/usr/bin,PS1=#,
PWD=/var/audit,REMOTEHOST=192.168.13.5,SHELL=/usr/bin/csh,SHLVL=1,
TERM=dtterm,TZ=US/Pacific,USER=matrix,VENDOR=sun

The following figure shows the format of an exec_env token.

Figure 23–9 exec_env Token Format

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

exit Token

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

The following figure shows the format of an exit token.

Figure 23–10 exit Token Format

file Token

The file token is a special token that is generated by the audit 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 audit daemon builds a special audit record that contains this token to “link” together successive audit files into one audit trail. The file token has four fields:

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

• A time and date stamp that identifies the time that the file was created or was closed

• A byte count of the file name that includes a null terminator

• A field that holds the file null-terminated name

The praudit command displays the file token as follows:

file,Tue Sep  1 13:32:42 1992, + 79249 msec,
	/var/audit/localhost/files/19990901202558.19990901203241.quisp

The following figure shows the format of a file token.

Figure 23–11 file Token Format

group Token (Obsolete)

This token has been replaced by the newgroups token, which provides the same type of information but requires less space. A description of the group token is provided here for completeness, but the application designer should use the newgroups token. Notice that praudit does not distinguish between the two tokens, as both token IDs are labeled group in praudit output.

The group token records the groups entries from the process's credential. The group token has two fixed fields:

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

• An array of group entries of size NGROUPS_MAX (16)

The remainder of the token consists of zero or more group entries. The praudit command displays the group token as follows:

group,staff,admin,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1

The following figure shows the format of a group token.

Figure 23–12 group Token Format

The group token is output only when the audit policy group 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 six 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

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

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

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

• The time and date that the record was created

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

The praudit command displays the header token for a ioctl() system call as follows:

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

The following figure shows the format of a header token.

Figure 23–13 header Token Format

The ID modifier field has the following flags defined:

0x4000			PAD_NOTATTR						nonattributable event
0x8000			PAD_FAILURE						fail audit event

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 16 bytes to describe the type, and 16 bytes to describe the address. The in_addr token has two fields:

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

• An Internet address

The praudit command displays the in_addr token as follows:

ip address,129.150.113.7

The following figure shows the format of an in_addr token.

Figure 23–14 in_addr Token Format

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. The following figure shows the format of an ip token.

Figure 23–15 ip Token Format

ipc Token

The ipc token contains the System V IPC message/semaphore/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 praudit command displays the ipc token as follows:

IPC,msg,3

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 following figure shows the format of an ipc token.

Figure 23–16 ipc Token Format

ipc_perm Token

The ipc_perm token contains a copy of the System V IPC access information. 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 modes of the IPC

• The sequence number of the IPC

• The IPC key value

The praudit command displays the ipc_perm token as follows:

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

The values are taken from the ipc_perm structure that is associated with the IPC object. The following figure shows the format of an ipc_perm token.

Figure 23–17 ipc_perm Token Format

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

The following figure shows the format of an iport token.

Figure 23–18 iport Token Format

newgroups Token

This token replaces the group token. Notice that the praudit command does not distinguish between the two tokens, as both token IDs are labeled group in praudit output.

The newgroups token records the group entries from the process's credential. The newgroups token has two fixed fields:

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

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

The remainder of this token is composed of zero or more group entries. The praudit command displays the newgroups token as follows:

group, staff, admin

The following figure shows the format of a newgroups token.

Figure 23–19 newgroups Token Format

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

opaque Token

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

The following figure shows the format of an opaque token.

Figure 23–20 opaque Token Format

path Token

The path token contains access path information for an object. This token contains the following fields:

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

• A byte count of 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 as follows. Note that the path length field is not displayed.

path,/etc/security/audit_user

The following figure shows the format of a path token.

Figure 23–21 path Token Format

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 invariant 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

The terminal ID for port numbers in releases that are earlier than the Solaris 8 release 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

The terminal ID for port numbers in the Solaris 8 release or the Solaris 9 release 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 command displays the process token as follows:

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

The following figure shows the format of a process token.

Figure 23–22 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). This 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. This token indicates exit status and other return values in application auditing.

The praudit command displays the return token as follows:

return,success,0

The following figures shows the format of a return token.

Figure 23–23 return Token Format

seq Token

The sequence token, seq, is an optional token that contains a sequence number. Used for debugging, this token is added to each audit record when the seq policy is active. The seq token has two fields:

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

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

The sequence number is incremented every time an audit record is generated and added to the audit trail. The praudit command displays the seq token as follows:

sequence,1292

The following figure shows the format of a seq token.

Figure 23–24 seq Token Format

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

socket Token

The socket token contains information that describes an Internet socket. This token has six fields:

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

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

• The local port address

• The local Internet address

• The remote port address

• The remote Internet address

The praudit command displays the socket token as follows:

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

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 16 bytes to describe the type, and 16 bytes to describe the address. The following figure shows the format of a socket token.

Figure 23–25 socket Token Format

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:

• An ID that identifies this token as a subject token

• The invariant 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

The terminal ID for port numbers in releases that are earlier than the Solaris 8 release 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

The terminal ID for port numbers in the Solaris 8 release or the Solaris 9 release 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,cjc,cjc,staff,cjc,staff,424,223,0 0 quisp

The following figure shows the format of the subject token.

Figure 23–26 subject Token Format

text Token

The text token contains a text string. This 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 command displays the text token as follows:

text,aw_test_token

The following figure shows the format of a text token.

Figure 23–27 text Token Format

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 has been set.

If an audit record was generated with trailers turned on, the auditreduce command verifies that the trailer points back to the record header correctly. 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

The following figure shows the format of a trailer token.

Figure 23–28 trailer Token Format

Device Allocation Reference

Device allocation protects removable media from unauthorized use. You can require that a user allocate a device. You can deny a user permission to use a device. Such allocation measures can protect your site from loss of data, computer viruses, and other security breaches. The following section provides information about device allocation.

Components of the Device-Allocation Mechanism

The components of the device-allocation mechanism are as follows:

• The allocate, deallocate, dminfo, and list_devices commands. For more information, see Using the Device Allocation Commands.

• The /etc/security/device_allocate file. See the device_allocate(4) man page.

• The /etc/security/device_maps file. See the device_maps(4) man page.

• A lock file in the /etc/security/dev directory for each allocatable device.

• The changed attributes of the device-special files that are associated with each allocatable device.

• Device-clean scripts for each allocatable device.

The device_allocate file, the device_maps file, and the lock files are local configuration files. These files are not administered as name service databases because tape drives, diskette drives, and printers connect to specific machines.

Using the Device Allocation Commands

This section describes some of the options to the allocate, deallocate, and list_devices commands that are for use by administrators. Only root or a role of equivalent power can access these options. The commands are detailed on their respective man pages.

The Allocate Error State

An allocatable device is in the allocate error state if it is owned by user bin and group bin with a device-special file mode of 0100. If a user wants to allocate a device that is in the allocate error state, you can try to force the deallocation of the device. The deallocate command with the -F option forces deallocation. Or, you can use allocate -U to assign the device to the user. Once the device is allocated, you can investigate any error messages that appear. After any problems with the device are corrected, you must use the force option, -F to clear the allocate error state from the device.

The device_maps File

You can examine the /etc/security/device_maps file to determine the device names, device types, and device-special files that are associated with each allocatable device. See the device_maps(4) man page. Device maps are created when you set up device allocation. A rudimentary device_maps file is created by bsmconv when the BSM is enabled. This initial device_maps file should be used only as a starting point. You can then augment and customize the device_maps file for your site.

The device_maps file defines the device-special file mappings for each device, which in many cases is not intuitive. This file allows various programs to discover which device-special files map to which devices. You can use the dminfo command, for example, to retrieve the device name, the device type, and the device-special files to specify when you set up an allocatable device. The dminfo command uses the device_maps file to report this information.

Each device is represented by a one-line entry of the form:

device-name:device-type:device-list

Lines in the device_maps file can end with a backslash (\) to continue an entry on the next line. Comments can also be included. A “#” makes a comment out of all subsequent text until the next newline not immediately preceded by a backslash. Leading and trailing blanks are allowed in any field.

The following is an example of entries in a device_maps file for SCSI tape st0 and diskette fd0.

fd0:\
	fd:\
	/dev/fd0 /dev/fd0a /dev/fd0b /dev/rfd0 /dev/rfd0a /dev/rfd0b:\
					.
					.
					.
st0:\
	st:\
	/dev/rst0 /dev/rst8 /dev/rst16 /dev/nrst0 /dev/nrst8 /dev/nrst16:\

The device_allocate File

You can modify the device_allocate file to change devices from allocatable to nonallocatable, or to add new devices. A sample device_allocate file follows.

st0;st;;;;/etc/security/lib/st_clean
fd0;fd;;;;/etc/security/lib/fd_clean
sr0;sr;;;;/etc/security/lib/sr_clean
audio;audio;;;*;/etc/security/lib/audio_clean

You define which devices should be allocatable during initial BSM configuration. You can decide to accept the default devices and their defined characteristics, as shown in the preceding sample device_allocate file. Whenever you add a device to any machine after the system is up and running, you must decide whether to make the new device allocatable.

After installation, you can modify the entries for devices in the device_allocate file. Any device that needs to be allocated before use must be defined in the device_allocate file on each machine. Currently, cartridge tape drives, diskette drives, CD-ROM devices, and audio chips are considered allocatable. These device types have device-clean scripts.

Xylogics^TM tape drives or Archive tape drives also use the st_clean script that is supplied for SCSI devices. You need to create your own device-clean scripts for other devices, such as modems, terminals, graphics tablets, and other allocatable devices. The script must fulfill object-reuse requirements for that type of device.

An entry in the device_allocate file does not mean that the device is allocatable, unless the entry specifically states that the device is allocatable. In the sample device_allocate file, note the asterisk (*) in the fifth field of the audio device entry. An asterisk in the fifth field indicates to the system that the device is not allocatable. That is, the system administrator does not require a user to allocate the device before it is used nor to deallocate it afterward. Any other string placed in this field indicates that the device is allocatable.

In the device_allocate file, you represent each device by a one-line entry of the form:

device-name;device-type;reserved;reserved;alloc;device-clean

For example, the following line shows the entry for device name st0:

st0;st;;;;;/etc/security/lib/st_clean

Lines in the device_allocate file can end with a “\” to continue an entry on the next line. Comments can also be included. A “#” makes a comment out of all subsequent text until the next newline not immediately preceded by a “\”. Leading and trailing blanks are allowed in any field.

The following table describes each field in the device_allocate file.

Device-Clean Scripts

The device-clean scripts address the security requirement that all usable data be purged from a physical device before reuse. By default, cartridge tape drives, diskette drives, CD-ROM devices, and audio devices require device-clean scripts, which are provided. This section describes what device-clean scripts do.

Object Reuse

Device allocation satisfies part of the object-reuse requirement. The device-clean scripts make sure that data that is left on a device by one user is cleared. The data is cleared before the device is allocatable by another user.

Device-Clean Script for Tapes

The st_clean device-clean script supports three tape devices. The supported tape devices are as follows:

• SCSI 1/4-inch tape

• Archive 1/4-inch tape

• Open-reel 1/2-inch tape

The st_clean script uses the rewoffl option to the mt command to affect the device cleanup. For more information, see the mt(1) man page. If the script runs during system boot, the script queries the device. The script determines if the device is online. If the device is online, the script determines if the device has media in it. The 1/4-inch tape devices that have media in them are placed in the allocate error state. The allocate error state forces the administrator to clean up the device manually.

During normal system operation, when the allocate or deallocate command is executed in interactive mode, the user is prompted to remove the media. The script pauses until the media is removed from the device.

Device-Clean Scripts for Diskettes and CD-ROM Devices

The following table shows the device-clean scripts for diskettes and CD-ROM devices.

The scripts use the eject command to remove the media from the drive. See the eject(1) man page. If the eject command fails, the device is placed in the allocate error state.

Device-Clean Script for Audio

Audio devices are cleaned up with an audio-clean script. The script performs an AUDIO_DRAIN ioctl system call to flush the device. The script then performs an AUDIO_SETINFO ioctl system call to reset the device configuration to the default. In addition, the script retrieves the audio chip registers by using the AUDIOGETREG ioctl system call. Any registers that deviate from the default settings are reset by using the AUDIOSETREG ioctl system call.

Writing New Device-Clean Scripts

If you add more allocatable devices to the system, you might need to create your own device-clean scripts. The deallocate command passes a parameter to the device-clean scripts. The parameter, shown here, is a string that contains the device name. See the device_allocate(4) man page for more information.

st_clean -[I|F|S] device-name

Device-clean scripts must return “0” for success and greater than “0” for failure. The options -I, -F, and -S help the script determine its running mode. The following table describes the options.

How the Device Allocation Mechanism Works

This section gives an example of how the device-allocate mechanism works.

The allocate command first checks for the presence of a lock file under the device name for the specified device in the /etc/security/dev directory. If the file is owned by allocate, then the ownership of the lock file is changed to the name of the user who initiated the allocate command.

The allocate command then checks for an entry for the device in the device_allocate file. The command further checks that the entry shows that the device as allocatable.

The first listing in the following example shows that a lock file exists with owner bin, group bin, and mode 600 for the st0 device in /etc/security/dev. The second listing shows that the associated device-special files are set up properly, with owner bin, group bin, and mode 000.

untouchable% ls -lg /etc/security/dev/st0
-rw------- 1 bin bin      		      0 Dec 6 15:21 /etc/security/dev/st0
untouchable% ls -lg /devices/sbus@1,f8000000/esp@0,800000
c--------- 1 bin bin		       18,  4 May 12 13:11 st@4,0:
c--------- 1 bin bin	       18, 20 May 12 13:11 st@4,0:b
c--------- 1 bin bin	       18, 28 May 12 13:11 st@4,0:bn
c--------- 1 bin bin	       18, 12 May 12 13:11 st@4,0:c
					 .
					 .
					 .
c--------- 1 bin bin	       18,  0 May 12 13:11 st@4,0:u
c--------- 1 bin bin	       18, 16 May 12 13:11 st@4,0:ub
c--------- 1 bin bin	       18, 24 May 12 13:11 st@4,0:ubn
c--------- 1 bin bin	       18,  8 May 12 13:11 st@4,0:un

In this example, the user vanessa allocates device st0.

untouchable% whoami
vanessa
untouchable% allocate st0

When the user vanessa runs the allocate command to allocate the tape st0, allocate first checks for the existence of an /etc/security/dev/st0 file. If no lock file exists or if the lock file is owned by a user other than allocate, then user vanessa could not allocate the device.

If the allocate command finds the lock file for the device with the correct ownership and permissions, the command then checks to make sure that the device has an entry in the device_allocate file. The command also checks that the entry specifies that the device is allocatable.

In this example, the default device_allocate entry for the st0 device specifies that the device is allocatable. Because the allocate command finds that all these conditions are met, the device is allocated to user vanessa.

The allocate command changes the ownership and permissions of the device-special files that are associated with the device in the /dev directory. To allocate the st0 device to the user vanessa, the mode on its associated device-special files is changed to 600 and the owner is changed to vanessa.

The allocate command also changes the ownership of the lock file that is associated with the device in the /etc/security/dev directory. To allocate the st0 device to the user vanessa, the owner of /etc/security/dev/st0 is changed to vanessa.

In the following example, after the user vanessa executes the allocate command with the device name st0, the owner of /etc/security/dev/st0 is changed to vanessa and the owner of the associated device-special files is now also vanessa. Lastly, user vanessa now has permission to read and write the files.

untouchable% whoami
vanessa
untouchable% allocate st0
untouchable% ls -lg /etc/security/dev/st0
-rw------- 1 vanessa staff 		      0 Dec 6 15:21 /etc/security/dev/st0
untouchable% ls -la /devices/sbus@1,f8000000/esp@0,800000
.
.
.
crw------- 1 vanessa 18,  4 May 12 13:11 st@4,0:
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:b
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:bn
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:c
.
.
.
crw------- 1 vanessa 18,  4 May 12 13:11 st@4,0:u
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:ub
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:ubn
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:un