2026-08-07 — v1.0.0.3 — complete-list rule synchronization, GUI checkbox fixes, trusted-name normalization, and expanded collision tests

VaultGuard (vg.exe) is a complete rewrite of a 12-year-old Qt/C++ folder-protection suite in pure x64 MASM — zero CRT, native WinAPI only, Windows 11 Dark Mode + Mica + system tray. The same binary acts as a full Win32 GUI, a scriptable CLI, or a Windows service depending on its arguments. It communicates with vg.sys, a kernel-mode FSFilter Content Screener minifilter signed by PROMOSOFT CORPORATION (2014), which loads on Windows 11 26H1 via Microsoft's backward-compatibility mechanism for cross-signed drivers predating 29 July 2015.

VaultGuard — Kernel-Backed Folder Protection for Windows

Table of Contents

• Overview
• Architecture
• GUI Reference
• CLI Reference
• Service & Autostart
• Use Cases
• Module Analysis
  • main.asm — Entry Point & Globals
  • window.asm — Window Skeleton
  • layout.asm — Control Creation
  • tray.asm — System Tray
  • theme.asm — Dark Mode & Colors
  • handlers.asm — Commands & Status
  • procpicker.asm — Running Process Picker
  • impexp.asm — GUI Config Import/Export
  • drop.asm — Drag & Drop
  • service.asm — Windows Service Runtime
  • driver_scm.asm — clrcd SCM lifecycle
  • device.asm — Device handle + EnsureDriverReady
  • ioctl.asm — DeviceIoControl wrappers
  • config.asm — Registry Persistence
  • cli.asm — Command-Line Interface
  • export.asm — CSV Export
  • res.asm — Driver Extraction (FDI)
  • strutil.asm — String Utilities
  • listview.asm — ListView Wrappers
• Driver Communication Protocol
• Protection Flags
• Registry Layout
• Build System
• Project Structure
• Regression Tests
• Known Limitations

Overview

VaultGuard is an access-control tool for Windows directories and files, backed by a kernel-mode driver of type Minifilter (FSFilter Content Screener). The project is a ground-up rewrite of the original 12-year-old VaultGuard (Qt/C++, split GUI + CLI) into pure x64 MASM assembly. The primary design goals are:

Architecture

GUI Reference

Launching vg.exe without arguments (or with an unrecognized argument) starts the graphical interface. Because the application installs and communicates with a kernel driver, it requires Administrator privileges (enforced via requireAdministrator in the manifest).

Main Window

The main window (class VGMainWnd) has a fixed size of 700 × 550 pixels and uses a native Win32 window with a Mica backdrop and a dark title bar when the system is in Dark Mode.

Driver and protection state is embedded dynamically in the window title:

VaultGuard | Driver: STOPPED   | Protection: OFF
VaultGuard | Driver: TRANSIENT | Protection: ON

This state refreshes every 2 seconds via WM_TIMER and after every user action.

System Tray

UIPI note: When launched elevated via Task Scheduler (/rl highest), ChangeWindowMessageFilterEx is called during WM_CREATE to allow the TaskbarCreated registered message (ID ≥ 0xC000) to cross the integrity boundary from Medium-IL Explorer into the High-IL process. Without this the tray icon would not appear after logon.

Protected Folders Panel

The upper section contains a ListView of protected paths.

Columns:

Trusted Processes Panel

The lower section defines processes that bypass all driver protections. Trust is global: the driver identifies a trusted process by executable basename and does not expose an application-to-folder mapping. Every copy with the same filename is therefore trusted for every protected path.

Note: Removing sends an empty IoctlRemoveTrusted that wipes the entire active trusted list in the driver. ConfigLoad immediately reloads all remaining registry entries. The driver provides no per-item removal IOCTL.

CLI Reference

CLI mode is activated when vg.exe is launched with at least one recognized argument.

