audit_filters(5)audit_filters(5)NAMEaudit_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
Page 1
audit_filters(5)audit_filters(5)
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
Page 2
audit_filters(5)audit_filters(5)
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:
Page 3
audit_filters(5)audit_filters(5)
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 ALSOaudit(1M), sat_select(1M), sat_reduce(1M), satd(1M).
IRIX Admin: Backup, Security, and Accounting
Page 4
