FSE_Dump v3.1.4

Bump deps
Rework pipelines
Rebuild with newest rust

Full Changelog: v3.1.3...v3.1.4

FSE_Dump v3.1.3

Fix docs
Bump deps
Rebuilt with new rust security release

Full Changelog: v3.1.2...v3.1.3

FSE_Dump v3.1.2

What's Changed

• Bump deps
• Build with new rust version

Full Changelog: v3.1.1...v3.1.2

FSE_Dump v3.1.1

Bump deps + rebuild with new rust

Full Changelog: v3.1.0...v3.1.1

FSE_Dump v3.1.0

Even though they're not very forensically sound, we now include the timestamps of the specific log file each entry was found in. For "uniques" there is an optional flag that tracks the earliest/latest time that a path was seen.

What's Changed

• Track times by @lespea in #475

Full Changelog: v3.0.0...v3.1.0

FSE_Dump v3.0.0

Release Notes: fse_dump v3.0.0

🎉 Major Release - Breaking Changes

This is a major release with significant enhancements to filtering capabilities and breaking changes to command-line flags.

---

🚨 Breaking Changes

Watch Command Flag Changes

The watch command has had its short flags modified to avoid conflicts with the new filtering options:

Old Flag	New Flag	Description
-f, --format	-o, --format	Output format selection
-p, --pretty	-P, --pretty	Pretty-print JSON output

Migration Guide:

# Old (v2.x)
fse_dump watch -f json -p

# New (v3.x)
fse_dump watch -o json -P

Filter Flag Replacement

The simple --filter flag has been replaced with more powerful filtering options:

Old Flag	New Flags	Description
--filter <STRING>	-p, --path-filter <REGEX>	Now uses regex patterns

Migration Guide:

# Old (v2.x)
fse_dump watch --filter "/Users/alice/"

# New (v3.x)
fse_dump watch -p "^/Users/alice/"

---

✨ New Features

Enhanced Filtering System

The filtering system has been completely redesigned with powerful new capabilities:

1. Path Filtering with Regex (-p, --path-filter)

Filter events by file path using regular expressions:

# Filter for PDF files
fse_dump dump --json output.json -p "\.pdf$"

# Filter for specific directory
fse_dump dump --json output.json -p "^/Users/alice/"

# Filter for multiple file types
fse_dump dump --json output.json -p "\.(doc|pdf|xlsx?)$"

2. Flag-Based Filtering

Two new filtering modes for FSEvents flags:

Any Flags Mode (-f, --any-flags): Include events with ANY of the specified flags

# Show files that were either created OR removed
fse_dump dump --json output.json -f Created Removed

# Show any permission or attribute changes
fse_dump dump --json output.json -f PermissionChange ExtendedAttrModified

All Flags Mode (--all-flags): Include events with ALL of the specified flags

# Show only files (not folders) that were modified
fse_dump dump --json output.json --all-flags FileEvent Modified

# Show folders that were created
fse_dump dump --json output.json --all-flags FolderEvent Created

3. Combined Filters

Filters can be combined for powerful queries:

# Modified PDFs in Documents folder
fse_dump dump --json output.json \
  -p "/Documents/.*\.pdf$" \
  -f Modified

# Created or removed files in system directories
fse_dump dump --json output.json \
  -p "^/(System|Library)/" \
  -f Created Removed

# All permission changes on specific files
fse_dump dump --json output.json \
  -p "/etc/passwd" \
  --all-flags FileEvent PermissionChange

Supported FSEvents Flags

The following flags are now available for filtering (case-insensitive):

Flag	Description
FolderEvent	Event occurred on a folder
Mount	Volume was mounted
Unmount	Volume was unmounted
EndOfTransaction	End of a transaction
LastHardLinkRemoved	Last hard link to file removed
HardLink	Hard link created
SymbolicLink	Symbolic link created
FileEvent	Event occurred on a file
PermissionChange	Permissions were changed
ExtendedAttrModified	Extended attributes modified
ExtendedAttrRemoved	Extended attributes removed
DocumentRevisioning	Document versioning event
ItemCloned	Item was cloned
Created	File/folder was created
Removed	File/folder was removed
InodeMetaMod	Inode metadata modified
Renamed	File/folder was renamed
Modified	File/folder was modified
Exchange	Files exchanged
FinderInfoMod	Finder info modified
FolderCreated	Folder was created

