Skip to content

About

A python demo project to demonstrates how to use the EaseFilter File Security Filter Driver SDK in Python

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

ย 

History

18 Commits

Folders and files

Repository files navigation

EaseFilter File System Filter Driver Python SDK

Platform Language License

The EaseFilter Python SDK provides a powerful, high-level Python interface to the EaseFilter Windows Kernel Minifilter Driver. This SDK empowers Python developers to easily integrate comprehensive file system monitoring, granular access control, transparent file encryption, and process sandboxing directly into their Python applications. EaseFilter File Security Architecture

๐Ÿš€ Key Features

  • File System Monitoring: Track file creation, deletion, reading, writing, renaming, and security changes in real-time.
  • Granular Access Control: Intercept file I/O operations and dynamically allow, deny, or modify access based on user, process, or file type.
  • Transparent File Encryption: Automatically encrypt data on-the-fly as it is written to the disk, and decrypt it when read by authorized processes.
  • Process Sandboxing: Restrict untrusted processes from modifying critical system files or accessing confidential directories.
  • Rapid Integration: Utilize Python's rapid development capabilities without needing to write complex C/C++ kernel-level code.

Installation

NOTE: Administrator permissions are required to run EaseFilter.

Install with Hatch

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.

Manual installation

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

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.

CLI examples

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.

Monitor filter

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

Control filter

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\*

Process filter

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

Encryption filter

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.

Registry filter

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

Development

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.

EaseFilter File System Filter Driver SDK Reference

Product Name Description
Cloud File System SDK EaseFilter Cloud File System SDK Introduction.
CloudTier Storage Tiering SDK EaseFilter Storage Tiering Filter Driver SDK Introduction.
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.
EaseFilter SDK Programming EaseFilter Filter Driver SDK Programming.

EaseFilter SDK Sample Projects

Sample Project Description
CloudTier Storage Tiering Demo A HSM File System Filter Driver Demo.
CloudTier S3 Tiering Demo CloudTier S3 Intelligent Tiering Demo.
Cloud File DR S3 Demo Cloud File DR S3 Demo.
Amazon S3 File Explorer Demo Amazon S3 File Explorer Demo.
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.
ZeroTrust Example Zero trust file access control with encryption feature.

Filter Driver Reference

License

This repository contains two distinct licensing categories:

  1. Wrapper/Implementation Code (MIT License): The source code, scripts, and configuration files provided directly in this repository are licensed under the MIT License. You are free to modify, distribute, and use this specific integration code.

  2. EaseFilter SDK (Commercial License): This project requires the EaseFilter SDK (including its binaries, filter drivers, and core libraries) to function. The EaseFilter SDK is proprietary commercial software and is strictly excluded from the MIT License.
    To use the EaseFilter SDK for commercial purposes or in a production environment, you must obtain a valid commercial license directly from EaseFilter.

Support

If you have questions or need help, please contact [email protected]

Home | Solution | Download | Demos | Blog | Programming

About

A python demo project to demonstrates how to use the EaseFilter File Security Filter Driver SDK in Python

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages