fix(install): detect Windows Defender AV block and emit specific guidance (#1408)

* fix(install): detect Windows Defender AV block and emit specific guidance

The Windows installer (and 'apm self-update') failed on hosts where
Defender or another real-time scanner flags the unsigned PyInstaller
apm.exe as potentially unwanted software (HRESULT 0x800700E1). The
binary smoke test threw 'Operation did not complete successfully
because the file contains a virus or potentially unwanted software',
which Test-AccessDeniedError did not match, so the installer fell
through to a generic 'failed to run' message and a pip fallback that
itself died on hosts running an unsupported Python (e.g. 3.14).

Changes:

- install.ps1: add Test-AntivirusBlockError mirroring the existing
  Test-AccessDeniedError contract. Matches the Defender PUA message,
  the generic 'contains a virus' / 'potentially unwanted software'
  phrasing, and HRESULTs 0x800700E1 and 0x800704EC.
- install.ps1: add Write-AntivirusGuidance with three actionable
  options - Add-MpPreference -ExclusionPath on the install root,
  pip --user fallback, and the Microsoft false-positive submission
  URL. Wired into the testFailure branch ahead of the AppLocker
  guidance check; the two error classes are distinct.
- docs/installation.md: add a troubleshooting subsection mirroring
  the existing AppLocker/WDAC one, documenting the same three
  recovery options.
- scripts/windows/test-install-script.ps1: add Test-AntivirusDetector
  covering real Defender output, generic PUA text, both HRESULTs, the
  cross-class case (access-denied must not be classified as AV), and
  empty/benign strings. Cases verified locally against the install.ps1
  functions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fixup(windows-installer): correct AV vs policy HRESULT classification

Address review feedback on PR #1408:

1. CRITICAL: 0x800704EC is ERROR_ACCESS_DISABLED_BY_POLICY (GPO/SRP),
   NOT ERROR_VIRUS_DELETED. The correct deleted-by-AV HRESULT is
   0x800700E2. Misclassifying a policy block as AV would prompt users
   to add a Defender exclusion to fix what is actually a Group Policy
   rule -- net regression vs pre-PR generic handler.
   - Test-AntivirusBlockError: drop 0x800704EC, add 0x800700E2.
   - Test-AccessDeniedError: add 0x800704EC and the standard SRP/GPO
     'blocked by group policy' message string. These belong in the
     AppControl/AppLocker guidance bucket.

2. Soften 'not actually malicious' framing. In a real supply-chain
   compromise this code path would still fire; an unconditional safety
   claim is poor security hygiene. Reword conditionally and tell users
   to verify the published .sha256 sidecar BEFORE excluding the binary.

3. Single-quote-escape $TargetInstallDir in the printed
   Add-MpPreference command so the suggestion stays valid for paths
   containing a single quote.

4. Stop leaking GetTempFileName() zero-byte companions in the test
   harness. Use GetRandomFileName under $env:TEMP for both .ps1 temp
   files in scripts/windows/test-install-script.ps1.

5. Replace brittle 'Select-Object -Last 1' JSON parsing with explicit
   ---APM-JSON-BEGIN---/---APM-JSON-END--- sentinels so child-pwsh
   profile output cannot corrupt the parsed JSON.

6. Expand Test-AntivirusDetector cases to cover both corrected AV
   HRESULTs (0x800700E1, 0x800700E2) and the GPO/SRP cross-class
   disambiguation (0x800704EC must route to AccessDenied, not AV).

Validated locally with pwsh: 9/9 cross-class detector cases pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Daniel Meppiel <copilot-rework@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

install.ps1

@@ -275,12 +275,39 @@ function Get-Sha256Hex {
 }
 
 function Test-AccessDeniedError {
-    # AppLocker / WDAC / App Control for Business denies CreateProcess on EXEs
-    # under user-writable paths (e.g. %TEMP%, %LOCALAPPDATA%\Temp) with HRESULT
-    # 0x80070005 (E_ACCESSDENIED), surfaced by PowerShell as "Access is denied".
+    # AppLocker / WDAC / App Control for Business / SRP / Group Policy deny
+    # CreateProcess on EXEs under user-writable paths (e.g. %TEMP%,
+    # %LOCALAPPDATA%\Temp) with one of:
+    #   0x80070005 (E_ACCESSDENIED, Win32 5)         -> "Access is denied"
+    #   0x800704EC (ERROR_ACCESS_DISABLED_BY_POLICY, -> "This program is
+    #               Win32 1260)                          blocked by group policy"
+    # Both belong in the AppControl/AppLocker guidance bucket.
     param([string]$Text)
     if (-not $Text) { return $false }
-    return ($Text -match 'Access is denied' -or $Text -match '0x80070005')
+    return (
+        $Text -match 'Access is denied' -or
+        $Text -match 'blocked by group policy' -or
+        $Text -match '0x80070005' -or
+        $Text -match '0x800704EC'
+    )
+}
+
+function Test-AntivirusBlockError {
+    # Defender / 3rd-party AV real-time protection blocks CreateProcess on
+    # binaries it flags with HRESULT 0x800700E1 (ERROR_VIRUS_INFECTED,
+    # Win32 225) or 0x800700E2 (ERROR_VIRUS_DELETED, Win32 226). PowerShell
+    # surfaces these as "Operation did not complete successfully because
+    # the file contains a virus or potentially unwanted software". Our
+    # PyInstaller-built apm.exe is unsigned, which routinely trips
+    # false-positive heuristics.
+    param([string]$Text)
+    if (-not $Text) { return $false }
+    return (
+        $Text -match 'contains a virus' -or
+        $Text -match 'potentially unwanted software' -or
+        $Text -match '0x800700E1' -or
+        $Text -match '0x800700E2'
+    )
 }
 
 function Write-AppControlGuidance {
@@ -309,6 +336,44 @@ function Write-AppControlGuidance {
     Write-Host ""
 }
 
+function Write-AntivirusGuidance {
+    param(
+        [string]$Path,
+        [string]$TargetInstallDir
+    )
+    Write-Host ""
+    Write-ErrorText "An antivirus product blocked execution of $Path."
+    Write-Host "Windows Defender (or another real-time scanner) flagged the binary."
+    Write-Host "The apm.exe release is built with PyInstaller and is currently"
+    Write-Host "unsigned, which routinely trips false-positive heuristics on"
+    Write-Host "unsigned binaries. Most blocks of apm.exe are false positives, but"
+    Write-Host "you should verify integrity before excluding it:"
+    Write-Host ""
+    Write-Host "  1. Verify the SHA256 of apm.exe against the published .sha256"
+    Write-Host "     sidecar on the release page before adding any AV exclusion."
+    Write-Host "     Do not exclude a binary whose checksum you have not verified."
+    Write-Host ""
+    Write-Info "If the checksum matches, options to unblock:"
+    if ($TargetInstallDir) {
+        # Single-quote-escape the path so the printed command stays valid
+        # even if the install directory contains a "'" character (rare but
+        # possible in usernames).
+        $escapedDir = $TargetInstallDir -replace "'", "''"
+        Write-Host "  a. Add a Defender exclusion for the install directory (run in"
+        Write-Host "     an elevated PowerShell, then rerun this installer):"
+        Write-Host "       Add-MpPreference -ExclusionPath '$escapedDir'"
+    } else {
+        Write-Host "  a. Add a Defender exclusion for apm.exe (run in an elevated"
+        Write-Host "     PowerShell, then rerun this installer):"
+        Write-Host "       Add-MpPreference -ExclusionProcess 'apm.exe'"
+    }
+    Write-Host "  b. Install via pip into your user site (avoids the binary entirely):"
+    Write-Host "       pip install --user apm-cli"
+    Write-Host "  c. Help us get the false positive cleared by submitting the binary"
+    Write-Host "     to Microsoft: https://www.microsoft.com/en-us/wdsi/filesubmission"
+    Write-Host ""
+}
+
 # ---------------------------------------------------------------------------
 # Banner
 # ---------------------------------------------------------------------------
@@ -645,8 +710,11 @@ try {
 
     if ($testFailure) {
         $denied = Test-AccessDeniedError -Text $testFailure
+        $avBlocked = Test-AntivirusBlockError -Text $testFailure
         Write-ErrorText "Downloaded binary failed to run: $testFailure"
-        if ($denied) {
+        if ($avBlocked) {
+            Write-AntivirusGuidance -Path $stagedExe -TargetInstallDir $releaseDir
+        } elseif ($denied) {
             Write-AppControlGuidance -Path $stagedExe -TargetInstallDir $releaseDir
         }
         Remove-Item -Recurse -Force $stagingDir -ErrorAction SilentlyContinue

scripts/windows/test-install-script.ps1

@@ -83,7 +83,7 @@ Remove-Module Microsoft.PowerShell.Utility -Force -ErrorAction SilentlyContinue
 $($match.Value)
 Write-Output (Get-Sha256Hex -Path '$tempFile')
 "@
-        $childScriptPath = [System.IO.Path]::GetTempFileName() + ".ps1"
+        $childScriptPath = [System.IO.Path]::Combine($env:TEMP, [System.IO.Path]::GetRandomFileName() + ".ps1")
         Set-Content -Path $childScriptPath -Value $childScript -Encoding UTF8
         try {
             $actual = & powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $childScriptPath 2>&1
@@ -145,6 +145,91 @@ function Test-MoveThenTestOrdering {
     }
 }
 
+# ---------------------------------------------------------------------------
+# Test 2b: Test-AntivirusBlockError detects Windows Defender / AV signatures.
+# Issue: Defender flags the unsigned PyInstaller binary as PUA (HRESULT
+# 0x800700E1), and the installer must distinguish that from AppLocker /
+# WDAC denial so it can emit the right guidance (exclusion + pip fallback,
+# not allow-list rule).
+# ---------------------------------------------------------------------------
+
+function Test-AntivirusDetector {
+    Write-Step "Test 2b: Test-AntivirusBlockError matches Defender PUA signatures"
+
+    $content = Get-Content $InstallScript -Raw
+    $pattern = '(?s)function Test-AntivirusBlockError\s*\{.*?\n\}'
+    $match = [regex]::Match($content, $pattern)
+    Assert-True $match.Success "Extracted Test-AntivirusBlockError from install.ps1"
+    if (-not $match.Success) { return }
+
+    $accessPattern = '(?s)function Test-AccessDeniedError\s*\{.*?\n\}'
+    $accessMatch = [regex]::Match($content, $accessPattern)
+    Assert-True $accessMatch.Success "Extracted Test-AccessDeniedError from install.ps1"
+    if (-not $accessMatch.Success) { return }
+
+    $childScript = @"
+`$ErrorActionPreference = 'Stop'
+$($match.Value)
+$($accessMatch.Value)
+
+# Real Defender failure text from issue #1389 follow-up:
+`$defenderMsg = "Program 'apm.exe' failed to run: Operation did not complete successfully because the file contains a virus or potentially unwanted softwareAt C:\\Users\\X\\AppData\\Local\\Temp\\tmpfoo.ps1:639 char:23"
+`$puaMsg      = "blocked: potentially unwanted software detected"
+`$hresultMsg  = "CreateProcess failed with 0x800700E1"
+`$deletedMsg  = "Operation failed with 0x800700E2 (file removed by antivirus)"
+`$accessMsg   = "Program 'apm.exe' failed to run: Access is denied"
+`$gpoMsg      = "This program is blocked by group policy. For more information, contact your system administrator. (0x800704EC)"
+`$benignMsg   = "exit code 1 - apm: command not found"
+
+`$results = @{
+    defender_match = (Test-AntivirusBlockError -Text `$defenderMsg)
+    pua_match      = (Test-AntivirusBlockError -Text `$puaMsg)
+    hresult_match  = (Test-AntivirusBlockError -Text `$hresultMsg)
+    deleted_match  = (Test-AntivirusBlockError -Text `$deletedMsg)
+    access_no_av   = (-not (Test-AntivirusBlockError -Text `$accessMsg))
+    gpo_no_av      = (-not (Test-AntivirusBlockError -Text `$gpoMsg))
+    benign_no_av   = (-not (Test-AntivirusBlockError -Text `$benignMsg))
+    empty_no_av    = (-not (Test-AntivirusBlockError -Text ''))
+    # Cross-class: AppLocker/SRP/GPO must NOT be misclassified as AV.
+    defender_not_access = (-not (Test-AccessDeniedError -Text `$defenderMsg))
+    # GPO/SRP block (0x800704EC) belongs in the AppControl bucket, not AV.
+    gpo_is_access  = (Test-AccessDeniedError -Text `$gpoMsg)
+    access_is_access = (Test-AccessDeniedError -Text `$accessMsg)
+}
+Write-Output '---APM-JSON-BEGIN---'
+Write-Output (`$results | ConvertTo-Json -Compress)
+Write-Output '---APM-JSON-END---'
+"@
+
+    # Use GetRandomFileName so we don't leak the GetTempFileName-created
+    # zero-byte .tmp companion file every run.
+    $tempScript = [System.IO.Path]::Combine($env:TEMP, [System.IO.Path]::GetRandomFileName() + ".ps1")
+    try {
+        Set-Content -Path $tempScript -Value $childScript -Encoding UTF8
+        $raw = & pwsh -NoProfile -NonInteractive -File $tempScript 2>&1
+        $lines = ($raw | Out-String) -split "`r?`n"
+        $begin = [Array]::IndexOf($lines, '---APM-JSON-BEGIN---')
+        $end   = [Array]::IndexOf($lines, '---APM-JSON-END---')
+        Assert-True (($begin -ge 0) -and ($end -gt $begin)) "Located JSON sentinels in child output"
+        if (($begin -lt 0) -or ($end -le $begin)) { return }
+        $json = ($lines[($begin + 1)..($end - 1)] -join '').Trim()
+        $r = $json | ConvertFrom-Json
+        Assert-True ([bool]$r.defender_match)      "Matches real Defender 'contains a virus' message"
+        Assert-True ([bool]$r.pua_match)           "Matches 'potentially unwanted software' message"
+        Assert-True ([bool]$r.hresult_match)       "Matches HRESULT 0x800700E1 (ERROR_VIRUS_INFECTED)"
+        Assert-True ([bool]$r.deleted_match)       "Matches HRESULT 0x800700E2 (ERROR_VIRUS_DELETED)"
+        Assert-True ([bool]$r.access_no_av)        "Does not misclassify 'Access is denied' as AV block"
+        Assert-True ([bool]$r.gpo_no_av)           "Does not misclassify GPO/SRP block (0x800704EC) as AV"
+        Assert-True ([bool]$r.benign_no_av)        "Does not misclassify benign failure text as AV block"
+        Assert-True ([bool]$r.empty_no_av)         "Does not match empty input"
+        Assert-True ([bool]$r.defender_not_access) "Defender message is not classified as AppLocker/WDAC"
+        Assert-True ([bool]$r.gpo_is_access)       "GPO/SRP block (0x800704EC) routes to AppControl guidance"
+        Assert-True ([bool]$r.access_is_access)    "'Access is denied' still routes to AppControl guidance"
+    } finally {
+        Remove-Item -Path $tempScript -Force -ErrorAction SilentlyContinue
+    }
+}
+
 # ---------------------------------------------------------------------------
 # Test 3: Run install.ps1 end-to-end into an isolated prefix.
 # ---------------------------------------------------------------------------
@@ -392,6 +477,7 @@ Write-Host ""
 
 Test-Sha256Fallback
 Test-MoveThenTestOrdering
+Test-AntivirusDetector
 Test-EndToEndInstall
 Test-CrossVersionUpgrade
 Test-SameVersionReinstall