vg.exe /?
vg.exe /enumitems    <outfile.csv>
vg.exe /enumtrusted  <outfile.csv>
vg.exe /protection   on | off
vg.exe /setitem      <path>  Hidden|Locked|Read-only|No-execution|Disabled
vg.exe /settrusted   <name>  Enabled|Disabled
vg.exe /tray
vg.exe /autostart    on | off
vg.exe /service      install | uninstall
vg.exe /driver       install [manual | auto]
vg.exe /driver       uninstall
vg.exe /driver       start | stop
vg.exe /driver       startup manual | auto
vg.exe /uninstall
/p <password>  — parsed and silently ignored (driver has no password layer)

Command Summary

Protection Modes for /setitem

CSV Output Formats

/enumitems output:

<BOM>Path,Hidden,Locked,ReadOnly,NoExec\r\n
C:\temp\aaa,1,0,0,0\r\n

/enumtrusted output:

<BOM>Application\r\n
totalcmd64.exe\r\n

Both files are written in UTF-16LE with BOM. /enumitems reads from registry (HKCU\Software\VG\Paths), not from the IOCTL buffer.

Exit Codes

Every CLI exit path goes through _CliFinish(code), which injects a VK_RETURN keystroke via WriteConsoleInputW so the CMD prompt reappears without waiting for Enter.

Service & Autostart

Windows Service (/service install)

vg.exe /service install
vg.exe /service uninstall

Registers vg.exe as a Windows service named VaultGuard:

• Start type: SERVICE_DEMAND_START — manual start (immediately started after creation via StartServiceW)
• Binary path: "<full path to vg.exe>" /svcstart
• On install: service is created and immediately started via StartServiceW
• On uninstall: service is stopped and deleted

The internal /svcstart switch is dispatched by CliDispatch → _SvcStart → StartServiceCtrlDispatcherW. Service lifecycle:

_SvcMain → RegisterServiceCtrlHandlerExW → SetServiceStatus(RUNNING)
         → WaitForSingleObject(stop_event, INFINITE)
         → on STOP/SHUTDOWN/PRESHUTDOWN: SetEvent → SetServiceStatus(STOPPED)

Accepted controls: SERVICE_CONTROL_STOP, SERVICE_CONTROL_SHUTDOWN, SERVICE_CONTROL_PRESHUTDOWN.

Logon Autostart (/autostart on)

vg.exe /autostart on
vg.exe /autostart off

Registers a Task Scheduler logon task:

schtasks.exe /create /f /sc onlogon /rl highest /tn VaultGuard
             /tr "\"<exe>\" /tray"

Key properties:

• /rl highest — runs elevated (High Integrity Level) without UAC prompt at logon
• /sc onlogon — fires once per user logon session
• Battery restrictions cleared after creation: DisallowStartIfOnBatteries:$false, StopIfGoingOnBatteries:$false

This is the only officially supported Microsoft method for silent elevated autostart on Windows 10/11. HKCU\Run entries are silently skipped for processes with requireAdministrator manifest.

Driver Service (/driver ...)

vg.exe /driver install
vg.exe /driver install auto
vg.exe /driver uninstall
vg.exe /driver start
vg.exe /driver stop
vg.exe /driver startup manual
vg.exe /driver startup auto

Manages the real protection service, clrcd, through WinAPI/SCM calls only:

• install extracts vg.sys, creates the kernel driver service and leaves it SERVICE_DEMAND_START by default
• install auto creates the service and changes start type to SERVICE_AUTO_START
• start / stop call StartServiceW / ControlService (current session)
• startup manual / startup auto call ChangeServiceConfigW for the existing clrcd service — SCM rewrites HKLM\SYSTEM\CurrentControlSet\Services\clrcd\Start on the fly; a running driver is not stopped
• uninstall stops and deletes clrcd, then deletes %SystemRoot%\System32\drivers\vg.sys best-effort

Full Cleanup (/uninstall)

vg.exe /uninstall

Single-shot teardown of every persistent VaultGuard footprint:

