Making Sense of macOS Logs(Part1): A User-Friendly Guide

If you've ever had to analyze logs from different systems, you know how frustrating it can be to correlate events across multiple time zones. Logs from different sources store timestamps in various formats, and some tools even output timestamps in local system time instead of UTC.

And If i talk about MAC

One tool that presents this challenge is praudit, which reads BSM audit logs and outputs timestamps in the local system time. To get accurate results, you must know the original time zone of the system before interpreting the log data.

--------------------------------------------------------------------------------------------------------

A Quick Fix: Changing Time Zone in Terminal

One simple trick for investigators is temporarily changing the Terminal's time zone.

This can be done using:

export TZ="UTC"

This adjustment ensures logs are displayed in UTC for consistency. The change only lasts for the current session, so once you exit the Terminal, it reverts back to the system's original time zone.

--------------------------------------------------------------------------------------------------------

Next Question is where to Find macOS Logs?

macOS stores logs in several locations, categorized into system logs, user logs, and application logs.

System Logs	Other Logs
/private/var/log	/Library/Logs
- Common Unix Logs	- User Logs
- Apple System Log (ASL)	- ~/Library/Logs
- Audit BSM Logs	- Application Specific
/var/db/diagnostics (& /uuidtext/)	- /Library/Application Support/<app>
- Unified Logs	- /Library/Logs

-----------------------------------------------------------------------------------------------------------------

Next question is what is the macOS Log Formats?

Most macOS logs follow the Standard Unix Log Format, which looks like this:

MMM DD HH:MM:SS Host Service: Message

One thing to note: this format doesn’t always include the year or time zone, making it harder to pinpoint exact events. However, most logs are stored in plaintext, making them easy to read.

-----------------------------------------------------------------------------------------------------------------

UAC Script collecting Logs

If you have seen the screenshot log is in .gz and .bz2 format

Next question will be How to Deal with Compressed Logs?

Old macOS logs are compressed using bzip2 or gzip to save space. You can decompress and merge logs using these commands:

For Bzip2 Logs:

bzcat system.log.{5..0}.bz2 > system_all.log

For Gzip Logs:

gzcat system.log.{5..0}.gz > system_all.log

This creates a single log file where events are arranged from oldest to newest, making it easier to analyze.

Merging Current Log Files

After decompressing old logs, you might want to merge them with the latest logs:

cat system.log >> system_all.log

This ensures you have a complete log timeline for investigations

-----------------------------------------------------------------------------------------------------------------

First Log we are going to Talk about are ASL Logs

ASL is basically known as Apple System Logs. Unlike standard plaintext logs, ASL files are stored in a proprietary binary format, requiring specialized tools for interpretation.

Where to Find ASL Logs

Post macOS version 10.5.6, ASL logs are stored in:

/private/var/log/asl/

The logs can be accessed through Console.app or the syslog command-line tool.

Key Characteristics of ASL Logs

Binary format: Identified by the signature ASL DB in the first six bytes of the file.
Log retention: System logs are retained for seven days, while logs related to user sessions (utmp, wtmp, lastlog) persist for one year.
File Naming Convention:
- Format: YYYY.MM.DD.[UID].[GID].asl
  Special files:
  - BB (Best Before): Contains login records for a given month and are kept for a year.
  - AUX (Auxiliary): Introduced in macOS 10.8+, these directories store additional text-based data referenced by ASL logs.

UAC Script Logs

Extracting and Viewing ASL Logs

Since ASL logs are in binary format, they require the syslog command for human-readable output. You can specify different output formats:

Output Formats:

bsd: Similar to system.log.
std: Default format with priority levels.
raw: Displays log messages in key-value pairs.
xml: Outputs logs as an XML property list.

Example Commands:

View logs in UTC time and raw format: (To view into Terminal)
syslog -T utc -F raw -d /var/log/asl
Extract ASL logs and convert them into a readable format: (To view into txt file)
syslog -F std -d /var/log/asl > asl_logs.txt

Key Fields in ASL Logs (raw format view in terminal)

