Windows File System Minifilter

A real-time, kernel-level file system monitoring and malware detection system for Windows. The project intercepts file I/O operations at the kernel level, forwards suspicious executables to a user-mode scanner, and classifies them using PE analysis and entropy-based heuristics.

System Architecture at a Glance

flowchart TB
    subgraph KernelSpace["Kernel Space"]
        FS["File System"]
        FltMgr["Filter Manager\n(FltMgr.sys)"]
        MF["WindowsFileSystemMinifilter.sys\n(Minifilter Driver)"]
    end

    subgraph UserSpace["User Space"]
        MON["FsMinifilterMonitor.exe\n(User-Mode Monitor)"]
        SCAN["Scanner.exe\n(Malware Scanner)"]
        subgraph ScanPipeline["Scan Pipeline"]
            PE["PE Parser"]
            FE["Feature Extractor"]
            ML["ML Classifier"]
            POL["Policy Engine"]
        end
    end

    FS -->|"I/O Request"| FltMgr
    FltMgr -->|"Pre/Post Callbacks"| MF
    MF -->|"FltSendMessage\n(Filter Port)"| MON
    MON -->|"Named Pipe\n(ScannerPipe)"| SCAN
    SCAN --> PE --> FE --> ML --> POL

    style KernelSpace fill:#1a1a2e,color:#fff
    style UserSpace fill:#16213e,color:#fff
    style ScanPipeline fill:#0f3460,color:#fff

Project Components

Component	Type	Language	Description
WindowsFileSystemMinifilter.sys	Kernel Driver	C (WDK)	Intercepts file system I/O via Filter Manager callbacks
FsMinifilterMonitor.exe	User-Mode App	C++	Receives kernel messages and dispatches scan requests
Scanner.exe	User-Mode App	C++	PE analysis, feature extraction, ML classification

Documentation Map

Architecture

High-level system design and technology decisions.

System Overview — Component topology, tech stack, deployment model
Driver Architecture — Kernel minifilter internals, callback registration, stream contexts
Communication Architecture — Filter ports, named pipes, message protocols
Design Decisions — Why minifilter? Why entropy? Rationale for every major choice

Flows

End-to-end data flows and lifecycle diagrams.

File Interception Flow — From I/O request to kernel callback to user-mode notification
Scan Pipeline Flow — PE parsing → feature extraction → classification → policy enforcement
Driver Lifecycle — Install → load → attach → filter → unload

Modules

Detailed breakdown of every component, class, and subsystem.

Kernel Driver Module — FsMinifilter.cpp, callback implementations, context management
Monitor Module — FsMinifilterMonitor, port connection, deduplication, pipe forwarding
Scanner Module — Worker thread, queue, pipe server, scan modes
PE Parser Module — DOS/NT header validation, section parsing, import counting
ML Classifier Module — Entropy-based heuristic classification model
Policy Engine Module — Verdict handling and enforcement actions

API & Contracts

Inter-component interfaces, data types, and communication protocols.

Kernel ↔ User Interface — Filter communication port protocol and message format
Scanner API — Public scanner interface, scan results, scan modes
Data Types Reference — All shared structures, enums, and constants

Guides

Step-by-step operational guides.

Getting Started — Prerequisites, first build, first run
Building the Project — Visual Studio configuration, WDK setup, multi-arch builds
Installing the Driver — Test signing, service creation, fltmc commands
Adding Detection Rules — How to extend the ML classifier and policy engine

Quick Links

Task	Guide
Build from source	Building
Install driver on test machine	Installing the Driver
Understand how a file scan works	Scan Pipeline Flow
Add a new malware detection rule	Adding Detection Rules
Understand kernel ↔ user comms	Communication Architecture

Repository Structure

├── Windows File System Minifilter/   # Kernel-mode minifilter driver
│   ├── main.cpp                      # DriverEntry
│   ├── FsMinifilter.cpp              # Callback implementations
│   ├── FsMinifilter.h                # Driver declarations & stream context
│   ├── FsMinifilterCommon.h          # Shared message types (kernel ↔ user)
│   └── WindowsFileSystemMinifilter.inf
├── FsMinifilterMonitor/              # User-mode monitor application
│   └── main.cpp                      # Port listener, pipe forwarder
├── scanner/                          # User-mode malware scanner
│   ├── scanner.cpp                   # Entry point, worker thread, pipe server
│   ├── pe_parser.cpp/h               # PE file parsing engine
│   ├── features.cpp/h                # Feature extraction
│   ├── ml.cpp/h                      # ML classification
│   ├── policy.cpp/h                  # Policy enforcement
│   ├── queue.cpp/h                   # Thread-safe scan queue
│   └── scanner_api.h                 # Public API surface
├── ScannerShared.h                   # Shared types (monitor ↔ scanner)
├── InstallDriver.cmd                 # Driver install/remove script
└── docs/                             # ← You are here