fsmon 0.1.3

🌍 Select Language | 选择语言

• English
• 简体中文

Features

• Real-time Monitoring: Captures 8 core fanotify events (CREATE, DELETE, CLOSE_WRITE, ATTRIB, etc.)
• Process Attribution: Tracks PID, command name, and user for every file change — even short-lived processes like touch, rm, mv
• Recursive Monitoring: Watch entire directory trees with automatic tracking of newly created subdirectories
• Complete Deletion Capture: No more missing events during rm -rf — captures every file deleted in recursive operations
• High Performance: Written in Rust, <5MB memory footprint, zero-copy event parsing
• Flexible Filtering: Filter by time, size, process, user, and event type
• Multiple Formats: Human-readable, JSON, and CSV output
• Systemd Service: Install as systemd service for long-term auditing with auto-restart

Why fsmon

Ever needed to answer "Who modified this file?" on a Linux server? That's exactly what fsmon is for.

Traditional file monitoring tools give you events without context — fsmon bridges that gap by attributing every file change to its responsible process. Whether it's a rogue script, an automated deployment, or a misconfigured service, you'll know exactly what happened, when, and who (or what) caused it.

Quick Start

Prerequisites

• OS: Linux 5.9+ (requires fanotify FID mode)
• Filesystem: ext4, XFS, tmpfs (btrfs partial support)
• Build: Rust toolchain (cargo)

# Verify kernel version
uname -r  # requires ≥ 5.9

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Installation

# Build from source
git clone https://github.com/lenitain/fsmon.git
cd fsmon
cargo install --path .

# Or install from crates.io
cargo install fsmon

Important: Copy to system path for sudo usage:

sudo cp ~/.cargo/bin/fsmon /usr/local/bin/

Basic Usage

# Monitor a directory
sudo fsmon monitor /etc --types MODIFY

# Monitor with recursive watching
sudo fsmon monitor ~/myproject --recursive

# Install as systemd service for long-term auditing
sudo fsmon install /var/log /etc -o /var/log/fsmon-audit.log

# Query historical events
fsmon query --since 1h --cmd nginx

# Check service status
fsmon status

Examples

Investigate Configuration Changes

# Monitor /etc for modifications
sudo fsmon monitor /etc --types MODIFY --output /tmp/etc-monitor.log

# In another terminal, make a change
echo "192.168.1.100 newhost" | sudo tee -a /etc/hosts

# Query the results
fsmon query --log-file /tmp/etc-monitor.log --since 1h --types MODIFY

Track Large File Creation

# Watch for files larger than 50MB
sudo fsmon monitor /tmp --types CREATE --min-size 50MB --format json

# Trigger
dd if=/dev/zero of=/tmp/large_test.bin bs=1M count=100

Audit Deletion Operations

# Capture complete recursive deletion
sudo fsmon monitor ~/test-project --types DELETE --recursive --output /tmp/deletes.log

# Trigger
rm -rf ~/test-project/build/

# Output shows every file deleted (even in subdirectories)
[2026-01-15 16:00:00] [DELETE] /home/pilot/test-project/build/output.o (PID: 34567, CMD: rm)
[2026-01-15 16:00:00] [DELETE] /home/pilot/test-project/build (PID: 34567, CMD: rm)

Command Reference

fsmon monitor --help    # Real-time monitoring
fsmon query --help      # Query history logs
fsmon status            # Check systemd service status
fsmon stop              # Stop systemd service
fsmon start             # Start systemd service
fsmon install --help    # Install systemd service
fsmon uninstall         # Uninstall systemd service
fsmon clean --help      # Cleanup old logs

Technical Architecture

• fanotify (FID mode): Linux kernel-level file monitoring
• Proc Connector: Caches process info at exec() time for accurate attribution
• name_to_handle_at: Directory handle caching for complete deletion tracking
• Rust + Tokio: Async runtime with high concurrency

Event Types

Default captures 8 core events. Use --all-events for all 14.

Default Events (8):

Additional Events (6, via --all-events):

License

MIT License