1. Disable protection (IoctlSetActive(0)) if driver reachable
2. Stop + delete app service VaultGuard via SCM
3. Stop + delete driver service clrcd via SCM
4. Delete %SystemRoot%\System32\drivers\vg.sys best-effort
5. Remove HKCU\Software\VG registry tree (Paths, Trusted)

All steps are best-effort — stale partial installs can be flushed in one pass even if individual steps fail.

Use Cases

Scenario 1: Lock a Folder and Allow a Specific Application

vg.exe /protection on
vg.exe /setitem "C:\Private" Locked
vg.exe /settrusted totalcmd64.exe Enabled

vg.exe /enumitems   items.csv
vg.exe /enumtrusted trust.csv

# Revoke when done
vg.exe /settrusted totalcmd64.exe Disabled

Scenario 2: Hide a Folder from Explorer

vg.exe /setitem "C:\Secret" Hidden

The folder disappears from Explorer, dir, and all directory enumeration APIs.

Scenario 3: Read-Only Archive

vg.exe /setitem "C:\Backups" Read-only

The driver strips FILE_WRITE_DATA and DELETE bits at the kernel level. Trusted processes can still write.

Scenario 4: Persistent Elevated Tray App at Logon

vg.exe /autostart on
# Task Scheduler entry created. VaultGuard starts at logon to tray, elevated, no UAC prompt.
vg.exe /autostart off   # remove

Scenario 5: Boot-Time Windows Service

vg.exe /service install
# Service VaultGuard created (DEMAND_START) and immediately started.
vg.exe /service uninstall

Scenario 6: Scripted Status Check

vg.exe /enumitems C:\temp\items.csv
$rows   = Import-Csv C:\temp\items.csv -Encoding Unicode
$locked = $rows | Where-Object { $_.Locked -eq '1' }
Write-Host "Locked paths: $($locked.Count)"

Module Analysis

The source tree is organized into 19 MASM source files plus includes. Each file has a single clearly defined responsibility.

main.asm — Entry Point & Globals

Entry point: mainCRTStartup

Startup sequence:

1. GetStdHandle(STD_OUTPUT_HANDLE) + GetFileType → AttachConsole(-1) if no TTY
2. GetCommandLineW → CommandLineToArgvW
3. argc >= 2 → CliDispatch(argv[1], argv, argc); returns 0 (unknown) or argc < 2 → GUI

Public globals:

window.asm — Window Skeleton

Contains exclusively MainWndProc and CreateMainWindow. Fixed 700 × 550 px, class VGMainWnd.

On creation, calls RegisterWindowMessageW("TaskbarCreated") and stores the dynamic ID in g_wmTaskbarCreated (PUBLIC) — used in MainWndProc and to unlock the UIPI filter in _OnCreate.

Handled WM messages:

layout.asm — Control Creation

_OnCreate(rcx=hwnd) creates all widgets in a single pass:

[y=  8] Toggle button (x=182)
[y=  8] [Add path...]  (x=364)  +  [Remove selected]  (x=504)
[y= 10] "Protected files/folders" header (x=20)
[y= 40] ListView Paths (w=624, h=220): columns Path/H/L/R/X — multi-select, checkboxes
[y=278] "Allowed apps (trusted)" header (x=20)
[y=276] Trusted edit box (x=182)  +  [Add] (x=364)  +  [Add running] (x=440)  +  [Remove] (x=556)
[y=308] ListView Trusted (w=624, h=140, ~6 rows): 1 column Process name — multi-select
[y=454] [Export] (x=20)  +  [Import] (x=115)
[y=482] Author/copyright label (x=20, w=624, centered)

Key initialization calls:

• InitCommonControlsEx(ICC_LISTVIEW_CLASSES)
• DragAcceptFiles(TRUE)
• ChangeWindowMessageFilterEx for WM_DROPFILES, WM_COPYDATA, WM_COPYGLOBALDATA, and TaskbarCreated — all MSGFLT_ALLOW

