Feature/windows extension catalog generation

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%\

cspell.json

@@ -106,6 +106,7 @@
     "bytecodealliance",
     "callouts",
     "canonicalizer",
+    "catattr",
     "cbl",
     "ccbdee",
     "ccbf",
@@ -304,6 +305,7 @@
     "kprobe",
     "ktime",
     "kusto",
+    "lastexitcode",
     "lbl",
     "lgrui",
     "libbpf",
@@ -323,6 +325,7 @@
     "ltsc",
     "luid",
     "macikgo",
+    "makecat",
     "managedidentity",
     "maxdepth",
     "mcr",

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.

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"

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]
+<HASH>disable.cmd=disable.cmd
+<HASH>enable.cmd=enable.cmd
+<HASH>install.cmd=install.cmd
+<HASH>reset.cmd=reset.cmd
+<HASH>uninstall.cmd=uninstall.cmd
+<HASH>update.cmd=update.cmd

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"
     },