Skip to content

Audit logs

logga collects three distinct sets of logs:

  • Process execution logs, which we simply call audit logs.
  • Authentication, privilege escalation, and other system-related audit logs, which we collectively call access logs.
  • Unified logs, which filters & persists requested macOS unified logs.

Several actors can trigger process execution events:

  • User running a command, such as cat myfile.txt
  • User running a script, e.g. bash script.sh
  • Daemons running commands / scripts / binaries (LaunchDaemon / LaunchAgents)
  • Applications running commands / scripts
  • Scripts running scripts or commands
  • Usually, anything that calls execve or posix_spawn

Process execution events generate a large log volume, so we wanted to handle them separately from the less verbose access logs (hence the separate files and log rotation rules). Each process execution triggers an audit log event. Please note that the event timestamp doesn't indicate when the process execution happened but rather when the event was generated. However, the difference should be only a few milliseconds.

Log structure

timestamp - string

Event timestamp.

log - object

Parent key wrapping the log payload.

command - string

The command to be run.

args - array

The command arguments.

exec_path - string

The execution path before symlink resolution. This is the path argument to execve or posix_spawn, or the interpreter from the shebang line for scripts run through the shell script image activator.

script - string

Script being executed by interpreter. This field is only valid if a script was executed directly and not as an argument to the interpreter (e.g. ./foo.sh not /bin/sh ./foo.sh)

cwd - string

Current working directory at execution time.

env - array

The environment variables belonging to the process.

username - string

Username executing the process.

group - string

Group the username belongs to.

tty - string

The TTY the executed process is associated with. If the process wasn't executed interactively, the value will be unknown.

audit_token - object

Audit token of the process which stores process information.


auid - int

The audit user ID for the calling process.

egid - int

The effective group ID for the calling process.

euid - int

The effective user ID for the calling process.

gid - int

The group ID for the calling process.

group - string

The human readable group name for the calling process.

pid - int

The pid of the process.

uid - int

The user ID for the calling process.

username - string

The human readable username for the calling process.

parent_audit_token - object

The audit token of the parent process which stores information of the parent process.


auid - int

The audit user ID for the parent process.

egid - int

The effective group ID for the parent process.

euid - int

The effective user ID for the parent process.

gid - int

The group ID for the parent process.

group - string

The human readable group name for the parent process.

pid - int

The pid of the parent process.

uid - int

The user ID for the parent process.

username - string

The human readable username for the parent process.

responsible_audit_token - object

Audit token of the process responsible for this process, which may be the process itself in case there is no responsible process or the responsible process has already exited.


auid - int

The audit user ID for the calling process.

egid - int

The effective group ID for the calling process.

euid - int

The effective user ID for the calling process.

gid - int

The group ID for the calling process.

group - string

The human readable group name for the calling process.

pid - int

The pid of the process.

uid - int

The user ID for the calling process.

username - string

The human readable username for the calling process.