audit_filters(5)                                              audit_filters(5)


NAME
     audit_filters - using filter programs with the audit facility

DESCRIPTION
     Traditionally, the System Audit Trail (SAT) facility saves all selected
     audit records directly to a file with little additional processing.
     However, for some applications it would be useful to perform some kind of
     manipulation on the audit data before saving it to disk, or perhaps
     manipulate the data and not save it to disk at all.  This explains what
     needs to be done to perform these manipulations and the mechanisms that
     should be used to accomplish them.

   satd
     satd(1M) is the daemon responsible for saving audit data from the kernel
     in disk files.  In the default configuration it reads data directly from
     the kernel using a special system call and writes it to uniquely named
     files in the /var/adm/sat directory.  When satd receives a HUP signal, it
     automatically closes the current file that it is writing to and opens a
     new one.  In this default setup, the filenames are of the form
     sat_YYMMDDHHMM so they can be easily sorted and read in the order that
     they were produced.

     Because audit data is often considered precious, satd takes several
     measures to ensure that data is not lost.  First, it monitors the amount
     of free space available on the filesystem to which it is writing records.
     It is possible to configure satd to automatically switch to one or more
     alternate filesystems if the current filesystem is full, using several
     different configurable rotation policies.  In this arrangement, if all of
     the filesystems available to satd are full, it automatically brings the
     system down into single user mode.  During this time, audit records are
     written to an "emergency" file that is pre-allocated in the root
     filesystem when the audit subsystem is first started.  Note that if a
     system shutdown is undesirable when satd has run out of space, it is
     always possible to assign /dev/null as the last filesystem for satd to
     use.  satd normally logs all device/filesystem changes to SYSLOG.

   Using satd with filters
     Unfortunately, these elaborate disk management features can make it
     difficult for other software to reliably locate all of the audit data,
     such as for post-processing.  Indeed, in some cases these disk management
     features may be totally unnecessary, for example if the data is consumed
     and then immediately discarded by other post-processing software.
     Therefore, satd provides an option (-o) to write audit data directly to
     its standard output, thus allowing it to be piped directly to other
     software.  This can be done in addition to or in place of writing the
     data to disk.  An example of this would be the command:

          satd -o -f /var/adm/sat | myfilter

     Here, satd writes the audit data to files in the directory /var/adm/sat
     as well as directing them to the program myfilter.  myfilter is then free
     to do whatever processing is needed on the audit data (perhaps


     summarizing it, or sending it to some remote host).

     It is also possible that some of the audit data may need to be
     manipulated before it is written to disk, for example to perform special
     filtering or to augment certain data items.  Piping the data out to a
     filter would lose the disk management features of satd.  Therefore, satd
     provides another option (-i) that allows it to read audit data from its
     standard input rather than reading it directly from the kernel.  This
     way, satd can receive its audit data from a filter and still do its
     normal disk management.  Here is an example of how such a scheme might be
     set up:

          satd -o | myfilter | satd -i -f /var/adm/sat

     Here, satd -o pulls the audit data from the kernel and writes it directly
     to its standard output without bothering to write it to disk.  The
     myfilter program reads this audit data from its standard input, performs
     whatever processing is necessary, then writes the resulting data (which
     should still be in the form of standard audit records) to its own
     standard output.  Finally, the satd -i stage reads audit data from its
     standard input (rather than the kernel) and writes it out to files in the
     /var/adm/sat directory.  Note that if using satd as filters, all filters
     except for the first one should specify a -i option to indicate that no
     file header is present at the beginning of the input stream, and all
     filters except for the last one should specify a -o option to indicate
     that input records should be echoed to standard output.


   Writing filters for use with audit
     It is possible to set up more than one filter for use with audit data.
     With that in mind, there are several important points to remember when
     writing audit filters:

     *  Filter programs that consume all audit records (as opposed to "true"
        filters, which would pass at least some subset of their input to their
        standard output) should still have a mode that causes audit records to
        be copied to their standard output.  This allows other filters to be
        added after them in a pipe.  Notice that this implies that a filter
        program should not write anything but audit records to its standard
        output, at least when this "copy to stdout" mode is enabled.

     *  On the other hand, if a site's only application for the audit data is
        some filter that consumes all of the data (for example, a program that
        summarizes all of the audit data) then copying data to standard output
        would not be desirable, since it would likely end up being echoed to
        the console.  Therefore, the ability to copy audit records to stdout
        should probably be controlled with some sort of command line option.
        For consistency with satd, it might be nice to name this option -o.
        Alternatively, the filter could examine its stdout with stat(2) to
        determine if its standard output is a pipe; if so, it could assume
        that an additional filter is present and only then copy records to
        stdout.  This could simplify user installation procedures, although a


        command line option to force copying on or off might still be useful
        in case of unusual situations.

     *  When satd -o is first started, it writes a file header before it
        writes any audit records.  Filter programs should not do this.  In
        particular, satd -i does not expect to see a file header in its input.
        Filter programs should have an option to expect/not expect the file
        header when first started.  Only the first filter on the pipe would
        need to expect and discard the header.  To be consistent with satd,
        the default could be to expect/discard a header and not expect one if
        a -i option is specified.

     *  If using the satd -o/satd -i approach to preprocessing audit data
        before writing it to disk, bear in mind that satd -i expects raw audit
        records as input.  Only complete records should be added or deleted to
        the stream of audit data.  If modifying data inside an audit record,
        care should be taken not to modify the size or offset of any fields
        within the record.

   Invoking audit filters
     If the audit subsystem is installed and enabled, IRIX starts satd
     automatically at boot time using the /etc/init.d/audit script.  This
     script should not normally be modified.  Instead, the script looks for
     several files in the /etc/config directory to modify its behavior:

     satd.options   contains options that should be specified on the satd
                    command line.  If this file is missing or empty, the
                    default options of -f /var/adm/sat are used.  To
                    specifically supply no options to the satd command, this
                    file should contain only the string "<NONE>".

     satd.filter*   one or more files containing the command lines for filters
                    that should be connected in a pipeline to satd.  If one or
                    more of these files exist and are non-empty, satd is given
                    the -o option and is invoked in a pipeline formed from the
                    commands found in these files.  The pipe stages are
                    ordered according to the order that the ls command lists
                    these files.

     An example is in order.  Suppose the file /etc/config/satd.options
     contains this:

          -f /AUDITDIR -f /ALTDIR

     and /etc/config/satd.filter-1 contains this:

          sat_reduce -C sleep -C hostname -S access

     and /etc/config/satd.filter-2 contains this:


          satd -i -f /SATDIR

     Then satd is invoked as follows by /etc/init.d/audit:

          satd -o -f /AUDITDIR -f /ALTDIR | sat_reduce -C sleep -C hostname -S access | satd -i -f /SATDIR

     In this example, satd writes to /AUDITDIR, /ALTDIR and stdout, where
     audit records with the command "sleep", "hostname" and the system call
     "access" are filtered out. These audit records are then piped into satd
     which will be writing the filter audit records to /SATDIR.

SEE ALSO
     audit(1M), sat_select(1M), sat_reduce(1M), satd(1M).

     IRIX Admin: Backup, Security, and Accounting


                                                                        Page 4