Filters Apply to All Commands

The new filtering system is available in both dump and watch commands:

# Watch for document modifications
fse_dump watch -o json -p "\.(doc|pdf|txt)$" -f Modified

# Dump with filters
fse_dump dump --json output.json -p "/Users/" -f Created

---

🔧 Improvements

Code Quality & Testing

• Extensive test coverage: Added comprehensive unit tests for:

  • Flag parsing and lookup (case-insensitive)
  • Record filtering (path and flag-based)
  • Compression options validation
  • Command-line option parsing
  • Unique path generation

• Enhanced documentation: Added detailed inline documentation and examples throughout the codebase

• Performance optimizations:

  • Improved flag string capacity calculations
  • Optimized filter matching logic
  • Better memory allocation strategies

Documentation Enhancements

• Completely rewritten README: Now includes:

  • Quick start guide
  • Comprehensive usage examples
  • Filter usage patterns
  • Installation instructions for all scenarios
  • Complete flag reference table

• Better CLI help: Improved command-line help text with clearer descriptions

Flag Module Improvements

• New flag_id() function for case-insensitive flag name lookup
• Better flag string caching mechanism
• Comprehensive flag parsing tests

---

🛠️ Internal Changes

New Modules & Structures

• RecordFilter struct: Complete rewrite of the filtering system

  • Replaces simple string matching with regex patterns
  • Adds flag-based filtering with AND/OR logic
  • Efficient bitwise flag matching

• FilterOpts struct: Command-line options for filtering

  • Unified filtering interface across commands
  • Proper conflict detection (any-flags vs all-flags)

Code Organization

• Added comprehensive module-level documentation
• Better separation of concerns between parsing and filtering
• Improved error messages for invalid flags

---

🚀 Usage Examples

Real-World Scenarios

Security Monitoring: Track sensitive file access

fse_dump watch -o json -P \
  -p "/(etc|private)/.*" \
  -f PermissionChange Modified Removed

Development Monitoring: Watch source code changes

fse_dump watch -o json \
  -p "\.(rs|py|js|go)$" \
  -f Modified Created

Forensic Analysis: Dump file deletions from last 7 days

fse_dump dump --days 7 --json deletions.json \
  -f Removed \
  --all-flags FileEvent

Document Tracking: Monitor office documents

fse_dump watch -o csv \
  -p "\.(docx?|xlsx?|pptx?|pdf)$" \
  -f Created Modified Removed

---

📊 Statistics

• 10 files changed: 2,697 insertions, 259 deletions
• 500+ lines of tests added
• README expanded from ~100 to ~500+ lines
• 20+ new test cases

---

📝 Migration Checklist

If you're upgrading from v2.x, update your scripts:

• Replace -f with -o in watch commands (format flag)
• Replace -p with -P in watch commands (pretty flag)
• Update --filter to -p or --path-filter (now uses regex)
• Consider adding flag-based filters for more precise event selection
• Review regex patterns to ensure proper escaping

---

🙏 Acknowledgments

• AI pair programming assistance via GitHub Copilot for documentation and testing
• Dependabot for dependency updates
• Community feedback and contributions

---

📅 Release Information

• Version: 3.0.0
• Release Date: 2026-01-14
• Previous Version: 2.2.1
• Commits Since Last Release: 10 commits

What's Changed

Full Changelog: v2.2.1...v3.0.0

v2.2.1

What's Changed

• Bump deps
• Rebuild with newest rust

Full Changelog: v2.2.0...v2.2.1

v2.2.0

There was a bug in the logic that determined what files should be processed, which has been fixed.

Also bumped the deps, etc.

Full Changelog: v2.1.11...v2.2.0

v2.1.11

• Fix CI/CD

Full Changelog: v2.1.10...v2.1.11

v2.1.10

What's Changed

• Bump deps
• Build with new rust

Full Changelog: v2.1.9...v2.1.10