https://github.com/mandiant/macos-unifiedlogs

A cross platform parser for Apple UnifiedLogs!
https://github.com/mandiant/macos-unifiedlogs

apple dfir forensics macos rust

Last synced: 4 months ago
JSON representation

A cross platform parser for Apple UnifiedLogs!

• Host: GitHub
• URL: https://github.com/mandiant/macos-unifiedlogs
• Owner: mandiant
• License: apache-2.0
• Created: 2022-08-18T17:33:30.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2025-08-08T15:57:20.000Z (5 months ago)
• Last Synced: 2025-08-08T17:48:55.969Z (5 months ago)
• Topics: apple, dfir, forensics, macos, rust
• Language: Rust
• Homepage:
• Size: 554 KB
• Stars: 265
• Watchers: 14
• Forks: 26
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# macos-unifiedlogs

A simple Rust library that can help parse the macOS Unified Log files.

Unified Logs were introduced in macOS version 10.12 (Sierra, 2016). Part of

Apple's goal to create a unified log format for all Apple products. They exist

on macOS, iOS, watchOS, tvOS. The Unified Logs replace many of the old log

formats Apple used. This library can be used to parse these log files.\

Data that is currently extracted includes:

- Process ID

- Thread ID

- Activity ID

- Log Message

- Timestamp (Intel and ARM supported)

- Effective User ID (EUID)

- Log Type

- Event Type

- Library

- Subsystem

- Category

- Process

- Raw message - Message extracted from UUID file

- Message entries - Message parts from tracev3 file. Combines with Raw message

  to get the Log Message

- Library UUID

- Process UUID

- Boot UUID

- Timezone

## Running

An example binary is available to download

- `unifiedlog_iterator` - Can parse a logarchive into a JSOL or CSV file. It can also parse the logs

  on a live system. The output file will be quite large

## Limitations

Its been tested against millions of log entries. However, due the complexity of

the Unified Log format there are some limitations:

1. No printf style error code lookup support. This library does not do any error

   code lookups for log messages. The native `log` command on macOS supports

   error code lookups when it encounters printf style `%m` messages.\

   For example the log message: 'Failed to open file, error: %m'\

   a. This Library outputs:

   ```

   Failed to open file, error: 1

   ```

   b. The macOS Log command outputs:

   ```

   Failed to open file, error: no such file or directory

   ```

2. This library supports most custom objects in log messages. However, unsupported objects will be base64 encoded

# References

- https://github.com/ydkhatri/UnifiedLogReader

- https://github.com/libyal/dtformats/blob/main/documentation/Apple%20Unified%20Logging%20and%20Activity%20Tracing%20formats.asciidoc

- https://eclecticlight.co/2018/03/19/macos-unified-log-1-why-what-and-how

- https://www.crowdstrike.com/blog/how-to-leverage-apple-unified-log-for-incident-response