FSEventsParser 3.1 Released

FSEventsParser 3.1 Released

By Nicole Ibrahim

G-C Partners' FSEventsParser python script 3.1 has been released. Version 3.1 now supports parsing macOS High Sierra FSEvents.

You can get the updated script here: https://github.com/dlcowen/FSEventsParser 

Prior versions of the script do not support High Sierra parsing, so it's important to upgrade to the current version of FSEventsParser.

Other recent updates include:

  • Better handling of carved gzip files has been added. Invalid record entries in corrupted gzips are now being excluded from the output reports.
  • Even more dates are being found using the names of system and application logs within each fsevent file. The dates are stored in the column 'approx_dates(plus_minus_one_day)' and indicates the approximate date or date range that the event occurred, plus or minus one day.
  • Script now reads a json file that contains custom SQLite queries to filter and export targeted reports from the database during parsing.

macOS High Sierra 10.13 and FSEvents

With the release of High Sierra, updates to the FSEvents API resulted in the following changes:
  • Magic Header: In macOS versions prior to 10.13, the magic header within a decompressed FSEvents log was '1SLD'. Beginning with 10.13, the magic header is now '2SLD'.
  • ItemCloned Flag: The ItemCloned flag was introduced with macOS 10.13.  When set, it indicates that the file system object at the specific path supplied in the event is a clone or was cloned. 
  •  File System Node ID: Beginning with 10.13, FSEvents records now contain a File System Node ID. 
    • e.g. If FSEvents were from an HFS+ formatted volume, this value would represent the Catalog Node ID.

FSEventsParser Database Report Views

Within the SQLite database, report views have been added for common artifacts. The report views are defined in the 'report_queries.json' file. They include:

  • Downloads Activity
  • Mount Activity
  • Browser Activity
  • User Profile Activity
  • Dropbox Activity
  • Email Attachments Activity
  • and more..
To access the report views, open the SQLite database generated by running the script using your SQLite viewer of choice. Expand "Views".

FSEventsParser Custom Reports

The FSEventsParser script now exports custom report views from the database during processing to individual TSV files.

The custom report views are defined in the file 'report_queries.json' which is also available on GitHub.

Users can modify the queries or add new ones to the json file using a text editor. Two examples are shown below: TrashActivity and MountActivity.

To add new queries to the json processing list, follow the json syntax shown below. Define the report views within the 'processing_list' array. To add a new item to the array, define:
1) 'report_name': The report/view name.
2) 'query': The SQLite query to be run.


  • The report name must be unique and must match the view name in the SQLite query. e.g.
    • 'report_name': 'TrashActivity'
    • 'query':'CREATE VIEW TrashActivity AS ....'

  • The query follows standard SQLite syntax, must be valid, and is stored in the json file as a single-line string value.

FSEventsParser Usage

All options are required when running the script. 

FSEParser v 3.1  -- provided by G-C Partners, LLC


  -h, --help        show this help message and exit
  -c CASENAME       The name of the current session, used for naming standards
  -q REPORTQUERIES  The location of the report_queries.json file containing custom report
                    queries to generate targeted reports
  -s SOURCEDIR      The source directory containing fsevent files to be parsed
  -o OUTDIR         The destination directory used to store parsed reports

 Below is an example of running the script.

For more information about FSEvents and how you can use them in your investigation visit http://nicoleibrahim.com/apple-fsevents-forensics/.

If you have any comments or questions, please feel free to leave them below.

Post a Comment