martin carpenter

contents

solaris auditd plugin

2012/07/15

tags: solaris auditd

introduction

The Solaris Basic Security Model (BSM) audit daemon (auditd(1M)) provides a detailed, (potentially) off-host audit record of executed processes, file activity, logins/logouts, etc and can contribute to US DoD C2-class TCSEC certification.

The audit subsystem generates events. The configuration is chosen by the administrator to select only interesting events for that environment. These events are queued to configurable plugin event handlers defined in /etc/security/audit_control.

Solaris 10 provides two such plugins which are shared objects in /usr/lib/security:

• audit_binfile.so — default plugin; writes binary audit data to files.
• audit_syslog.so — optional; sends formatted messages to the LOG_AUDIT facility of syslogd(1M).

OpenSolaris/Solaris 11 provides a third:

• audit_remote.so — optional, transmits audit messages securely via a GSS authenticated session to a remote server.

If we could write our own plugin we could:

• Perform finer-grained triage on events before writing them to disk/syslog/remote (eg file read events just for /etc/shadow).
• Perform actions other than just writing to disk/syslog/remote.
• Avoid limitations in the current implementations (eg Solaris 1024 character syslog message limit).

private: keep out

Unfortunately the auditd(1M) plugin API in Solaris 10 and 11 is private. The functions that we need to implement are:

• auditd_plugin()
• auditd_plugin_close()
• auditd_plugin_open()

Their prototypes can be found in <security/auditd.h>.

The simplest way to understand these functions is to read the OpenSolaris implementations under usr/src/lib/auditd_plugins.

/*
 * auditd_plugin_open(), auditd_plugin() and auditd_plugin_close()
 * implement a replaceable library for use by auditd; they are a
 * project private interface and may change without notice.
 */

It looks like this API was going to be opened at some point but I wouldn't count on that today.

Other useful BSM functions are provided in libbsm(3LIB).

function synopsis

If that hasn't put you off, here is a quick synopsis of the three functions to be implemented.

auditd_plugin_open() initializes the plugin from the values defined in the audit_control(4) file:

auditd_rc_t auditd_plugin_open(
    const kva_t *kvlist,
    char **ret_list,
    char **error_text);

audit_plugin() processes one record from the audit subsystem. This is where the action happens.

auditd_rc_t auditd_plugin(
    const char *buffer,
    size_t buf_len,
    uint32_t sequence,
    char **error_text);

auditd_plugin_close() performs shutdown/cleanup operations for the plugin when the audit daemon terminates.

auditd_rc_t auditd_plugin_close(
    char **error_text);

gotchas

Implementing the above three functions is not difficult but there are some not-immediately-obvious things to be aware of:

• Unlike PAM these plugins aren't "stackable": a plugin either gets called for an event or it doesn't. You can't do any logic at the plugin configuration level.
• If you implement a plugin you MUST read the notes section of the proposed audit_plugin(3) manual page, in particular for details of what happens if the call to audit_plugin() blocks ("can cause the system to come to a standstill") and for the warning to avoid installing your own sighandlers. (Other points are dated).
• See the note in <security/auditd.h> regarding the fact that auditd_plugin_open() trashes its second and third arguments before return (dup before calling).
• Beware: threaded. See, for example, use of mutexes in audit_binfile's binfile.c
• Private interface. You may get eaten by a grue.

see also

• Oracle Solaris System Administration Guide: Security Services part no. 816–4557, Part VIII Oracle Solaris Auditing.
• audit_binfile(5)
• audit_remote(5)
• audit_syslog(5)
• audit_control(4)
• audit_user(4)