This is a demo library that provides a Pythonic API over the EaseFilter File System Filter Driver SDK. The source code is throughly documented, and intended to serve as an example for using EaseFilter.
A CLI is included, based on the C++ demo.
Python version 3.9 or above is required to use this program. Also, a license key is required.
The provided interfaces include:
EaseFilter Filter Driver SDK can monitor Windows file I/O activities in real time, track the file access and changes, monitor file and folder permission changes, audit who is writing, deleting, moving or reading files, report the user name and process name, get the user name and the ip address when the Windows file server's file is accessed by network user.
The EaseFilter control filter driver can intercept the file I/O before it goes down to the file system or after it returned from the file system. You can deny the file access in the pre file I/O operations based on the filter rule policies. It meant that the EaseFilter can complete and return the file I/O without going down to the file system. Also you can modify the I/O data before it goes down to the file system or after it returned from the file system.
The EaseFilter Encryption Filter Driver(EEFD) is a transparent on-access file level encryption file system filter driver. It can encrypt or decrypt the file automatically in the file system level. The EEFD is a mature commercial product. It provides a complete modular framework for the developers to build the on access file encryption software. With the EEFD, you can incorporate transparent on-access, file level encryption into your application.
Easefilter process filter driver is a kernel-mode driver that filters process/thread creation and termination, it provides you an easy way to develop Windows application for the Windows process monitoring and protection. With the EaseFilter Process Filter Driver, it enables your application to prevent the untrusted executable binaries ( malwares) from being launched, protect your data being damaged by the untrusted processes.
Registry filter driver is a kernel-mode driver that filters registry calls, it provides you an easy way to develop Windows application for registry monitoring and protection, track the registry change and prevent the registry from being changed by unauthorized processes or users.
NOTE: Administrator permissions are required to run EaseFilter.
The recommended installation method uses Hatch, which takes care of the project dependencies.
First, install Python.
Then, install hatch:
pip install hatch
Edit the license key field in config.toml:
license_key = "..."
Change to this directory, and to run the included CLI, use:
hatch run cli [args]
Otherwise, to start a Python REPL (command line), run:
hatch run py
In this environment, you can import the easefilter module to interface with
the filter. The CLI's code is available at easefilter/cli/main.py, and can
serve as an example for using this library.
If you do not wish to use Hatch, you can run this project directly through Python.
First, install Python.
Then, install the dependencies:
pip install -r requirements.txt
Edit the license key field in config.toml:
license_key = "..."
To run the CLI, use:
python -m easefilter.cli [args]
And to start a Python REPL, change directory here, and run Python normally:
python
Visual Studio can be used to navigate this codebase easily. Open
ef-python.sln to open this project.
There are no integrations for debugging/running the code directly in VS. Use the terminal to install and run this project.
It may be helpful to set up a virtual environment; to do this, select Tools / Python / Python Environments and click Add environment.
Here are a few example CLI commands to try.
To get detailled help, run
hatch run cli --help
or, for help on a specific subcommand,
hatch run cli monitor --help
For documentation on event types you can register, see the file easefilter/enums.py.
Default settings, creates a test directory (C:\easefilter_demo) and monitors its contents:
hatch run cli monitor
Monitor events for all files on your device:
hatch run cli monitor *
Monitor a specific directory:
hatch run cli monitor "C:\directory\*"
Enable monitoring all specific events (the --io-mask is shorthand for all the bitflags combined):
hatch run cli monitor --io-mask 192118399729052330
Monitor all file handle creation events:
hatch run cli monitor --io-sym POST_CREATE
Deny all file writes in a directory:
hatch run cli control --deny-sym "ALLOW_WRITE_ACCESS,ALLOW_OPEN_WITH_CREATE_OR_OVERWRITE_ACCESS" C:\a_directory\*
Deny all reads in the directory (also denies cd-ing into directory):
hatch run cli control --deny-sym "ALLOW_READ_ACCESS,ALLOW_OPEN_WITH_READ_ACCESS" C:\a_directory\*
Deny file listing in a directory (makes directory seem empty):
hatch run cli control --deny-sym ALLOW_DIRECTORY_LIST_ACCESS C:\a_directory\*
Monitor all process creations/deletions (try starting a PowerShell to test this):
hatch run cli process
Monitor specifically cmd.exe:
hatch run cli process --proc-mask C:\Windows\System32\cmd.exe
Monitor all System32 processes:
hatch run cli process --proc-mask C:\Windows\System32\*
(BE CAREFUL with this flag) Prevent cmd.exe from running:
hatch run cli process --proc-control-sym DENY_NEW_PROCESS_CREATION --proc-mask C:\Windows\System32\cmd.exe
Transparently encrypt a directory:
hatch run cli encryption 'C:\my_encrypted_dir\*'
This will prompt for a password. The password prompt does not show the characters you type in.
Files will only be decrypted while the filter is running. Once stopped, files will be encrypted and unreadable.
Monitor all registry events:
hatch run cli registry
Monitor all registry events for keys with a matching name:
hatch run cli registry *KeyName*
Monitor all registry events coming from regedit:
hatch run cli registry --proc-mask C:\Windows\regedit.exe
Monitor all registry key rename events coming from regedit:
hatch run cli registry --reg-class-sym Reg_Pre_Rename_Key --proc-mask C:\Windows\regedit.exe
Prevent regedit from deleting keys:
hatch run cli registry --reg-deny-sym REG_ALLOW_DELETE_KEY --proc-mask C:\Windows\regedit.exe
To format/lint after changing any code, run
hatch fmt
or, to do a dry-run and avoid making changes,
hatch fmt --check
These will run Ruff and Pyright.
Tests can be performed with pytest like this:
hatch test
You may specify a test to run by adding its path (e.g. tests/test_something.py) as an argument.
Consult pytest's documentation for more information.
| Product Name | Description |
|---|---|
| File Monitor SDK | EaseFilter File Monitor Filter Driver SDK Introduction. |
| File Control SDK | EaseFilter File Control Filter Driver SDK Introduction. |
| File Encryption SDK | EaseFilter Transparent File Encryption Filter Driver SDK Introduction. |
| Registry Filter SDK | EaseFilter Registry Filter Driver SDK Introduction. |
| Process Filter SDK | EaseFilter Process Filter Driver SDK Introduction. |
| Storage Tiering SDK | EaseFilter Storage Tiering Filter Driver SDK Introduction. |
| EaseFilter SDK Programming | EaseFilter Filter Driver SDK Programming. |
| Sample Project | Description |
|---|---|
| Auto File DRM Encryption | Auto file encryption with DRM data embedded. |
| Transparent File Encrypt | Transparent on access file encryption. |
| Secure File Sharing with DRM | Secure encrypted file sharing with digital rights management. |
| File Monitor Example | Monitor file system I/O in real time, tracking file changes. |
| File Protector Example | Prevent sensitive files from being accessed by unauthorized users or processes. |
| FolderLocker Example | Lock file automatically in a FolderLocker. |
| Process Monitor | Monitor the process creation and termination, block unauthorized process running. |
| Registry Monitor | Monitor the Registry activities, block the modification of the Registry keys. |
| Secure Sandbox Example | A secure sandbox example, block the processes accessing the files out of the box. |
| FileSystemWatcher Example | File system watcher, logging the file I/O events. |
- Understand MiniFilter Driver: https://www.easefilter.com/kb/understand-minifilter.htm
- Understand File I/O: https://www.easefilter.com/kb/File_IO.htm
- Understand I/O Request Packets(IRPs):https://www.easefilter.com/kb/understand-irps.htm
- Filter Driver Developer Guide: https://www.easefilter.com/kb/DeveloperGuide.htm
- MiniFilter Filter Driver Framework: https://www.easefilter.com/kb/minifilter-framework.htm
- Isolation Filter Driver: https://www.easefilter.com/kb/Isolation_Filter_Driver.htm
If you have questions or need help, please contact support@easefilter.com