UIPI fix: The TaskbarCreated filter is required when running at High Integrity Level (elevated via Task Scheduler). Without it, the TaskbarCreated broadcast from Medium-IL Explorer is silently blocked, and the tray icon never reappears after logon.

tray.asm — System Tray

WM_TRAY is WM_APP + 1. _TrayAdd sets uCallbackMessage = WM_TRAY so all tray icon mouse events are routed to MainWndProc.

theme.asm — Dark Mode & Colors

handlers.asm — Commands & Status

_OnCommand dispatch by control ID:

_OnNotify — handles flag-cell clicks and LVN_ITEMCHANGED checkbox events. Every path/trusted enable or disable persists the row state, calls ConfigLoad to rebuild both complete driver lists, and preserves all unaffected entries.

UpdateStatusBar — EnsureDriverReady → IoctlGetStatus → updates title bar and toggle button text.

RefreshLists — IoctlEnumPaths + IoctlEnumTrusted → LVM_DELETEALLITEMS → _LvInsertItem for each entry.

procpicker.asm — Running Process Picker

ShowProcPicker(rcx=hwndOwner) → eax = count of processes added

Opens a modal dialog snapped flush against the right edge of the main window.

impexp.asm — GUI Config Import/Export

File format (.vgc, UTF-16LE with BOM):

[Paths]
C:\Private=2
C:\Secret=1
[Trusted]
totalcmd64.exe=1

drop.asm — Drag & Drop

_OnDropFiles(rcx=HDROP, rdx=hMainWnd) — handles WM_DROPFILES:

1. DragQueryFileW(0) → first dropped path into g_pathBuf
2. Detects drop target: if cursor Y-position is over Trusted panel → route to trusted add
3. Last 4 chars are .lnk → ResolveLnkPath → GetLongPathNameW
4. Trusted panel drop: extracts filename component → lowercase → IoctlAddTrusted + ConfigSaveTrusted + ConfigLoad
5. Paths panel drop: auto-commits prior g_pendingPath, stores resolved path in g_pendingPath → RefreshLists
6. DragFinish

ResolveLnkPath(rcx=.lnk path, rdx=out buf):

CoInitialize → CoCreateInstance(CLSID_ShellLink) → QueryInterface(IID_IPersistFile) → IPersistFile::Load → IShellLinkW::GetPath → full COM release chain → CoUninitialize

service.asm — Windows Service Runtime

SERVICE_ACCEPT_PRESHUTDOWN (0x100) requires RegisterServiceCtrlHandlerExW (extended variant).

driver_scm.asm — clrcd SCM Lifecycle

Service Control Manager glue for the kernel driver service clrcd.

device.asm — Device Handle + EnsureDriverReady

Owns the kernel device handle and the install-on-demand bootstrap.

ioctl.asm — DeviceIoControl Wrappers

Thin marshalling layer over DeviceIoControl for every IOCTL the driver exposes.

IOCTL Codes (reverse-engineered from vg.sys)

The two SET-style IOCTLs replace their entire in-memory list rather than appending one record. VaultGuard therefore rebuilds and submits the complete active path or trusted-process list after every change.

config.asm — Registry Persistence

cli.asm — Command-Line Interface

Switch comparison uses wcscmp_ci — ASCII case-insensitive wide compare, no CharLowerW. All switches work regardless of capitalization.

Every exit path goes through _CliFinish(code) → ConsoleSendEnter() (injects VK_RETURN via WriteConsoleInputW) so the CMD prompt reappears immediately.

Switch dispatch order: /? → /service → /driver → /uninstall → /enumitems → /enumtrusted → /protection → /setitem → /settrusted → /svcstart → /tray → /autostart → unknown (return 0 → GUI)

RunCmdAndWait(rcx=lpCommandLine) — helper used by /autostart: launches process hidden (CREATE_NO_WINDOW), waits for exit, returns exit code.

