Date: Tue, 28 Mar 2006 15:15:59 +0000 (GMT) From: Robert Watson <rwatson@FreeBSD.org> To: trustedbsd-audit@TrustedBSD.org Subject: Defining an API for audit filter modules Message-ID: <20060328150017.U19236@fledge.watson.org>
next in thread | raw e-mail | index | archive | help
Recently as part of the audit3 work, I added a new facility, audit pipes, to
the FreeBSD kernel. Audit pipes are synthetic devices that appear in /dev,
and allow direct access to the the BSM audit record stream without dealing
with the complexities of accessing the trail via the file system. This avoids
locating the trail files, parsing the files to seek to current events, dealing
with file ownership and rotation issues, synchronizing with the audit daemon,
etc. It also moves us in the direction of avoiding having to commit the
records to disk at all if live analysis (such as intrusion detection) is the
goal of the logging, rather than producing a reliable trail for later use.
Audit pipes, in particular, offer lossy delivery of discete records: the
application can set the maximum queue depth, and track overflows (drops), etc.
In order to make audit pipes more accessible and immediately useful for
application developers, I have recently prototyped an audit filter daemon and
audit filter API. The goal of this work is to allow developers to produce
"pluggable modules" to a standard module API, which will be presented audit
records as they arrive via a live audit pipe (or potentially other source,
such as a socket). The daemon provides both the I/O engine and execution
context for BSM record management: the shared objects simply have to present
an API to the daemon that it can use to submit records to for examination and
handling.
Right now, the module API defined in audit_filter.h is quite limited:
typedef int (*audit_filter_attach_t)(void **instance, int argc, char *argv[]);
Called when a module is attached by the daemon, in order to allow the filter
to register state (via 'instance'), accept arguments (via 'argc' and
'argv'), and optionally to reject attachment if the circumstances aren't
right.
typedef int (*audit_filter_reinit_t)(void *instance, int argc, char *argv[]);
Called when the auditfilterd configuration file is changed, resulting in the
arguments for a module changing. The new arguments are presented via 'argc'
and 'argv'. If an error is returned, the module is detached.
typedef void (*audit_filter_record_t)(void *instance, struct timespec *ts,
int token_count, const tokenstr_t *tok[]);
Called when an audit record is available for inspection by the module. The
record is pre-parsed into an array of token structures using au_fetch_tok().
typedef void (*audit_filter_bsmrecord_t)(void *instance, struct timespec *ts,
void *data, u_int len);
Called when an audit record is available for inspection by the module. The
record is presented in BSM bytestream, as some modules may wish to perform
their own BSM handling rather than relying on the parsing performed using
the libbsm routine.
typedef void (*audit_filter_detach_t)(void *instance);
Called when the module is being detached, in order to allow the module to
free any state, close files, etc.
This API will appear in OpenBSM 1.0a6 in the next week or so, once the code
has stabilized a bit more. However, the purpose of this e-mail isn't just to
draw your attention to this new part of OpenBSM, but also to solicit feedback.
In particular, I'm interested in two sorts of feedback:
(1) Comments on the API components thus far defined. I do currently provide
instance state, although a module could currently as easily use its own
global state. I did this to allow for the possibility of a module being
loaded more than once at a time with different arguments, although that is
currently not supported. However, maybe there's more that needs to be
done here.
(2) Comments on future API components. One of the things I'd like to do is
add an interest filter mechanism so that modules can push interest into
the daemon, and eventually the kernel, to control the set of records
gathered. An easy obvious direction would be to allow the specification
based on mechanisms already present via pre-selection: i.e., the request a
mask of event classes based on audit identity. You can imagine more
complicated things, and ideas on how far to take this would be welcome.
Are there other useful things that are clearly missing for an application
you may have in mind?
Thanks,
Robert N M Watson
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060328150017.U19236>