Each log entry contains various attributes that can provide insights into system activity. Some of the most useful fields include:

Time: Timestamp of the record.
Host: System hostname.
Sender: Process or service that generated the log.
PID: Process ID.
UID/GID: User and group IDs.
Level: Priority level of the message.
Message: The actual log message.
Session: Associated session (managed by launchd).
ASLAuxTitle: Typically labeled "Full Report."
ASLAuxURL: URL linking to additional auxiliary logs.

Working with Archived Logs

ASL logs, like other system logs, undergo log rotation. Older logs are compressed using bzip2 or gzip. To decompress and merge archived logs:

bzcat system.log.{7..0}.bz2 > merged_system.log
cat system.log >> merged_system.log

This command stitches together log files from oldest to newest, creating a unified log for analysis.

-----------------------------------------------------------------------------------------------------------------

Second Log we are going to Talk about are Unified Logs

A New Era of Logging

With macOS 10.12 and iOS 10, Apple introduced Unified Logging, a major overhaul that replaced the traditional Apple System Logs (ASL) and Syslog.

This new system provides a consistent logging experience across macOS, iOS, watchOS, and tvOS, making it easier for developers and forensic analysts to work with log data efficiently.

Unlike the older log formats, which stored logs in plaintext or simple binary files, Unified Logging uses a structured binary format stored in:

/var/db/diagnostics/ (main log storage)
/var/db/uuidtext/ (referenced data)

(or you can check /private/var/db/)

The log files themselves have a .tracev3 extension, which requires specialized tools to interpret.

Collecting Unified Logs

Apple provides the log collect command to gather system logs efficiently. When run with root privileges, this command generates a structured logarchive bundle that includes all relevant log files.

Command to Collect Logs:

log collect

This command outputs a system_logs.logarchive folder containing

Bundled .tracev3 files
Referenced data from /var/db/uuidtext/

If you're analyzing a system image where log collect isn't possible, you can manually create a log archive:

cp -R /private/var/db/uuidtext/ /private/var/db/diagnostics/ logs.logarchive

/usr/libexec/PlistBuddy -c "Add :OSArchiveVersion integer 4" logs.logarchive/Info.plist

Without this Info.plist file, macOS won’t recognize the manually created archive.

Viewing Logs in Console.app

The easiest way to explore collected logs is via Console.app, Apple’s built-in log viewer. Simply open the system_logs.logarchive file in Console, and you’ll see logs categorized by time, process, and severity level.

Note: Capture logs in real-time using the log collect command. Because of reboot some logs might be lost

Parsing Logs with log show (Live System)

For command-line users, the log show command allows for deeper analysis of .tracev3 files.

Viewing System Logs:

log show

This outputs system logs in chronological order but excludes info and debug messages by default. To include them, use:

log show --info --debug

Filtering Logs with Predicates

One of the most powerful features of Unified Logging is its filtering capabilities using the

--predicate argument. You can narrow down logs based on specific conditions:

Example: Find All Error Messages

log show --predicate 'messageType == "Error"'

Example: Find Logs from a Specific Process

log show --predicate 'processImagePath CONTAINS "Safari"'

Other Useful Filters:

eventType: Filters by event type (Log, Trace, Activity)
eventMessage: Filters log message text
messageType: Filters by log level (Info, Debug, Error, Fault)
subsystem: Filters by system component (e.g., “com.apple.network”)
category: Filters by log category

Filter log events using logical statements

(AND/OR/NOT/</>/=/CONTAINS/BEGINSWITH/TRUE/FALSE, etc.)

With these filters, analysts can efficiently extract valuable insights from massive log datasets.

------------------------------------------------------------------------------------------------------------

Parsing Unified log on Window

If you've collected macOS logs using a tool like UAC and need to analyze them on a Windows system,

you might wonder—how do you efficiently parse these logs? Worry not, I’ve got you covered!

Introducing Unified Log Reader

A fantastic tool created by Yogesh Khatri, Unified Log Reader allows you to extract and analyze macOS logs on Windows. You can find the tool here:

🔗 Unified Log Reader GitHub Repository

