Communication Architecture

This document describes the two inter-process communication channels that connect the kernel driver, user-mode monitor, and scanner: the Filter Communication Port and the Named Pipe.

Related: System Overview · Driver Architecture · Kernel ↔ User Interface · Monitor Module

1. Communication Topology

flowchart LR
    subgraph Ring0["Kernel (Ring 0)"]
        Driver["WindowsFileSystemMinifilter.sys"]
        ServerPort["Server Port\n(\\FsMinifilterPort)"]
        Driver --> ServerPort
    end

    subgraph Ring3["User (Ring 3)"]
        Monitor["FsMinifilterMonitor.exe"]
        ClientPort["Client Port Handle"]
        Pipe["Named Pipe\n(\\\\.\\pipe\\ScannerPipe)"]
        Scanner["Scanner.exe"]
        
        Monitor --> ClientPort
        Monitor --> Pipe
        Pipe --> Scanner
    end

    ServerPort -.->|"FltSendMessage\n(MINIFILTER_MESSAGE)"| ClientPort
    ClientPort -.->|"FilterGetMessage"| Monitor

    style Ring0 fill:#7b2cbf,color:#fff
    style Ring3 fill:#2d6a4f,color:#fff

2. Channel 1: Filter Communication Port

Overview

The kernel driver creates a filter communication port during DriverEntry. The monitor connects to this port using FilterConnectCommunicationPort. The kernel sends unidirectional messages (driver → monitor); no replies are expected.

Lifecycle Sequence

sequenceDiagram
    participant D as Driver (Kernel)
    participant FM as Filter Manager
    participant M as Monitor (User)

    Note over D: DriverEntry()
    D->>FM: FltBuildDefaultSecurityDescriptor()
    D->>FM: FltCreateCommunicationPort("\\FsMinifilterPort")
    FM-->>D: g_serverPort handle

    Note over M: wmain()
    M->>FM: FilterConnectCommunicationPort("\\FsMinifilterPort")
    FM->>D: PortConnectCallback()
    D->>D: g_clientPort = ClientPort
    D->>D: g_clientProcessId = PsGetCurrentProcessId()
    FM-->>M: port handle

    loop File System Events
        D->>FM: FltSendMessage(MINIFILTER_MESSAGE)
        FM->>M: FilterGetMessage() returns
        M->>M: Process message
    end

    Note over M: Process exit or Ctrl+C
    M->>FM: CloseHandle(port)
    FM->>D: PortDisconnectCallback()
    D->>D: g_clientPort = NULL
    D->>D: g_clientProcessId = 0

Port Configuration

Message Format

classDiagram
    class MINIFILTER_MESSAGE {
        +ULONG MessageType
        +ULONG ProcessId
        +WCHAR FilePath[520]
    }

    class FILTER_MESSAGE {
        +FILTER_MESSAGE_HEADER Header
        +MINIFILTER_MESSAGE Message
    }

    FILTER_MESSAGE --> MINIFILTER_MESSAGE : contains

The kernel sends raw MINIFILTER_MESSAGE via FltSendMessage. The user-mode monitor receives it wrapped in FILTER_MESSAGE which includes the FILTER_MESSAGE_HEADER prepended by Filter Manager.

See Data Types Reference for complete struct layouts.

3. Channel 2: Named Pipe (Monitor → Scanner)

Overview

The monitor forwards scan-worthy events to the scanner via a Win32 named pipe. The scanner creates the pipe server; the monitor connects as a client.

Lifecycle Sequence

sequenceDiagram
    participant S as Scanner.exe
    participant M as Monitor.exe

    Note over S: wmain() → InitializeScanner()
    S->>S: CreateNamedPipe("\\\\.\\pipe\\ScannerPipe")
    S->>S: ConnectNamedPipe() — blocks

    Note over M: Receives first .exe/.dll event
    M->>S: CreateFile(PIPE_NAME) — connects
    S-->>S: ConnectNamedPipe returns

    loop Scan Requests
        M->>S: WriteFile(SCAN_REQUEST)
        S->>S: ReadFile() → Enqueue → ScanWorker
    end

    Note over M: Process exits
    M->>S: Pipe disconnected
    S-->>S: ReadFile returns FALSE

Pipe Configuration

Message Format

The pipe carries raw SCAN_REQUEST structs:

classDiagram
    class SCAN_REQUEST {
        +WCHAR filePath[260]
        +DWORD pid
        +FILETIME timestamp
    }

Connection Resilience

The monitor implements a retry loop for pipe connection (EnsurePipeConnection):

• Up to 20 retries with 100ms intervals
• If a pipe write fails, the handle is closed and re-established on the next request
• This allows the scanner to be started before or after the monitor

4. Deduplication Layer

Between receiving kernel messages and forwarding to the scanner, the monitor applies deduplication to avoid flooding the scanner with repeated events for the same file.

flowchart TD
    MSG["Kernel Message Received"]
    
    MSG --> IsExe{"Is .exe or .dll?"}
    IsExe -->|No| Drop1["Drop"]
    IsExe -->|Yes| Dedup{"Seen within\nlast 5 seconds?"}
    
    Dedup -->|Yes| Drop2["Drop (Deduplicated)"]
    Dedup -->|No| Cache["Update Cache\n+ Forward to Scanner"]

    subgraph CacheMgmt["Cache Management"]
        direction TB
        Cleanup["Periodic Cleanup\n(every 30s)"]
        Evict["Evict entries\n> 5s old"]
        Cleanup --> Evict
    end

    style Drop1 fill:#6c757d,color:#fff
    style Drop2 fill:#6c757d,color:#fff
    style Cache fill:#2d6a4f,color:#fff

5. End-to-End Message Flow

flowchart LR
    A["App writes\nmalware.exe"] 
    --> B["NTFS I/O"]
    --> C["Filter Manager"]
    --> D["PreOperationWrite"]
    --> E["SendMessageToUserMode\n(MSG_TYPE_FILE_MODIFY)"]
    --> F["FilterGetMessage\n(Monitor)"]
    --> G["Dedup Check"]
    --> H["WriteFile\n(Named Pipe)"]
    --> I["ReadFile\n(Scanner)"]
    --> J["Enqueue"]
    --> K["ScanWorker\nDequeue + Analyze"]

    style A fill:#e63946,color:#fff
    style K fill:#2d6a4f,color:#fff

Next Steps

• See the full message structure definitions: Data Types Reference
• See how the monitor processes messages: Monitor Module
• Understand the scan pipeline after queue: Scan Pipeline Flow