Unified Logs

Overview

The macOS Unified Logging System (ULS) is the system-wide structured logging infrastructure introduced in macOS 10.12 Sierra. It replaced the legacy Apple System Log (ASL) and syslog frameworks and is now the authoritative event record for the kernel, all Apple system frameworks, and most third-party applications. Every process on a modern macOS system writes to ULS; no other artifact offers the same breadth of cross-subsystem correlation.

Architecture

ULS has four physical components that together form a self-contained, decodable archive:

The tracev3 files contain compressed, binary-encoded log entries that reference format strings by UUID rather than embedding them. Rendering a human-readable message requires the uuidtext database for that UUID. The timesync anchors convert the Mach absolute time stored in each record to a calendar timestamp — without the correct anchor, timestamps cannot be recovered.

.logarchive bundles are self-contained: log collect copies all four components into a single directory bundle, making the bundle independently renderable on any macOS host.

Ring-Buffer Retention

The store is partitioned into priority tiers. The Persist/ tier survives reboots; the HighVolume/ tier is overwritten most aggressively.

On a typical active laptop the Persist tier retains approximately one to two weeks of events. Under sustained high activity the window may be as short as a few days. ULS is not a long-term audit log.

Forensic Significance

ULS is the only macOS artifact that can answer all of the following questions from a single source:

File Locations

All paths are under /var/db/ and protected by System Integrity Protection (SIP). Read access requires root on a live system. On a mounted disk image, standard read permissions apply once the image is attached with appropriate tools.

File Naming

tracev3 chunk files within each subdirectory carry a UUID-derived filename. The timesync directory contains one .timesync file per boot, named with a timestamp. There is no persistent sequential numbering analogous to FSEvents record files.

Subsystem Forensic Value

The table below maps the six predicate presets collected by macfor to the subsystems they target and their primary forensic use cases.

Critical Forensic Caveats

Predicate Presets

macfor renders six predicate-filtered NDJSON extracts. Each preset targets a specific forensic domain using an NSPredicate expression passed to log show --predicate.

Predicates are applied during log show rendering. They filter events before writing to NDJSON; no events outside the predicate are stored in the extract.

NDJSON Event Record Schema

Each line of a rendered NDJSON extract is a JSON object with the following fields:

message_type values error and fault represent unexpected conditions; fault indicates a programmer error at the source. Filtering to these levels first is a useful triage shortcut when reviewing a large extract.

macfor Collection Details

What Is Collected

The system.unifiedlogs plugin produces three artifacts:

Manifest Contents

The collection manifest (manifest.json) for this plugin records:

• log CLI version (from log version)
• Boot UUID (from logs.logarchive/Info.plist)
• Collection window start and end timestamps
• Per-file SHA-256 hashes for all raw store files
• File count and total bytes per directory tier
• Per-preset event counts and any preset-level errors

Collection Options

Requirements

Live collection requires root. The plugin detects privilege at runtime and emits a clear error if root is absent. Detection (macfor detect) reports the artifact as present even without root, so the privilege gap is visible in pre-collection reports.

macOS 10.15 Catalina through 15 Sequoia are supported. The plugin relies on Apple's log CLI, which Apple maintains for forward compatibility.

Investigation Recipes

Was a Specific Binary Allowed to Execute?

Use the exec preset, which captures AMFI verdicts and kernel-level execution events.

# Render the exec extract (macfor already does this during collection)
log show logs.logarchive \
  --style ndjson \
  --predicate '(subsystem == "com.apple.AMFI") OR (subsystem == "com.apple.kernel")' \
  --timezone UTC \
  | grep -i "mymalware"

In the NDJSON extract, look for message fields containing the binary path. AMFI messages include verdict strings such as allowing (permitted), denied (blocked), and Library Validation failed. A sequence of allowing verdict followed by execution with no subsequent crash indicates successful execution. A denied entry indicates SIP or AMFI blocked it.

Cross-reference with the xprotect preset if the binary was downloaded: a Gatekeeper assessment log entry will reference the same path within seconds of the AMFI verdict.

Which USB Devices Were Attached During a Suspicious Window?

Use the usb preset. Mass-storage devices produce IOUSBFamily attachment entries followed by USBMSC enumeration messages that carry vendor string, product string, and serial number.

# Filter usb.ndjson to a specific time window
cat unifiedlogs/events/usb.ndjson \
  | python3 -c "
import sys, json
for line in sys.stdin:
    e = json.loads(line)
    ts = e.get('timestamp','')
    if '2026-04-10T03' <= ts <= '2026-04-10T05':
        print(e['timestamp'], e['message'])
"

Key message patterns to look for in the usb extract:

Vendor/product strings from USBMSC messages can be correlated against the USB device history in the devices.bluetooth artifact and macOS's IORegistry for a complete attachment timeline.

Did Gatekeeper Quarantine or Block This Download?

Use the xprotect preset. Gatekeeper (syspolicy) and the quarantine LaunchServices subsystem emit assessment entries whenever a downloaded item is opened.

# Search xprotect extract for a specific filename
grep -i "SuspiciousInstaller.pkg" unifiedlogs/events/xprotect.ndjson \
  | python3 -c "import sys, json; [print(json.dumps(json.loads(l), indent=2)) for l in sys.stdin]"

Key syspolicy message patterns:

Combine the xprotect extract with the Quarantine Events database (~/Library/Preferences/com.apple.LaunchServices.QuarantineEventsV2) for the download URL and originating process. The two artifacts provide complementary views: the SQLite database records the download origin; ULS records what Gatekeeper decided.

Version Differences

Forward compatibility is inherited from Apple's log CLI, which Apple maintains across OS versions. New NDJSON fields from future macOS releases are absorbed into the extra passthrough map.

Known Limitations (v1)

Tool Support

References

• Apple log man page
• mandiant/macos-UnifiedLogs — Rust parser
• Reviewing macOS Unified Logs — Mandiant
• UnifiedLogReader — Yogesh Khatri
• SANS: macOS Unified Log Investigations
• Jonathan Levin — MacOS and iOS Internals, Vol. III
• Apple Platform Security — Logging
• MITRE ATT&CK: Indicator Removal — Clear macOS Logs (T1070.002)
• Related artifacts: FSEvents, TCC Database, Quarantine Events, XProtect