Managing Audit Records on Local Systems (Tasks)

The default plugin, audit_binfile, creates an audit trail. The trail can contain large amounts of data. The following tasks show you how to work with all this data.

Managing Audit Records on Local Systems (Task Map)

The following task map points to procedures for selecting, analyzing, and managing audit records.

How to Display Audit Record Definitions

The auditrecord command displays audit record definitions. The definitions provide the audit event number, audit class, selection mask, and record format of an audit event.

• Put the definitions of all audit event records in an HTML file.

  The -a option lists all audit event definitions. The -h option puts the list in HTML format.

  % auditrecord -ah > audit.events.html

  ---

  Tip - When you display the HTML file in a browser, use the browser's Find tool to find specific audit record definitions.

  ---

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

Example 28-27 Displaying the Audit Record Definitions of a Program

In this example, the definition of all audit records that are generated by the login program are displayed. The login programs include rlogin, telnet, newgrp, and the Secure Shell feature of Oracle Solaris.

% auditrecord -p login
...
login: logout
  program     various              See login(1)
  event ID    6153                 AUE_logout
  class       lo                  (0x0000000000001000)
...
newgrp
  program     newgrp               See newgrp login
  event ID    6212                 AUE_newgrp_login
  class       lo                  (0x0000000000001000) 
...
rlogin
  program     /usr/sbin/login      See login(1) - rlogin
  event ID    6155                 AUE_rlogin
  class       lo                   (0x0000000000001000)
...
/usr/lib/ssh/sshd
  program     /usr/lib/ssh/sshd    See login - ssh
  event ID    6172                 AUE_ssh
  class       lo                   (0x0000000000001000)
...
telnet login
  program     /usr/sbin/login      See login(1) - telnet
  event ID    6154                 AUE_telnet
  class       lo                   (0x0000000000001000)
  …

Example 28-28 Displaying the Audit Record Definitions of an Audit Class

In this example, the definitions of all audit records in the pf class that was created in Example 28-10 is displayed.

% auditrecord -c pf

pfexec
  system call pfexec               See execve(2) with pfexec enabled
  event ID    116                  AUE_PFEXEC
  class       pf                   (0x0100000000000000)
      header
      path                    pathname of the executable
      path                    pathname of working directory
      [privileges]            privileges if the limit or inheritable set are changed
      [privileges]            privileges if the limit or inheritable set are changed
      [process]               process if ruid, euid, rgid or egid is changed
      exec_arguments
      [exec_environment]      output if arge policy is set
      subject
      [use_of_privilege]
      return

The use_of_privilege token is recorded whenever privilege is used. The privileges tokens are recorded if the limit or inheritable set is changed. The process token is recorded if an ID is changed. No policy option is required for these tokens to be included in the record.

How to Merge Audit Files From the Audit Trail

By merging the audit files from all the audit directories, you can analyze the contents of the entire audit trail.

Before You Begin

You must become an administrator who is assigned the Audit Review rights profile. For more information, see How to Use Your Assigned Administrative Rights.

1. Create a file system for storing merged audit files.

   To lessen the chance of reaching the limit of disk space, this file system should be in a different zpool from the file systems that you created in How to Create ZFS File Systems for Audit Files to store the original files.

2. Merge the audit records in the audit trail.

   Go to the directory for storing merged audit files. From this directory, merge the audit records into a file with a named suffix. All directories in the audit trail on the local system are merged and placed in this directory.

   # cd audit-storage-directory
   # auditreduce -Uppercase-option -O suffix

   The uppercase options to the auditreduce command manipulate files in the audit trail. The uppercase options include the following:

   -A

   Selects all of the files in the audit trail.

   -C

   Selects complete files only.

   -M

   Selects files with a particular suffix. The suffix can be a machine name, or it can be a suffix that you have specified for a summary file.

   -O

   Creates an audit file with 14-character timestamps for both the start time and the end time, with the suffix suffix in the current directory.

   -R pathname

   Specifies to read audit files in pathname, an alternate audit root directory.

   -S server

   Specifies to read audit files from the specified server.

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

Example 28-29 Copying Audit Files to a Summary File

In the following example, an administrator who is assigned the System Administrator rights profile copies all files from the audit trail into a merged file on a different file system. The /var/audit/storage file system is on a separate disk from the /var/audit file system, the audit root file system.

