Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dlcowen/FSEventsParser

Parser for OSX/iOS FSEvents Logs
https://github.com/dlcowen/FSEventsParser

Last synced: about 2 months ago
JSON representation

Parser for OSX/iOS FSEvents Logs

Awesome Lists containing this project

README 

        
Overview

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



FSEvents files are written to disk by macOS APIs and contain historical records of file system activity that occurred for a particular volume. 

They can be found on devices running macOS and devices that were plugged in to a device running macOS. They are GZIP format, so you can also try carving for GZIPs to find FSEvents files that may be unallocated.



FSEventsParser can be used to parse FSEvents files from the '/.fseventsd/' on a live system or FSEvents files extracted from an image. 



Carved GZIP files from a macOS volume or a device that was plugged into a macOS system can also be parsed.



The parser outputs parsed information to tab delimited txt files and an SQLite database. Errors and exceptions are recorded in the exceptions logfile.



The report_queries.json file can be used to generate custom reports based off of SQLite queries. Use -q to specify the file's location when running the parser. 

You can download predefined SQLite queries from https://github.com/dlcowen/FSEventsParser/blob/master/report_queries.json.

Create your own targeted reports by editing the 'report_queries.json' file or just get default targeted reports including:

- UserProfileActivity

- UsersPictureTypeFiles

- UsersDocumentTypeFiles

- DownloadsActivity

- TrashActivity

- BrowserActivity

- MountActivity

- EmailAttachments

- CloudStorageDropBoxActivity

- CloudStorageBoxActivity

- DSStoreActivity

- SavedApplicationState

- RootShellActivity

- GuestAccountActivity

- SudoUsageActivity

- BashActivity

- FailedPasswordActivity

- iCloudSyncronizationActivity

- SharedFileLists



Requires

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

When the source type is an image DFVFS is required to run the script. Refer to https://github.com/log2timeline/dfvfs/wiki/Building.

Alternately, you can run the compiled version of FSEParser to avoid having to install any other dependancies. The latest compiled version can be downloaded here:



https://github.com/dlcowen/FSEventsParser/releases



Usage

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

        ==========================================================================

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

        ==========================================================================

        Usage: FSEParser_V4 -s SOURCE -o OUTDIR -t SOURCETYPE [folder|image] [-c CASENAME -q REPORT_QUERIES]



        Options:

          -h, --help         show this help message and exit

          -s SOURCE          REQUIRED. The source directory or image containing

                             fsevent files to be parsed

          -o OUTDIR          REQUIRED. The destination directory used to store parsed

                             reports

          -t SOURCETYPE      REQUIRED. The source type to be parsed. Available options

                             are 'folder' or 'image'

          -c CASENAME        OPTIONAL. The name of the current session,

                             used for naming standards. Defaults to 'FSE_Reports'

          -q REPORT_QUERIES  OPTIONAL. The location of the report_queries.json file

                             containing custom report queries to generate targeted

                             reports.



                             

Examples

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

A live system.

> sudo ./FSEParser_V4 -s /.fseventsd -t folder -o /some_folder -c test_case -q report_queries.json



Exported fsevent files

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



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



> sudo ./FSEParser_V4 -s /Volumes/USBDISK/.fseventsd -t folder -o /some_folder -c test_case -q report_queries.json



Notes

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

- Parsed records can be in excess of 1 million records.

- The script does not recursively search subdirectories in the source_dir provided. All FSEvents files including carved gzip if any must be placed in the same directory.

- Currently the script does not perform deduplication. Duplicate records may occur when carved gzips are also parsed.



Ouput Column Reference

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



event_id: The fsevent record ID in hex and decimal format. The record ID is assigned in chronological order.



node_id: Introduced in HighSierra. The file system node ID (stored in the catalog file for HFS+) of the record fullpath at the time the event was recorded. This value is empty for MacOS versions prior to High Sierra.



fullpath: The record fullpath.



type: The file type of the record fullpath/the event type:

- FileEvent

- FolderEvent

- HardLink

- SymbolicLink



flags: The changes that occurred to the record fullpath:

- Created

- Modified

- Renamed

- Removed

- InodeMetaMod

- ExtendedAttrModified

- FolderCreated

- PermissionChange

- ExtendedAttrRemoved

- FinderInfoMod

- DocumentRevisioning

- Exchange

- ItemCloned

- LastHardLinkRemoved

- Mount

- Unmount

- EndOfTransaction



approx_dates_plus_minus_one_day: Approximate dates (no times) that the event occurred. The date ranges were pulled using the name of Log files that have the Created flag within an FSEvents file. This value may or may not be off by one day due to timezone variances.



source: The fullpath of the FSEvents file that the record was parsed from.



source_modified_time: The FSEvents source file modified date in UTC.