From cc09cc55fb45804c22a108ee906f4123e4bd273a Mon Sep 17 00:00:00 2001 From: Srikrishna Veturi Date: Tue, 6 Oct 2026 11:15:21 -0600 Subject: [PATCH 1/2] Generate Windows extension catalog Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- build.cmd | 7 ++ doc/GettingStartedWindows.md | 7 ++ .../scripts/New-ExtensionCatalog.ps1 | 77 +++++++++++++++++++ .../src/windows/GuestProxyAgentExtension.cdf | 15 ++++ .../src/windows/HandlerManifest.json | 1 + 5 files changed, 107 insertions(+) create mode 100644 proxy_agent_extension/scripts/New-ExtensionCatalog.ps1 create mode 100644 proxy_agent_extension/src/windows/GuestProxyAgentExtension.cdf diff --git a/build.cmd b/build.cmd index cc8e8eee..f9a84dd4 100644 --- a/build.cmd +++ b/build.cmd @@ -247,6 +247,13 @@ for %%F in (%extension_src_path%\*.cmd) do ( ) xcopy /Y %out_dir%\ProxyAgentExt.* %out_package_proxyagent_extension_dir%\ +echo ======= generate ProxyAgent Extension catalog +call powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%extension_root_path%\scripts\New-ExtensionCatalog.ps1" -ExtensionPackageDirectory "%out_package_proxyagent_extension_dir%" +if %ERRORLEVEL% NEQ 0 ( + echo Extension catalog generation failed with exit-code: %errorlevel% + exit /b %errorlevel% +) + echo ======= copy e2e test project to Package folder SET out_package_e2etest_dir=%out_package_dir%\e2etest echo xcopy /Y /S /C /Q %out_e2etest_dir% %out_package_e2etest_dir%\ diff --git a/doc/GettingStartedWindows.md b/doc/GettingStartedWindows.md index 184f9f5c..0c4ac47a 100644 --- a/doc/GettingStartedWindows.md +++ b/doc/GettingStartedWindows.md @@ -22,6 +22,9 @@ The following must be installed in order to build this project: - `"MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (latest)"` + The selected Windows SDK must include `makecat.exe`, which the build uses to generate the Windows extension catalog. + If the tool is installed outside the standard Windows SDK location, set `MAKECAT_PATH` to its full path before building. + 3. [WDK for Windows 11, version 22H2](https://go.microsoft.com/fwlink/?linkid=2196230) (version **10.0.22621.x**), including the "*Windows Driver Kit Visual Studio extension*" (make sure the "*Install Windows Driver Kit Visual Studio Extension*" check box is checked before completing the installer). @@ -50,6 +53,10 @@ By default this will clone the project under the `GuestProxyAgent` directory. 2. Navigate to this repo root folder. 3. ```build.cmd``` +The Windows build output includes an unsigned `GuestProxyAgentExtension.cat` generated from the extension handler scripts. +Microsoft production signing is applied later by the official release pipeline; catalogs from local and public CI builds +are not trusted production artifacts. + ## Building with Docker If you are prefer an isolated build environment, you can use the Windows Container build image. diff --git a/proxy_agent_extension/scripts/New-ExtensionCatalog.ps1 b/proxy_agent_extension/scripts/New-ExtensionCatalog.ps1 new file mode 100644 index 00000000..997944cf --- /dev/null +++ b/proxy_agent_extension/scripts/New-ExtensionCatalog.ps1 @@ -0,0 +1,77 @@ +[CmdletBinding()] +param( + [Parameter(Mandatory)] + [string] $ExtensionPackageDirectory, + + [string] $MakeCatPath = $env:MAKECAT_PATH +) + +$ErrorActionPreference = 'Stop' + +if (-not (Test-Path -LiteralPath $ExtensionPackageDirectory -PathType Container)) { + throw "Extension package directory does not exist: $ExtensionPackageDirectory" +} + +$handlerFiles = @( + 'disable.cmd' + 'enable.cmd' + 'install.cmd' + 'reset.cmd' + 'uninstall.cmd' + 'update.cmd' +) + +foreach ($handlerFile in $handlerFiles) { + $handlerPath = Join-Path $ExtensionPackageDirectory $handlerFile + if (-not (Test-Path -LiteralPath $handlerPath -PathType Leaf)) { + throw "Catalog input does not exist: $handlerPath" + } +} + +if ([string]::IsNullOrWhiteSpace($MakeCatPath)) { + $makeCatCommand = Get-Command makecat.exe -ErrorAction SilentlyContinue + if ($makeCatCommand) { + $MakeCatPath = $makeCatCommand.Source + } +} + +if ([string]::IsNullOrWhiteSpace($MakeCatPath)) { + $windowsKitsBin = Join-Path ${env:ProgramFiles(x86)} 'Windows Kits\10\bin' + if (Test-Path -LiteralPath $windowsKitsBin -PathType Container) { + $MakeCatPath = Get-ChildItem -LiteralPath $windowsKitsBin -Directory | + Sort-Object Name -Descending | + ForEach-Object { Join-Path $_.FullName 'x64\makecat.exe' } | + Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | + Select-Object -First 1 + } +} + +if ([string]::IsNullOrWhiteSpace($MakeCatPath) -or + -not (Test-Path -LiteralPath $MakeCatPath -PathType Leaf)) { + throw 'makecat.exe was not found. Install the Windows SDK or set MAKECAT_PATH to its full path.' +} + +$catalogDefinitionSource = Join-Path $PSScriptRoot '..\src\windows\GuestProxyAgentExtension.cdf' +$catalogDefinitionPath = Join-Path $ExtensionPackageDirectory 'GuestProxyAgentExtension.cdf' +$catalogPath = Join-Path $ExtensionPackageDirectory 'GuestProxyAgentExtension.cat' + +Copy-Item -LiteralPath $catalogDefinitionSource -Destination $catalogDefinitionPath -Force +Remove-Item -LiteralPath $catalogPath -Force -ErrorAction SilentlyContinue + +Push-Location $ExtensionPackageDirectory +try { + & $MakeCatPath (Split-Path $catalogDefinitionPath -Leaf) + if ($LASTEXITCODE -ne 0) { + throw "makecat.exe failed with exit code $LASTEXITCODE." + } + + if (-not (Test-Path -LiteralPath $catalogPath -PathType Leaf)) { + throw "makecat.exe did not create the expected catalog: $catalogPath" + } +} +finally { + Pop-Location + Remove-Item -LiteralPath $catalogDefinitionPath -Force -ErrorAction SilentlyContinue +} + +Write-Host "Generated extension catalog: $catalogPath" diff --git a/proxy_agent_extension/src/windows/GuestProxyAgentExtension.cdf b/proxy_agent_extension/src/windows/GuestProxyAgentExtension.cdf new file mode 100644 index 00000000..729e4311 --- /dev/null +++ b/proxy_agent_extension/src/windows/GuestProxyAgentExtension.cdf @@ -0,0 +1,15 @@ +[CatalogHeader] +Name=GuestProxyAgentExtension.cat +ResultDir=. +EncodingType=0x00010001 +CatalogVersion=2 +HashAlgorithms=SHA256 +CATATTR1=0x10010001:OSAttr:2:6.2 + +[CatalogFiles] +disable.cmd=disable.cmd +enable.cmd=enable.cmd +install.cmd=install.cmd +reset.cmd=reset.cmd +uninstall.cmd=uninstall.cmd +update.cmd=update.cmd diff --git a/proxy_agent_extension/src/windows/HandlerManifest.json b/proxy_agent_extension/src/windows/HandlerManifest.json index 16d82ca6..63e3ec50 100644 --- a/proxy_agent_extension/src/windows/HandlerManifest.json +++ b/proxy_agent_extension/src/windows/HandlerManifest.json @@ -8,6 +8,7 @@ "disableCommand": "disable.cmd", "rebootAfterInstall": "false", "reportHeartbeat": "true", + "catalogFileName": "GuestProxyAgentExtension.cat", "resetStateCommand": "reset.cmd", "supportMultipleExtensions": "false" }, From ef0f1e364cc5f041b462f6bad40fc54a0a7a3da3 Mon Sep 17 00:00:00 2001 From: Srikrishna Veturi Date: Tue, 6 Oct 2026 11:33:24 -0600 Subject: [PATCH 2/2] Add catalog signing terms to spell check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cspell.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cspell.json b/cspell.json index 8ae512d8..a7f39ba6 100644 --- a/cspell.json +++ b/cspell.json @@ -106,6 +106,7 @@ "bytecodealliance", "callouts", "canonicalizer", + "catattr", "cbl", "ccbdee", "ccbf", @@ -302,6 +303,7 @@ "kprobe", "ktime", "kusto", + "lastexitcode", "lbl", "lgrui", "libbpf", @@ -321,6 +323,7 @@ "ltsc", "luid", "macikgo", + "makecat", "managedidentity", "maxdepth", "mcr",