$ cd /var/audit/storage
$ auditreduce -A -O All
$ ls /var/audit/storage/*All
20100827183214.20100827215318.All

In the following example, only complete files are copied from the audit trail into a merged file. The complete path is specified as the value of the -0 option. The last component of the path, Complete, is used as the suffix.

$ auditreduce -C -O /var/audit/storage/Complete
$ ls /var/audit/storage/*Complete
20100827183214.20100827214217.Complete

In the following example, by adding the -D option, the original audit files are deleted.

$ auditreduce -C -O daily_sys1.1 -D sys1.1
$ ls *sys1.1
20100827183214.20100827214217.daily_sys1.1

How to Select Audit Events From the Audit Trail

You can filter audit records for examination. For the complete list of filtering options, see the auditreduce(1M) man page.

Before You Begin

You must become an administrator who is assigned the Audit Review rights profile. For more information, see How to Use Your Assigned Administrative Rights.

• Select the kinds of records that you want from the audit trail, or from a specified audit file.

  auditreduce -lowercase-option argument [optional-file]

  argument

  Specific argument that a lowercase option requires. For example, the -c option requires an argument of an audit class, such as ua.

  -d

  Selects all of the events on a particular date. The date format for argument is yyymmdd. Other date options, -b and -a, select events before and after a particular date.

  -u

  Selects all of the events attributable to a particular user. The argument is a user name. Another user option, -e, selects all of the events attributable to an effective user ID.

  -c

  Selects all of the events in a preselected audit class. The argument is an audit class name.

  -m

  Selects all of the instances of a particular audit event. The argument is an audit event.

  -o

  Selects by object type. Use this option to select by file, group, file owner, FMRI, pid, and other object types.

  optional-file

  Is the name of an audit file.

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

Example 28-30 Combining and Reducing Audit Files

The auditreduce 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 media.

# cd /var/audit/audit_summary
# auditreduce -O lo.summary -b 20100827 -c lo; compress *lo.summary

Example 28-31 Copying One User's Audit Records to a Summary File

In this example, the records in the audit trail that contain the name of a particular user are merged. The -e option finds the effective user. The -u option finds the login user.

$ cd /var/audit/audit_summary
$ auditreduce -e tamiko -O tamiko

You can look for specific events in this file. In the following example, what time the user logged in and out on Sept 7, 2010, your time, is checked. Only those files with the user's name as the file suffix are checked. The short form of the date is yyyymmdd.

# auditreduce -M tamiko -O tamikolo -d 20100907 -u tamiko -c lo

Example 28-32 Copying Selected Records to a Single File

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

# auditreduce -c lo -d 20100827 -O /var/audit/audit_summary/logins
# ls /var/audit/audit_summary/*logins
/var/audit/audit_summary/20100827183936.20100827232326.logins

How to View the Contents of Binary Audit Files

The praudit command enables you to view the contents of binary audit files. You can pipe the output from the auditreduce command, or you can read a particular audit file. The -x option is useful for further processing.

Before You Begin

You must become an administrator who is assigned the Audit Review rights profile. For more information, see How to Use Your Assigned Administrative Rights.

• Use one of the following praudit commands to produce the output that is best for your purposes.

  The following examples show praudit output from the same audit event. Audit policy has been set to include the sequence token.

  • The praudit -s command displays audit records in a short format, one token per line. Use the -l option to place each record on one line.

    $ auditreduce -c lo | praudit -s
    header,69,2,AUE_screenlock,,mach1,2010-10-14 08:02:56.348 -07:00
    subject,jdoe,root,staff,jdoe,staff,856,50036632,82 0 mach1
    return,success,0
    sequence,1298

  • The praudit -r command displays audit records in their raw format, one token per line. Use the -l option to place each record on one line.

    $ auditreduce -c lo | praudit -r
    21,69,2,6222,0x0000,10.132.136.45,1287070091,698391050
    36,26700,0,10,26700,10,856,50036632,82 0 10.132.136.45
    39,0,0
    47,1298

  • The praudit -x command displays audit records in XML format, one token per line. Use the -l option to place the XML output for one record on one line. The following listing divides two lines of output to fit on this printed page:

    $ auditreduce -c lo | praudit -x
    <record version="2" event="screenlock - unlock" host="mach1" 
         iso8601="2010-10-14 08:28:11.698 -07:00">
    <subject audit-uid="jdoe" uid="root" gid="staff" ruid="jdoe
        rgid="staff" pid="856" sid="50036632" tid="82 0 mach1"/>
    <return errval="success" retval="0"/>
    <sequence seq-num="1298"/>
    </record>

Example 28-33 Printing the Entire Audit Trail

With a pipe to the print command, the output for the entire audit trail goes to the printer. For security reasons, the printer has limited access.

# auditreduce | praudit | lp -d example.protected.printer

Example 28-34 Viewing a Specific Audit File

In this example, a summary login file is examined in a terminal window.

# cd /var/audit/audit_summary/logins
# praudit 20100827183936.20100827232326.logins | more

Example 28-35 Putting Audit Records in XML Format

In this example, the audit records are converted to XML format.

# praudit -x 20100827183214.20100827215318.logins > 20100827.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.

Example 28-36 Processing praudit Output With a Script

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

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

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

Troubleshooting

A message similar to the following indicates that you do not have enough privilege to use the praudit command:

praudit: Can't assign 20090408164827.20090408171614.sys1.1 to stdin.

Run the praudit command in a profile shell. You must become an administrator who is assigned the Audit Review rights profile. For more information, see How to Use Your Assigned Administrative Rights.

How to Clean Up a not_terminated Audit File

When anomalous system interruptions occur, the audit service exits while its audit file is still open. Or, a file system becomes inaccessible and forces the system to switch to a new file system. In such instances, an audit file remains with the string not_terminated as the end timestamp, even though the file is no longer used for audit records. Use the auditreduce -O command to give the file the correct timestamp.

Before You Begin

You must become an administrator who is assigned the Audit Review rights profile. For more information, see How to Use Your Assigned Administrative Rights.

1. List the files with the not_terminated string on your audit file system in order of creation.

   # ls -R1t audit-directory*/* | grep not_terminated

   -R

   Lists files in subdirectories.

   -t

   Lists files from most recent to oldest.

   -1

   Lists the files in one column.

