SMB Change Notification Monitor

A Python script that monitors file system changes on Windows SMB shares in real-time using the smbprotocol library. This tool demonstrates proper handling of SMB2 CHANGE_NOTIFY requests and manual parsing of FILE_NOTIFY_INFORMATION responses.

Features

• 🔄 Real-time monitoring of file/directory changes on SMB shares
• 📁 Comprehensive change detection (create, delete, modify, rename, etc.)
• 🛠️ Manual SMB2 response parsing to handle all action codes (including undocumented ones)
• 📋 Complete Microsoft specification support for all documented notification types
• 🔒 Robust error handling and connection management
• 🌳 Recursive monitoring of subdirectories
• 📊 Detailed logging of all file system events

Requirements

• Python >= 3.8
• smbprotocol library

Installation

1. Clone or download this script to your local machine

2. Install dependencies:

   pip install smbprotocol

3. Configure connection settings (see Configuration section below)

Configuration

Edit the configuration section at the top of watch_smb_changes.py:

# =============================================================================
# CONFIGURATION SECTION
# =============================================================================
SERVER   = "10.2.34.56"    # SMB server IP address or hostname
SHARE    = "test"           # SMB share name (without \\server\ prefix)
USERNAME = "test"           # SMB username
PASSWORD = "test"           # SMB password

Configuration Options

Setting	Description	Example
SERVER	SMB server IP address or hostname	"192.168.1.100" or "fileserver.local"
SHARE	Share name (without server prefix)	"documents" for \\server\documents
USERNAME	SMB authentication username	"administrator"
PASSWORD	SMB authentication password	"your_password"

Usage

Run the script from the command line:

python3 watch_smb_changes.py

Example Output

Connecting to SMB server 10.2.34.56...
Authenticating as test...
Connecting to share test...
Starting to watch for changes...
Press Ctrl+C to stop monitoring
--------------------------------------------------
[ADDED] documents\new_file.txt
[MODIFIED] documents\existing_file.docx
[RENAMED_OLD_NAME] documents\old_name.pdf
[RENAMED_NEW_NAME] documents\new_name.pdf
[REMOVED] documents\deleted_file.tmp

Stopping the Monitor

Press Ctrl+C to gracefully stop monitoring and close all SMB connections.

Supported Change Types

The script monitors and reports all types of file system changes:

Action	Description
ADDED	File or directory was created
REMOVED	File or directory was deleted
MODIFIED	File content, attributes, or timestamps changed
RENAMED_OLD_NAME	Original name in a rename operation
RENAMED_NEW_NAME	New name in a rename operation
ADDED_STREAM	NTFS alternate data stream was added
REMOVED_STREAM	NTFS alternate data stream was removed
MODIFIED_STREAM	NTFS alternate data stream was modified
REMOVED_BY_DELETE	Object ID removed due to file deletion
ID_NOT_TUNNELLED	Object ID tunneling failed
TUNNELLED_ID_COLLISION	Object ID tunneling collision

Technical Details

SMB2 Protocol Implementation

This script implements the Microsoft SMB2 CHANGE_NOTIFY protocol as documented in:

• MS-SMB2 Section 2.2.35 - SMB2 CHANGE_NOTIFY Request
• MS-FSCC Section 2.7.1 - FILE_NOTIFY_INFORMATION

Key Technical Features

• Manual Buffer Parsing: Bypasses library limitations to handle all server response codes
• Complete Completion Filter: Monitors all possible change types (file names, attributes, timestamps, security, streams)
• Non-blocking Design: Uses SMB2's asynchronous notification mechanism
• Invisible Monitoring: Doesn't interfere with normal file operations (uses appropriate ShareAccess flags)

Architecture

┌─────────────────┐    SMB2 CHANGE_NOTIFY    ┌─────────────────┐
│   Python Script │ ◄──────────────────────► │   SMB Server    │
└─────────────────┘                          └─────────────────┘
         │                                             │
         ▼                                             ▼
┌─────────────────┐                          ┌─────────────────┐
│ Manual Response │                          │  File System    │
│     Parser      │                          │    Monitor      │
└─────────────────┘                          └─────────────────┘

Troubleshooting

Common Issues

1. Connection Refused

   ConnectionRefusedError: [Errno 111] Connection refused
   

   • Check if the SMB server is running and accessible
   • Verify the server IP address and port (445)
   • Ensure firewall allows SMB traffic

2. Authentication Failed

   SMB authentication failed
   

   • Verify username and password
   • Check if the user has access to the specified share
   • Ensure the SMB server allows the authentication method

3. Share Not Found

   Share not found
   

   • Verify the share name is correct
   • Check if the share exists and is accessible
   • Ensure the user has permissions to access the share

4. Permission Denied

   Access denied
   

   • Verify the user has read permissions on the share
   • Check if the directory exists and is accessible

Debug Mode

For detailed debugging, uncomment the debug print statements in the main loop:

# Uncomment these lines for verbose output:
print("Waiting for a change notification from the server...")
# ...
print("Change notification received. Parsing response...")

Limitations

• Windows SMB servers only: Designed for Windows SMB/CIFS shares
• Network dependent: Performance depends on network latency
• Single share: Monitors one share at a time (can be extended for multiple shares)

License

MIT License - See the script header for full license information.

Contributing

This script is based on Microsoft's official SMB2 specifications and serves as a reference implementation. Feel free to extend it for your specific use case.

References

• Microsoft SMB2 Protocol Specification
• Microsoft File System Control Codes
• smbprotocol Python Library