Installation & Usage

Download the Unified Log Reader tool from the link above.
Run the following command to parse your collected logs:

UnifiedLogReader.exe -f SQLITE "E:\Output for testing\uac-Deans-Mac.local-macos-20250222225422\[root]\private\var\db\uuidtext" "E:\Output for testing\uac-Deans-Mac.local-macos-20250222225422\[root]\private\var\db\diagnostics\timesync" "E:\Output for testing\uac-Deans-Mac.local-macos-20250222225422\[root]\private\var\db\diagnostics" "C:\Users\Akash's\Downloads"

Output:

Understanding the Command Arguments

uuidtext_path → Path to the uuidtext folder (e.g., /var/db/uuidtext).
timesync_path → Path to the timesync folder (e.g., /var/db/diagnostics/timesync).
tracev3_path → Path to a tracev3 file or a folder containing tracev3 logs (e.g., /var/db/diagnostics).
output_path → The folder where the parsed logs will be saved.

Notes:

If you have a .logarchive file, set the uuidtext_path to the .logarchive folder. The timesync folder is located within it.
The tool supports different output formats:
- SQLITE (Recommended for structured analysis)
- TSV_ALL (Tab-separated format)
- LOG_DEFAULT (Standard log format)

This method enables you to analyze macOS logs efficiently on Windows, making forensic investigations much easier. 🚀

-----------------------------------------------------------------------------------------------------------------

Third Log we are going to Talk about are Audit Logs

The macOS Audit Logs, stored in (/private/var/audit/ or /var/audit/ check both), are a goldmine of information that can help security professionals track events like logins, privilege escalations, and system modifications. However, these logs aren’t your typical plain-text files; they use a structured binary format and require special tools to read them

What are BSM Audit Logs?

macOS uses the Basic Security Module (BSM) Audit Logs, a system originally developed by Sun Microsystems and later maintained by TrustedBSD. These logs help ensure security compliance by recording detailed system activities.

Unlike traditional log files in /var/log/, these audit logs are found in /var/audit/ and store data in a binary format, making them harder to tamper with.

Filename Structure

Each log file follows a specific naming convention based on timestamps:

Audit Trail Files: YYYYMMDDHHMMSS.YYYYMMDDHHMMSS
Current Log File: Symbolic link named current pointing to the active log.
not_terminated: Files that were not terminated properly due to a system error, or the file was otherwise inaccessible..
Crash Recovery Logs: Files ending in .crash_recovery (generated after a system or audit crash).

Collected using UAC Script

Configuration Files: How Auditing Works ( /etc/security/)

The auditing behavior in macOS is controlled by configuration files stored in /etc/security/. These files determine what gets logged and how long the logs are retained.

Key Configuration Files

audit_class – Defines event classifications (e.g., login/logout, system changes).
audit_control – Specifies audit settings:
- dir: Location of audit logs (/var/audit/).
- flags: Specifies which events are logged.
- minfree: Minimum disk space required for audit logs.
- policy: Defines global audit policies.
- filesz: Maximum file size for logs.
- expire-after: Log retention period based on time or size.
audit_user – Customizes auditing per user.
audit_event – Lists auditable events with unique event IDs.
- eventnum: Unique number for the event
- eventname: Event Name
- description: Event Description
- eventclass: Event class (see audit_class)

Interpreting Audit Logs

Audit logs aren’t human-readable by default, so you need special tools to analyze them. +

1. Viewing Audit Logs with praudit

The praudit command prints audit logs in readable formats. Example:

