POSIX.1E Auditing, v 0.1
Copyright 1999, Robert Watson

Please read LICENSE for licensing information.

This is a first pass at implementing POSIX.1E auditing support.  This file
include information on its bugs/features, and installation.  The posix1e
cross-platform mailing list may be subscribed to by sending email to
posix1e-request@cyrus.watson.org; the posting address is
posix1e@cyrus.watson.org.  Questions concerning the FreeBSD implementation
should be sent to robert+freebsd@cyrus.watson.org.

Bugs and/or Features
--------------------

The major components are:

o Kernel patches to add audit hooks for a few sample syscalls
o Kernel source to add /dev/audit and queueing mechanism
o Include file for kernel and userland, sys/audit.h
o Library with auditing calls defined in standard, libposix1e
o Audit daemon to listen on /dev/audit and move audit records into a log file
o Test utilities and audit_cat program
o Man pages for the above
o Liberal license and hopefully portable code, leaving aside the actual
  kernel code itself, and the auditd interface to it.

This is a first initial release, so it does not include:
o Any guarantees of functionality
o Extensive testing before release
o Audit hooks for all syscalls
o The device number is officially allocated, by the syscalls are not.
o Any profiling or performance testing to improve performance

Some features are not yet implemented, or may be buggy.  Where possible, this
is mentioned in the man pages for the related API call or program.  Here's
a brief overview:
o The aud_rec_to_text call does not yet know how to print all audit records,
  or even all parts of any audit records.  It is also poorly implemented, and
  should be redone.
o audit_free may behave poorly if handed a pointer it doesn't know what to do
  with.
o As mentioned above, few syscalls are actually audited, although the calls
  to implement this are available.  The way in which to do this should be
  discussed, but currently involves one macro per syscall.  Because audit
  records are generated even on syscall failure, this might require fairly
  extensive hooking of the syscall; furhter attention is clearly required.
o The Audit ID is currently just a copy of the process's effective UID.  The
  spec discusses how this is probably not appropriate, while easiest to
  implement.  Some alternative should be considered.

Installation
------------

Auditing support requires that you patch your kernel source, add some new
files to your kernel, and modify your kernel configuration file to add
appropriate options for POSIX.1E.  Additionally, you'll need to build 
libposix1e, the userland support library, as well as the audit daemon and
tool set that rely on it.  This code was based on 4.0-CURRENT of FreeBSD,
and has been tested against snapshots from late February and early March,
1999.

1. Kernel Files and Patches

cd /usr/tmp/audit				# or wherever you untarred
cp sys/kern/kern_audit.c /usr/src/sys/kern
cp sys/sys/audit.h /usr/src/sys/sys
cd /usr/src/sys
patch < /usr/tmp/audit/kernel.patch		# or wherever you untarred

2. Configure a New Kernel

Modify your kernel config file (often in /usr/src/sys/i386/conf) to add
the following option:

	options         "_POSIX_AUD"            # POSIX.1e Auditing

config your kernel, and rebuild (remember to make depend!).  Install your
new kernel.

3. Build libraries

Because new syscalls have been added, you'll need to rebuilt libc.  You'll
also need to build libposix1e, which contains support functions for the
auditing code (and is the bulk of the code).  This will also result in the
installing of a lot of useful man pages.  This code relies on
/usr/include/sys/audit.h, which is normally installed from /usr/src/sys/sys
at some point or another during the building of libc.

To build libposix1e, cd to /usr/tmp/audit/libposix1e, and just type make.
If you have problems, it's probably because audit.h isn't in place.  Do a
make install once it's built.

4. Build daemon and utilities

These rely on the availability of libposix1e, so the previous step must have
completed.  Cd to /usr/tmp/audit/auditd, do a make and make install.  If
desired, cd to /usr/tmp/audit/text/audit_cat and do a make.

5. Created /dev/audit

A patch for /dev/MAKEDEV is included, but it's easier to just do

mknod audit     c 120 0; chmod 400 audit

Devfs support is included, so /dev/audit should show up automatically if
you are using devfs, once you have rebooted.

6. Reboot and test

Reboot.  Auditing is by default disabled until the audit daemon is started.
This is to prevent resources from being consumed queueing the records until
they have somewhere to go.  Once booted, start /usr/sbin/auditd.  Assuming
all went well, your system is now being audited.  You can use
test/audit_cat/audit_cat -f /var/log/audit.log to watch audit logs as
they get entered in the system.  Because very few syscalls are currently
audited, and because the record->text conversion routine isn't very useful
yet, this won't be very enlightening.  To stop auditing, kill the audit
daemon.  /var/log/audit.log can grow very quickly.