export.asm — CSV Export

Owns all enumeration and file-writing logic for /enumitems and /enumtrusted.

CSV is written from registry (authoritative persisted state), not from the driver IOCTL buffer which can lag after flag-change operations.

res.asm — Driver Extraction (FDI)

The driver vg.sys is embedded inside vg.exe as a resource: LZX CAB appended to the ICO file header.

1. FindResourceW(NULL, IDR_DRIVER=102, RT_RCDATA=10) → resource pointer
2. LockResource → raw bytes; CAB starts at offset 1078 bytes
3. All FDI callbacks operate in memory — no temp files on disk
4. FDICopy → heap buffer → WriteFile to %SystemRoot%\system32\drivers\vg.sys

CAB is packed at ~42% of original size via LZX compression.

strutil.asm — String Utilities

listview.asm — ListView Wrappers

Driver Communication Protocol

IOCTL Buffer Formats

Path-list synchronization:

• Each 0x1404-byte record contains [0..3] = DWORD flags and [4..] = the NT path as WCHARs.
• QueryDosDeviceW("C:") resolves the DOS drive to an NT prefix such as \Device\HarddiskVolume3.
• IOCTL_VG_ADD_PATH receives the packed complete list. The original five-record input size is 0x6414 bytes.
• When no active paths remain, VaultGuard sends a syntactically valid system-drive record with flags=0; a completely zero-filled input is accepted but does not reliably remove the driver's final in-memory path.

Trusted-list synchronization:

• Each fixed 0xD94-byte record contains [0..3] = 0 and [4..] = the lowercase executable basename as WCHARs.
• IOCTL_VG_ADD_TRUSTED receives the packed complete list.

IoctlRemoveTrusted:

• nInBufSize = 0 → driver clears entire active trusted list
• Caller must call ConfigLoad afterward to reload remaining entries

IoctlGetStatus → output buffer VG_STATUS (16 bytes):

Protection Flags

Flags combine as bitmask: Hidden + Locked = 0x03, Hidden + Locked + Read-only = 0x07. Disabled = 0x00 means path stored in registry, inactive in driver.

Registry Layout

HKEY_CURRENT_USER\
└── Software\
    └── VG\
        ├── Paths\
        │     "C:\Private\Data"   REG_DWORD  0x00000003   (Hidden + Locked)
        │     "C:\Projects\Work"  REG_DWORD  0x00000004   (Read-only)
        │     "C:\Temp\Archive"   REG_DWORD  0x00000000   (Disabled)
        └── Trusted\
              "totalcmd64.exe"    REG_DWORD  0x00000001
              "explorer.exe"      REG_DWORD  0x00000001

ConfigLoad enumerates both subkeys, packs all active records, and submits each complete list in one IOCTL. The driver holds no persistent state across reboots.

Build System

Build Steps

.\build.ps1

[0] makecab IcoBuilder\vg.sys → LZX CAB → prepend 1078 B ICO header → ICON\vg.ico
[1] rc.exe /c65001 vg.rc → vg.res
[2] ml64.exe /c /Cp /Cx /Zi
    strutil res driver_scm device ioctl config cli export service theme listview handlers drop tray layout procpicker impexp window main
[3] link.exe /SUBSYSTEM:WINDOWS /NODEFAULTLIB /MANIFEST:EMBED /MANIFESTUAC:requireAdministrator
    Libs: kernel32 user32 advapi32 shell32 ole32 dwmapi gdi32 comctl32 uxtheme cabinet
[4] dumpbin — verify: no CRT imports, allowed DLL set only

-SkipRC skips steps 0 and 1 (requires pre-existing vg.res). Intermediates removed on completion.

Project Structure

