How to add a new audit event

Most system calls are considered “auditable” events, meaning that they are security-relevant and of interest to audit consumers. Here is the process for adding the required auditing for a new (or existing) system call:

Each possible event in the system is assigned a unique event identifier, prefixed with AUE_. Most system calls will have an AUE_ event name similar to the system call name, such as AUE_LISTEN, AUE_CLOSE, etc. Compat system calls or semantically identical system calls will share the same identifier – for example, all variants on the fstat(2) system call use the same AUE_FSTAT identifier.

If an existing BSM event appears to be a good match for the new system call in sys/bsm/audit_kevents.h. If so, use that event. If not, contact RobertWatson for assistance as it will need to be added in the OpenBSM before being merged to the FreeBSD base source tree. This is necessary to avoid allocating conflicting events with other systems that use OpenBSM, so the OpenBSM version of the file is considered authoritative.

Some system calls are not considered auditable, and may simply use AUE_NULL. However, this is unusual, as most system calls involve some sort of access control.

The syscalls.master file format has an audit identifier for each system call. Make sure to find all instances in all files, such as compat32, etc. Make sure to rebuild the sysent vector.

It is often desirable to audit arguments passed to a system call, not just that the system call occurred. This is typically done using a series of type-based macros:

AUDIT_ARG(fd, args->fd);

Possible types can be found in src/sys/security/audit/audit.h; contact RobertWatson if you require additional types.

When audit records are written to disk (or sent to processes), they are converted from an in-kernel data structure to the BSM format. This is done on a per-event type basis in audit_bsm.c:kaudit_to_bsm(). Each supported event identifier appears once in the switch, and for each expected (or optional) argument, the type is converted to a BSM token and added to the in-progress record. Contact RobertWatson if you need any advice here.

Test by configuring auditing of the event, generating the system call, and viewing the trail (or using an auditpipe) to confirm that the system call and any required arguments are properly captured in the trail.