2. Clean up the old not_terminated file.

   Specify the name of the old file to the auditreduce -O command.

   # auditreduce -O system-name old-not-terminated-file

3. Remove the old not_terminated file.

   # rm system-name old-not-terminated-file

Example 28-37 Cleaning Up Closed not_terminated Audit Files

In the following example, not_terminated files are found, renamed, then the originals are removed.

ls -R1t */* | grep not_terminated
…/egret.1/20100908162220.not_terminated.egret
…/egret.1/20100827215359.not_terminated.egret
# cd */egret.1
# auditreduce -O egret 20100908162220.not_terminated.egret
# ls -1t
20100908162220.not_terminated.egret Current audit file
20100827230920.20100830000909.egret Cleaned up audit file
20100827215359.not_terminated.egret Input (old) audit file
# rm 20100827215359.not_terminated.egret
# ls -1t
20100908162220.not_terminated.egret Current audit file
20100827230920.20100830000909.egret Cleaned up audit file

The start timestamp on the new file reflects the time of the first audit event in the not_terminated file. The end timestamp reflects the time of the last audit event in the file.

How to Prevent Audit Trail Overflow

If your security policy requires that all audit data be saved, prevent audit record loss.

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. Set a minimum free size on the audit_binfile plugin.

   Use the p_minfree attribute.

   The audit_warn email alias sends a warning when the disk space fills to the minimum free size. See Example 28-17.

2. Set up a schedule to regularly archive audit files.

   Archive audit files by backing up the files to offline media. You can also move the files to an archive file system.

   If you are collecting text audit logs with the syslog utility, archive the text logs. For more information, see the logadm(1M) man page.

3. Set up a schedule to delete the archived audit files from the audit file system.
4. Save and store auxiliary information.

   Archive information that is necessary to interpret audit records along with the audit trail. Minimally, you save the passwd, group, and hosts files. You also might archive the audit_event and audit_class files.

5. Keep records of which audit files have been archived.
6. Store the archived media appropriately.
7. Reduce the amount of file system capacity that is required by enabling ZFS compression.

   On a ZFS file system that is dedicated to audit files, compression shrinks the files considerably. For an example, see How to Compress Audit Files on a Dedicated File System.

   See also Interactions Between ZFS Compression, Deduplication, and Encryption Properties in Oracle Solaris 11.1 Administration: ZFS File Systems.

8. 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 contain only records for specified types of audit events. To extract summary files, see Example 28-30 and Example 28-32.