Driver Lifecycle

This document describes the complete lifecycle of the minifilter driver from installation through operation to removal.

Related: Driver Architecture · Kernel Driver Module · Installing the Driver

1. Lifecycle Overview

stateDiagram-v2
    [*] --> Installed: InstallDriver.cmd install\n(sc.exe create + reg add)

    Installed --> Loading: sc.exe start / fltmc load
    
    Loading --> DriverEntry: System calls DriverEntry()
    
    DriverEntry --> Registered: FltRegisterFilter()
    Registered --> PortCreated: FltCreateCommunicationPort()
    PortCreated --> Filtering: FltStartFiltering()
    
    Filtering --> MonitorConnected: PortConnectCallback()
    MonitorConnected --> Filtering: PortDisconnectCallback()
    
    Filtering --> Unloading: fltmc unload / sc.exe stop

    Unloading --> PortClosed: FltCloseCommunicationPort()
    PortClosed --> Unregistered: FltUnregisterFilter()
    Unregistered --> Installed: Service remains registered

    Installed --> Removed: InstallDriver.cmd remove\n(sc.exe delete + reg cleanup)
    Removed --> [*]

    state Filtering {
        [*] --> Idle
        Idle --> Processing: IRP received
        Processing --> Sending: Target .exe/.dll detected
        Sending --> Idle: Message sent / timed out
        Processing --> Idle: Not target → skip
    }

2. Installation Phase

The InstallDriver.cmd script performs the following steps:

flowchart TD
    Start["InstallDriver.cmd install"]
    
    Start --> Find["Find latest .sys file\n(ARM64/Release → x64/Release → Debug)"]
    Find --> Clean["Remove any existing installation\n(fltmc unload, sc stop/delete)"]
    Clean --> Copy["Copy .sys to\nC:\\Windows\\System32\\drivers\\"]
    Copy --> Service["sc.exe create\ntype=filesys start=demand"]
    
    Service --> Reg1["reg add: DependOnService = FltMgr"]
    Reg1 --> Reg2["reg add: Group = FSFilter Activity Monitor"]
    Reg2 --> Reg3["reg add: DefaultInstance"]
    Reg3 --> Reg4["reg add: Altitude = 47777"]
    Reg4 --> Reg5["reg add: Flags = 0"]
    
    Reg5 --> StartSvc["sc.exe start"]
    StartSvc --> Verify{"sc query → RUNNING?"}
    
    Verify -->|Yes| Success["Driver Installed"]
    Verify -->|No| Fail["Check test signing,\narchitecture, Event Viewer"]

    style Success fill:#2d6a4f,color:#fff
    style Fail fill:#e63946,color:#fff

Registry Layout After Installation

HKLM\SYSTEM\CurrentControlSet\Services\WindowsFileSystemMinifilter
├── Type = 2 (FILE_SYSTEM_DRIVER)
├── Start = 3 (DEMAND_START)
├── ErrorControl = 1 (NORMAL)
├── ImagePath = \SystemRoot\System32\drivers\WindowsFileSystemMinifilter.sys
├── DependOnService = FltMgr
├── Group = FSFilter Activity Monitor
└── Instances
    ├── DefaultInstance = "WindowsFileSystemMinifilter Instance"
    └── WindowsFileSystemMinifilter Instance
        ├── Altitude = "47777"
        └── Flags = 0

3. DriverEntry Sequence

sequenceDiagram
    participant OS as Windows Kernel
    participant DE as DriverEntry()
    participant FM as Filter Manager
    participant Port as Comm Port

    OS->>DE: DriverEntry(DriverObject, RegistryPath)
    
    DE->>FM: FltRegisterFilter(&g_filterRegistration)
    FM-->>DE: g_minifilterHandle
    
    alt Registration failed
        DE-->>OS: Return error status
    end

    DE->>FM: FltBuildDefaultSecurityDescriptor(FLT_PORT_ALL_ACCESS)
    FM-->>DE: securityDescriptor

    DE->>Port: FltCreateCommunicationPort(\n  "\\FsMinifilterPort",\n  PortConnectCallback,\n  PortDisconnectCallback,\n  MaxConnections=1)
    Port-->>DE: g_serverPort

    DE->>FM: FltFreeSecurityDescriptor()
    
    alt Port creation failed
        DE->>FM: FltUnregisterFilter()
        DE-->>OS: Return error status
    end

    DE->>FM: FltStartFiltering()
    
    alt Start failed
        DE->>Port: FltCloseCommunicationPort()
        DE->>FM: FltUnregisterFilter()
        DE-->>OS: Return error status
    end

    DE-->>OS: STATUS_SUCCESS
    Note over OS: Driver is now active and filtering

Error Handling Strategy

The DriverEntry follows a strict cleanup-on-failure pattern. Each initialization step checks the return status, and on failure, cleans up all previously acquired resources in reverse order:

4. Instance Attachment

When the driver starts filtering, Filter Manager calls InstanceSetupCallback for each mounted volume:

flowchart LR
    subgraph Volumes["Mounted Volumes"]
        C["C: (NTFS)"]
        D["D: (NTFS)"]
        Net["\\\\server\\share\n(Network)"]
        USB["E: (FAT32 USB)"]
    end

    subgraph Driver["Minifilter"]
        Setup["InstanceSetupCallback()"]
    end

    C -->|"Attach"| Setup
    D -->|"Attach"| Setup
    Net -->|"Attach"| Setup
    USB -->|"Attach"| Setup
    
    Setup -->|"STATUS_SUCCESS\n(attach to all)"| Result["Attached"]

    style Result fill:#2d6a4f,color:#fff

Current behavior: InstanceSetupCallback returns STATUS_SUCCESS for all volumes, meaning the driver attaches to every file system volume. This includes network shares and removable drives.

5. Unload Sequence

sequenceDiagram
    participant Admin as Administrator
    participant FM as Filter Manager
    participant Unload as InstanceFilterUnloadCallback
    participant Port as Comm Port

    Admin->>FM: fltmc unload WindowsFileSystemMinifilter
    FM->>Unload: InstanceFilterUnloadCallback(Flags)

    Unload->>Port: FltCloseCommunicationPort(g_serverPort)
    Note over Port: Triggers PortDisconnectCallback\nif monitor is connected

    Unload->>FM: FltUnregisterFilter(g_minifilterHandle)
    Note over FM: All instance contexts released\nAll stream contexts cleaned up

    Unload-->>FM: STATUS_SUCCESS
    FM-->>Admin: Driver unloaded

6. Monitor Connection Lifecycle

stateDiagram-v2
    [*] --> DriverRunning: Driver loaded,\nport created

    DriverRunning --> Connected: Monitor calls\nFilterConnectCommunicationPort()
    
    state Connected {
        [*] --> Idle
        Idle --> SendingMessage: File event on .exe/.dll
        SendingMessage --> Idle: FltSendMessage → success/timeout
    }

    Connected --> Disconnected: Monitor exits or\nCloseHandle(port)
    Disconnected --> DriverRunning: PortDisconnectCallback()\ng_clientPort = NULL

    DriverRunning --> [*]: Driver unloaded

    note right of Connected
        g_clientPort ≠ NULL
        g_clientProcessId = monitor PID
        Messages are sent
    end note

    note right of DriverRunning
        g_clientPort == NULL
        Messages are silently dropped
        (SendMessageToUserMode returns
        STATUS_PORT_DISCONNECTED)
    end note

7. Operational Commands

Next Steps

• Step-by-step install guide: Installing the Driver
• What happens during filtering: File Interception Flow
• Driver code details: Kernel Driver Module