top of page
Search

Investigating macOS File System Events: The Hidden Forensic Trail

  • Apr 2
  • 4 min read

Ever wondered how macOS keeps track of file system changes?

Deep within the system lies a powerful yet often overlooked artifact—the .fseventsd directory. This little-known database logs file system modifications, making it invaluable for forensic investigations. Let’s dive into how it works and how you can leverage it for file activity tracking.


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

What is the .fseventsd Directory?

Each time you connect a volume (like a USB drive) to a Mac, the system creates a .fseventsd directory at the root level.

This directory functions as the File System Events Store Database, recording changes to files and directories on that volume. macOS services like Spotlight and Time Machine rely on this data to detect new or modified files efficiently.


The .fseventsd directory contains:

  • Gzipped log files: These are sequentially named with no extensions, recording system events.

  • The fseventsd-uuid file: A unique identifier for the database, which remains persistent on hard drives but changes frequently on external USB devices.

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


I know you will ask question Dean, how are u able to open the MAC .fseventsd directory in windows

Acquiring a full forensic image is ideal in investigations, but it's not always practical.

In one case, I was assisting a client located in another part of the country, making it impossible to collect a full disk image remotely.

Additionally, when individuals with limited forensic expertise are tasked with image collection, errors can occur, leading to incomplete or compromised evidence.


To address this challenge, I leveraged two powerful forensic artifact collection scripts:



These scripts automate the collection of critical forensic artifacts, ensuring consistency and reducing the risk of errors.


For instance, in this specific case, I used UAC to extract key forensic data from a macOS system. The script provided sufficient output for a thorough analysis without requiring full disk imaging.

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


Why is this Important for Investigators?

Forensic analysts can extract and analyze .fseventsd data to reconstruct file system activity, including:


✅ Identifying file creations, modifications, and deletions

✅ Tracing USB usage and external drive activities

✅ Recovering deleted files through metadata remnants


However, there are some caveats:

  • If the system crashes or is powered off abruptly, the .fseventsd data may be lost.

  • The database format has evolved over time, and Apple doesn’t publicly document all changes.

  • Non-HFS+ volumes may contain the directory but lack database logs.


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


Extracting and Analyzing FSEvent Data

Since .fseventsd files are gzipped, root access is required to extract and view them.


You can start by listing the attributes: (On Live System)

ls -la .fseventsd/

To unzip and inspect them:

sudo gunzip -c /.fseventsd/fseventsd-uuid

While the logs aren’t easily readable, you can use strings to extract human-readable filenames and paths:

sudo strings /.fseventsd/fseventsd-uuid

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


Automating the Analysis with Python

Instead of manually parsing logs, forensic analysts often use the FSEventsParser tool.


This Python script(For MAC or python) as well .exe( For Windows) Avaliable:

  • Extracts and decodes .fseventsd logs

  • Converts data into a SQLite database and CSV file for structured analysis


First we talk about Python script:

To use it:

git clone https://github.com/dlcowen/FSEventsParser
cd FSEventsParser
python3 fsevents_parser.py -d /path/to/fseventsd

A live system.

python3 FSEParser_V4.1.py -s /.fseventsd -t folder -o /some_folder -c test_case -q report_queries.json

If you are a window person like me lets talk about .exe

To use it (On Collected artifact using UAC)

C:\Users\Akash's\Downloads\FSEParser_V4.0_Windows_x64>FSEParser_V4.exe -s .fseventsd -t folder -o "C:\Users\Akash's\Downloads"

An image file.

FSEParser_V4.exe -s E:\001-My_Source_Image.E01 -t image -o E:\My_Out_Folder -c Test_Case

An attached external device or mounted volume/image.

FSEParser_V4.exe -s G:\.fseventsd -t folder -o E:\My_Out_Folder -q report_queries.json

Output:

Sqlite:- you can open with SqliteDB
Tsv File you can open with Eric Zimmerman tool Timeline explorer

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


Using Inspector for Advanced Processing

Forensic tools like Cellebrite Inspector come with built-in FSEvents parsers. When analyzing a system image,

navigate to: ➡ System | System Logs in the left sidebar ➡ Use the filter icon to refine event searches

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


Real-World Example: Tracking File System Events

Imagine investigating a USB thumb drive where a user created several directories and moved files. The .fseventsd logs would reveal:


  • Mount event: The moment the drive was connected.

  • Folder creations: Including renaming from default names like untitled folder.

  • File additions: Such as installer DMGs and images being copied.

  • Document edits: Tracking temporary .DocumentRevisions files before saving.

  • Deletion tracking: Differentiating between files moved to .Trashes (recoverable) and those permanently deleted.


Note the .DS_Store is shown. This means the user added these files using the Finder GUI window.

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


Time Stamps in FSEvents Data

One major limitation: FSEvents logs don’t store timestamps per event. However, we can estimate timestamps using:


  • The created/modified timestamps of the .fseventsd gzip files.

  • Neighboring ASL log timestamps.

  • Application-specific logs (e.g., chat message archives).


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



Conclusion: A Powerful Yet Overlooked Artifact

The .fseventsd directory provides a wealth of forensic insights into file system activities on macOS. While not a perfect timeline solution, it serves as a powerful artifact for tracking file movements, external drive activity, and even partial recovery of deleted files. Whether using a Python script or forensic tools like Inspector, leveraging this data can be crucial in digital investigations.

🔎 Want to try it out? Check out the FSEventsParser tool on GitHub: https://github.com/dlcowen/FSEventsParser.

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


 
 
 

Comments

bottom of page