VaultGuard\
├── x64/
│   ├── consts.inc       EQU constants: IOCTL codes, flags, struct offsets, control IDs
│   ├── globals.inc      EXTRN declarations for globals from main.asm
│   ├── main.asm         Entry point, global data, message loop
│   ├── window.asm       MainWndProc + CreateMainWindow
│   ├── layout.asm       _OnCreate: all controls + UIPI message filters
│   ├── tray.asm         System tray: _TrayAdd, _TrayRemove, _OnTrayMsg
│   ├── theme.asm        Dark mode, Mica, ListView colors
│   ├── handlers.asm     _OnCommand, _OnNotify, UpdateStatusBar, RefreshLists
│   ├── procpicker.asm   ShowProcPicker — running process picker dialog
│   ├── impexp.asm       GuiExportConfig, GuiImportConfig — .vgc file import/export
│   ├── drop.asm         WM_DROPFILES + ResolveLnkPath (IShellLink COM) + trusted panel routing
│   ├── service.asm      Windows service runtime: _SvcStart, _SvcMain, _SvcCtrlHandler
│   ├── listview.asm     _LvAddColumn, _LvInsertItem, _LvGetItemText
│   ├── driver_scm.asm   clrcd SCM lifecycle (Install/Start/Stop/Uninstall/SetStartType)
│   ├── device.asm       Device open/close + EnsureDriverReady
│   ├── ioctl.asm        DeviceIoControl wrappers + path/trusted marshalling
│   ├── config.asm       ConfigLoad/Save/Remove for Paths and Trusted (registry)
│   ├── cli.asm          CliDispatch + RunCmdAndWait + _CliAutostart
│   ├── export.asm       _CliEnumItems, _CliEnumTrusted — CSV export
│   ├── strutil.asm      String utilities + WideWriteLn/WideWriteConsole
│   └── res.asm          ExtractDriver — FDI decompression of CAB from icon
├── tests/
│   ├── cli_test.ps1              84 CLI, lifecycle, registry, CSV, and enforcement checks
│   ├── rule_collision_test.ps1   55 rule-order and collision enforcement checks
│   ├── gui_sync_test.ps1         Native GUI complete-list synchronization regression
│   └── driver_protocol_probe.ps1 Destructive low-level driver protocol probe
├── IcoBuilder/
│   ├── vg.sys           Original driver (source for packaging)
│   └── vg.ico           Base icon (ICO header used as CAB wrapper)
├── images/
│   └── VaultGuard.jpg   Main window screenshot
├── build.ps1            Build script — auto-detects VS + SDK via vswhere.exe
└── LICENSE.md

Regression Tests

tests/cli_test.ps1 contains 84 regression checks. It requires bin\vg.exe, an Administrator context, and an isolated NTFS test volume. The script installs, starts, and removes clrcd as needed and performs a full uninstall check.

powershell -ExecutionPolicy Bypass -File tests\cli_test.ps1 -TestDrive X:
# -KeepOutput   preserves CSV output files in tests\out\

Safety: Never point -TestDrive at a system or data volume. The suite deliberately applies protection to the selected volume root. A temporary NTFS VHD mounted as X: is the recommended target.

tests/rule_collision_test.ps1 -TestDrive X: adds 55 enforcement checks covering the last-rule transition, seven simultaneous paths, six trusted names, reversed update order, same-basename executables, a protected-and-trusted executable, parent/child collisions, No-execution, global on/off, and driver restart persistence.

tests/gui_sync_test.ps1 drives the native window controls and verifies that disabling one path or trusted process keeps the other entries active, and that adding another process preserves the existing trusted list.

tests/driver_protocol_probe.ps1 is the destructive driver-level protocol probe used to confirm SET/replace semantics, the valid zero-flags empty-list transition, overlapping-path behavior, trusted-record layout, and global trust. It refuses to run while clrcd is already active.

Known Limitations

License

MIT License — full text in LICENSE.md.

WARNING: This tool installs a kernel-mode driver (vg.sys) and requires Administrator privileges. The original vg.sys is the property of PROMOSOFT CORPORATION. Use on systems you own or have permission to modify.

Last updated: 2026-08-07 — v1.0.0.3