praudit -xn /var/audit/*
    or
sudo praudit -xn /var/audit/20250226082421.not_terminated > /Users/deanwinchester/Desktop/audit.log

-x prints logs in XML format.
-n prevents conversion of user and group IDs to names.

2. Filtering Logs with auditreduce

Need to extract specific log events? Use auditreduce:

auditreduce -m AUE_lw_login /var/audit/* | praudit
             or 
sudo auditreduce -m AUE_lw_login /var/audit/20250226082421.not_terminated | praudit

Output

Lets understand the output:

First Part:

header, 128, 11, loginwindow login, 0, Wed Feb 26 00:25:24 2025, + 721 msec

header → The start of an audit event.
128 → Event record size.
11 → Event version.
loginwindow login → The process responsible for the login (GUI-based login).
0 → Indicates no special flags.
Wed Feb 26 00:25:24 2025, + 721 msec → Timestamp of the login event.

Second Part

subject_ex, deanwinchester, root, wheel, deanwinchester, staff, 152, 100006, 50331650, 0.0.0.0

subject_ex → The user and group context of the action.
deanwinchester → The user who logged in.
root → The effective user ID (root privileges were used at some point).
wheel → The user group (admin privileges).
deanwinchester → The real user performing the action.
staff → The user’s group.
152 → The process ID (PID) of the login session.
100006 → Audit session ID.
50331650 → Terminal session ID.
0.0.0.0 → The source IP address (in this case, local login).

Third Part

return, success, 0

return → Status of the event.
success → Indicates the login was successful.
0 → No errors.

Fourth Part

identity, 1, com.apple.loginwindow, complete, , complete, 0x0e6dce00ff9c249a49f9dde396

identity → The authentication method used.
1 → Likely represents a local user login.
com.apple.loginwindow → The process responsible for the login.
complete → Authentication was fully completed.
0x0e6dce00ff9c249a49f9dde396 → A unique identifier for the session.

Summary

This log entry documents a successful login to the macOS system via the login window (GUI-based login). The user deanwinchester logged in locally, and the authentication process completed successfully.

3. Searching for Suspicious Activity

To find all authentication failures:

auditreduce -m AUE_auth_fail | praudit

To track when a user switches to root:

auditreduce -m AUE_su | praudit

Why Are macOS Audit Logs Important?

Audit logs play a crucial role in security monitoring, forensics, and compliance. They help:

✅ Detect unauthorized access attempts.

✅ Investigate suspicious activities.

✅ Ensure compliance with security regulations.

✅ Provide forensic evidence in incident response cases.

-----------------------------------------------------------------------------------------------------------------

Conclusion

macOS logs may seem complex at first, but they offer powerful insights into activities. With tools security analysts can uncover hidden threats and ensure system integrity.

If you're serious about macOS security, mastering these logs is a must! 🚀

Got any questions or want to see more examples? Let’s discuss!

---------------------------------------------Dean-------------------------------------------------------

A Quick Fix: Changing Time Zone in Terminal

Next Question is where to Find macOS Logs?

-----------------------------------------------------------------------------------------------------------------

Next question is what is the macOS Log Formats?

-----------------------------------------------------------------------------------------------------------------

If you have seen the screenshot log is in .gz and .bz2 format

Next question will be How to Deal with Compressed Logs?

For Bzip2 Logs:

For Gzip Logs:

Merging Current Log Files

-----------------------------------------------------------------------------------------------------------------

Where to Find ASL Logs

Key Characteristics of ASL Logs

Extracting and Viewing ASL Logs

Output Formats:

Example Commands:

Key Fields in ASL Logs (raw format view in terminal)

Working with Archived Logs

-----------------------------------------------------------------------------------------------------------------

A New Era of Logging

Collecting Unified Logs

Command to Collect Logs:

Viewing Logs in Console.app

Parsing Logs with log show (Live System)

Viewing System Logs:

Filtering Logs with Predicates

Example: Find All Error Messages

Example: Find Logs from a Specific Process

Other Useful Filters:

Introducing Unified Log Reader

Installation & Usage

Understanding the Command Arguments

Notes:

-----------------------------------------------------------------------------------------------------------------

What are BSM Audit Logs?

Filename Structure

Configuration Files: How Auditing Works ( /etc/security/)

Key Configuration Files

Interpreting Audit Logs

1. Viewing Audit Logs with praudit

2. Filtering Logs with auditreduce

Summary

3. Searching for Suspicious Activity

Why Are macOS Audit Logs Important?

-----------------------------------------------------------------------------------------------------------------

Conclusion

Comments