OpenBSM auditing on Mac OS X

Way back in 10.3.x, Apple submitted Mac OS X and Mac OS X Server to the National Information Assurance Partnership for Common Criteria certification. Common Criteria certification means that the the covered hardware and software has been tested and evaluated to make sure that it meets an established set of requirements for security and data protection. 10.3.6 and 10.3.6 Server were tested and were found to meet Evaluation Assurance Level 3 (EAL3) for Common Criteria certification.

As part of that certification effort, a new piece of software appeared from Apple: the Common Criteria Tools audit software. This software was OpenBSM, which is an open source implementation of Sun’s Basic Security Module (BSM) security audit API and file format. From 10.3.x – 10.5.x, this software needed to be installed and configured separately. As of 10.6.x and 10.7.x, it’s installed along with the OS. In fact, if you’re running 10.6.x and 10.7.x or their Server equivalents, it’s running now on your box unless you went in and turned it off. If you’re interested in learning more, see below the jump.

The good news was that this software (potentially) records all events on your Mac or Mac server, which would be invaluable to a forensic examination of a compromised box.

The bad news was that the audit logs themselves weren’t sent to syslog, but instead were saved in BSM’s own binary file format. Also, the files themselves had a unique file name scheme, where the complete timestamp of the beginning time and the complete timestamp of the end time were used as the file name. Consequently, the filenames look like this:

The log currently in use is usually easy to identify, as it’s the one named something like 20120108210134.not_terminated.

What’s being logged and to where?

What’s being logged depends on how /etc/security/audit_control is configured. On my 10.7.2 laptop, /etc/security/audit_control looks like this:


#
# $P4: //depot/projects/trustedbsd/openbsm/etc/audit_control#8 $
#
dir:/var/audit
flags:lo,aa
minfree:5
naflags:lo,aa
policy:cnt,argv
filesz:2M
expire-after:10M
superuser-set-sflags-mask:has_authenticated,has_console_access
superuser-clear-sflags-mask:has_authenticated,has_console_access
member-set-sflags-mask:
member-clear-sflags-mask:has_authenticated


The first value (dir:) specifies where the audit logs are being stored. By default, they’re stored in /var/audit.

The second value listed (flags:) is for audit flags. These tell the system how to record those events which are audited for all users on the machine (i.e. the events that can be tied back to a specific user.) The flags themselves are usually two letter combinations, which in turn represent system calls. Here’s a partial listing of them:


no = no_class - Null value for turning off event preselection
fr = file_read - Read of data, open for reading
fw = file_write - Write of data, open for writing
fa = file_attr_acc - Access of file attributes: stat, pathconf
fm = file_attr_mod - Change of file attributes: chown, chmod, flock
fc = file_creation - Creation of file
fd = file_deletion - Deletion of file
cl = file_close - File being closed after reading or writing
pc = process - Process operations: fork, exec, exit
nt = network - Network events: bind, connect, accept
ip = ipc - System V IPC operations
na = non_attrib - Nonattributable events
ad = administrative - Administrative actions
lo = login_logout - Login and logout events
ap = application - Application-defined event
io = ioctl - ioctl system call
ex = exec - program execution
to = other - Miscellaneous (your system shrugging its shoulders and saying "I saw it, but don't know what it is.")
all = all - All flags set


To be honest, trying to fine tune the flags is hard so I recommend using the great catch-all of flags: all. That way, you know you’re getting everything.

Note: If you’re using flags: all, be aware that this will cause your audit software to dump a large amount of data into the current audit log.

The third value listed (minfree:) defines the minimum free-space level on the disk for the audit software. This is a percentage value, so that the auditing software can be told to do something if free space on the boot drive drops below that amount. Once this minimum percentage is hit, the auditing function runs the /etc/security/audit_warn script. You should edit this script to perform whatever functions you deem necessary.

The fourth value listed (naflags:) is for nonattributable flags. These tell the system how to record those events which can’t be tied back to a specific user. Once again, I recommend using the great catch-all of naflags: all if you want to make sure you’re getting everything. Same warning as above, using all will cause the audit software to record a LOT of data to your audit logs.

The fifth value listed (policy:) is a bit of mystery to me. The FreeBSD man pages explain what they do, but a lot seems to not be implemented at this time.

The sixth value (filesz:) defines the maximum size that an individual audit log can grow to. Once that limit is hit, the audit process closes out the file and starts a new log file.

Values for the disk space used are numbers with the following suffixes:

B – Disk space used in Bytes.

K – Disk space used in Kilobytes.

M – Disk space used in Megabytes.

G – Disk space used in Gigabytes.

The seventh value (expire-after:) specifies when audit log files will expire and be removed. This may be after a time period has passed since the audit file was last written to, when the aggregate of all the audit files have reached a specified size or a combination of both. If no expire-after parameter is given then audit log files will not expire and be removed by the audit control system.

Values for the audit log file age are numbers with the following suffixes:

s – Log file age in seconds.

h – Log file age in hours.

d – Log file age in days.

y – Log file age in years.

Values for the disk space used are numbers with the following suffixes:

B – Disk space used in Bytes.

K – Disk space used in Kilobytes.

M – Disk space used in Megabytes.

G – Disk space used in Gigabytes.

The suffixes on the values are case sensitive. You can also use AND and OR values to determine when audit log files expire. In the case of AND, both values must be met before the audit file can be removed. In the case of OR, either condition may expire the log file.

For example:

expire-after: 60d AND 1G

Setting this value will expire files that are older than 60 days but only if 1 gigabyte of disk space total is being used by the audit logs. However, setting this value will expire files if the directory is over 1 GB in size or those files in the directory that are older than 60 days:

expire-after: 60d OR 1G

All the values below expire-after are a complete mystery to me and I don’t know what they do. If someone does know, please let me know in the comments.

Reading the audit logs

Reading the audit logs can be a bit of a challenge, as they’re stored in BSM’s binary file format. Fortunately, there is now an application named Audit Explorer available from the Mac App Store that helps simplify this process a lot. NetSquared, the makers of Audit Explorer, have also posted videos to show you sample audit trails for particular events to help get you started with analyzing your audit files.

As /var/audit‘s permissions are set so that only root has access, you may need to copy out the files that you want to analyze to a location that your user account can access.