FSEvents (File System Events)

Overview

FSEvents (File System Events) is a macOS subsystem that records a chronological log of file system modifications at the volume level. The FSEvents daemon (fseventsd) monitors all file system changes and persists them as gzip-compressed binary records in hidden directories on each volume.

FSEvents is one of the most forensically valuable artifacts on macOS. It provides a historical record of file creation, deletion, modification, renaming, and metadata changes -- even for files that no longer exist. Unlike most forensic artifacts, FSEvents records persist across reboots and can survive attempts to delete individual files or clear browser histories.

The records do not contain timestamps directly. Instead, each event is assigned a monotonically increasing event ID per volume. Timeline reconstruction requires correlating event IDs with other timestamped artifacts.

Forensic Significance

File Locations

Directory Structure

/.fseventsd/
├── fseventsd-uuid                   # Volume UUID (plain text)
├── 0000000000000001                 # Event record file (gzip compressed)
├── 0000000000000002                 # Event record file (gzip compressed)
├── 0000000000000003                 # ...
└── ...

Record files are named with zero-padded hexadecimal event IDs. Each file contains gzip-compressed binary data with one or more pages of event records.

On macOS 10.15 (Catalina) and later with APFS volume groups, the system volume is read-only and the data volume at /System/Volumes/Data/ contains the active FSEvents store. Both locations should be checked during collection.

File Format

FSEvents files are gzip-compressed streams. After decompression, each file contains one or more pages. Each page has a 12-byte header followed by a sequence of variable-length records.

Page Header (12 bytes)

The magic bytes determine the record format version:

Record Format (Version 1)

Record Format (Version 2 / Version 3)

All multi-byte integers use little-endian byte order.

Gzip Stream Details

Each FSEvents record file is a gzip-compressed stream. Some files may contain multiple concatenated gzip members. A robust parser must handle multi-member gzip streams and continue processing even if a member is corrupted.

Key Fields for Analysis

Event Flags

Event flags are the most forensically important field. They are a bitmask indicating what happened to the item and what type of item it is.

Stream-Level Flags (Issues with the Event Stream)

Item Event Flags (What Happened)

Item Type Flags (What Type of Item)

Extended Flags (macOS 10.13+)

Multiple flags can be set simultaneously. For example, a file creation with content modification would have flags 0x00011100 (ItemCreated | ItemModified | ItemIsFile).

Path Field

The path field is a relative path from the volume root. It does not include the volume mount point. For example, a file at /Users/admin/Documents/report.pdf would be stored as Users/admin/Documents/report.pdf.

To reconstruct the full absolute path, the volume UUID from fseventsd-uuid must be resolved to a mount point.

Event ID

Event IDs are 64-bit monotonically increasing integers per volume. They serve as a sequencing mechanism rather than a timestamp. Key properties:

• Event IDs never repeat within a volume (unless the counter wraps, indicated by EventIDsWrapped flag).
• Gaps in event IDs between consecutive records indicate either event coalescing or system downtime.
• The file name of each FSEvents record file corresponds to the first event ID in that file.
• Event IDs can be correlated with other macOS artifacts that reference FSEvents IDs.

Timestamps

FSEvents records do not contain timestamps. This is a critical distinction from most other forensic artifacts. The event ID ordering provides sequence but not time.

Approaches for estimating timestamps:

1. File modification time: The modification time of each .fseventsd/ record file can approximate when events in that file were written.
2. Cross-artifact correlation: Match file paths in FSEvents against timestamped artifacts (Spotlight metadata, Unified Logs, browser history) to anchor events to a timeline.
3. Event ID interpolation: If two events can be anchored to timestamps via other artifacts, intermediate events can be roughly estimated through linear interpolation.

Analysis Notes

Volume UUID Resolution

Each volume's FSEvents store contains a fseventsd-uuid file with a UUID that uniquely identifies that volume. When analysing a system with multiple volumes, the UUID-to-volume mapping is essential for reconstructing full file paths.

Common volumes on modern macOS:

Common Investigation Patterns

Stream Issues

When UserDropped (0x02) or KernelDropped (0x04) flags are set on any record, it indicates that events were lost. This typically occurs during periods of extremely high file system activity. The MustScanSubDirs flag indicates that a directory needs a full rescan because individual events were coalesced.

These flags should be documented in forensic reports as they represent gaps in the evidence.

Parsing Considerations

• FSEvents files may have partial corruption. A forensic parser should recover as many records as possible rather than failing on the first error.
• The path field uses UTF-8 encoding. Non-ASCII filenames (especially those containing CJK characters or emoji) are common.
• Some older records may reference paths that no longer exist on the system.
• Record files are rotated by fseventsd based on size constraints, so older events are progressively pruned.

Version Differences

The version 3 format (3SLD) has been observed in recent macOS releases. It uses the same structure as version 2.

Tool Support

References

• Apple FSEvents Reference (Developer Documentation)
• FSEvents Forensics - Nicole Ibrahim (SANS)
• G-C Partners FSEventsParser
• mac_apt - macOS Artifact Parsing Tool
• macOS Forensics - FSEvents Analysis (Yogesh Khatri)
• Apple Open Source: fsevents.h header file