Home > Common Criteria, Mac administration, Mac OS X, OpenBSM > OpenBSM auditing on Mac OS X

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:

Screen Shot 2012-01-30 at 3.02.31 PM

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 $

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.

  1. Dan O'Donnell
    January 30, 2012 at 11:14 pm

    The maker of Audit Explorer says that it is possible to access the audit trail files from within AE, but it has not been made clear how to actually do that. When it becomes clear this should be a big help.

  2. Steve
    February 29, 2012 at 10:09 pm

    This is a really interesting article, out of interest how large do these logs grow, whats the theory behind rotating them etc?

    • March 2, 2012 at 10:43 am

      Steve, depending on what’s running, these logs can grow enormously. For example, back in the Retrospect 6.x days, I would get multi-GB audit logs on my Retrospect backup server on a weekly basis because the audit software was recording all the I/O calls that Retrospect made while pulling backups from clients.

      When configuring this on a server, my rotation scheme is usually based on a daily rotation regardless of log file size.

  3. av
    April 27, 2012 at 11:08 pm

    NB on the policy flag — there are two important ones that I’ve found interested on MacOS. cnt indicates audit system should run even in case of failure. The other commonly used flag is argv, which causes command line arguments to the execve(2) system call to be audited as part of command execution. Thanks for the article!

  4. Jonathan
    June 12, 2012 at 8:19 am


    Never heard of OpenBSM before I read your post. How do you audit the audits? 😉 Do you use Audit Explorer on daily basis to go through the audits looking for odd behaviour or do you have another approach?

    Do you personally use OpenBSM on your desktops/ notebooks or just at work?


  5. Jenson
    June 19, 2015 at 10:35 pm

    Audit Explorer is no longer available in App Store. Do you have any recommended alternatives? It sounds to me we have an advanced audit system but can’t read the audit files. What good is that?

  6. September 22, 2015 at 1:25 am

    2nd Jenson’s request. Is there another method or app beside audit Explorer?

  7. Al Deaderick
    March 24, 2016 at 3:32 pm

    Sad about Audit Explorer. You can read the audit logs in the command line with the built-in praudit tool.

    to see your current log:
    sudo praudit /var/audit/current
    see the man page for more info.

    December 14, 2017 at 7:37 pm

    would love to know if there is a GUI product to read the audit files

  9. Lucas
    February 2, 2018 at 1:37 pm

    Amazing post!!! Loved it!

  10. tep
    April 19, 2019 at 5:59 pm

    I’ve tried setting expire-after to: ’60d AND 1G’ and ’60d OR 1G’ and both settings allow the logs to grow to enormous sizes…

    • Arthur
      October 16, 2019 at 6:45 pm

      @tep I have the same issue. I had over 300G in my var/audit folder. No documentation on how to force the expiration except audit -e. What initiates that process?

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: