VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/_sigcheck.ps1

@@ -0,0 +1,32 @@
+$ErrorActionPreference = 'Stop'
+# Read the file list from stdin. Using stdin (rather than TLS arguments) keeps paths with
+# spaces, quotes or non-ASCII characters safe and avoids relying on `$args` binding rules,
+# which differ between PowerShell 5.1 and PowerShell 7.
+$paths = @($input)
+$out = New-Object System.Collections.ArrayList
+foreach ($p in $paths) {
+  $line = "$p".Trim()
+  if (-not $line) { continue }
+  $entry = [ordered]@{ path = $line; ok = $false; status = 'unknown'; subject = ''; issuer = ''; thumbprint = ''; kind = 'none'; message = ''; error = '' }
+  try {
+    $sig = Get-AuthenticodeSignature -LiteralPath $line -ErrorAction Stop
+    $entry.status = "$($sig.Status)"
+    $entry.message = "$($sig.StatusMessage)"
+    if ($sig.SignerCertificate) {
+      $entry.subject = "$($sig.SignerCertificate.Subject)"
+      $entry.issuer = "$($sig.SignerCertificate.Issuer)"
+      $entry.thumbprint = "$($sig.SignerCertificate.Thumbprint)"
+    }
+    $props = @($sig.PSObject.Properties.Name)
+    if ($props -contains 'SignatureType') { $entry.kind = "$($sig.SignatureType)".ToLower() }
+    elseif ($sig.IsOSBinary) { $entry.kind = 'os' }
+    else { $entry.kind = 'embedded' }
+    $entry.ok = ($entry.status -eq 'Valid')
+  } catch {
+    $entry.status = 'unknown-error'
+    $entry.error = "$($_.Exception.Message)"
+  }
+  [void]$out.Add([pscustomobject]$entry)
+}
+$json = ConvertTo-Json -InputObject @($out) -Compress -Depth 4
+[Console]::Out.WriteLine($json)

VirtualDesktop/_sigcheck.py

@@ -0,0 +1,321 @@
+"""Authenticode verification for driver packages.
+
+The manifest pins SHA-256 digests, which already protects against a swapped mirror.  This
+module adds *defence in depth*: after extraction (and before the driver is handed to the
+Windows installer) the signature is verified and the signer certificate thumbprint is compared
+against the manifest allow-list.  A revoked or unexpected signer is reported instead of being
+installed silently.
+
+Why verification is delegated to PowerShell's ``Get-AuthenticodeSignature``
+--------------------------------------------------------------------------
+A direct ``WinVerifyTrust`` implementation through ``ctypes`` was written and **removed again**:
+on this machine every call — including for known-good system binaries such as
+``notepad.exe`` — returned ``TRUST_E_PROVIDER_UNKNOWN`` (``0x800B0001``) regardless of the
+``WINTRUST_DATA`` layout or the ``hwnd`` value used.  A verifier that answers "cannot verify"
+for everything is worse than no verifier, because it looks like a checked result.  The PowerShell
+cmdlet uses the same WinVerifyTrust path ``signtool verify`` uses and returns the real answer
+(measured on the driver package: ``mttvdd.cat`` and ``MttVDD.dll`` both ``Valid``, signer
+``CN=SignPath Foundation``).  When no verifier is available the result is ``UNKNOWN``, never
+``VALID``.
+
+``SIGNATURE_TARGETS`` deliberately checks the PE files *before* the catalog: a catalog carries no
+signer certificate, so it can never satisfy the thumbprint allow-list, while ``MttVDD.dll`` does.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence
+
+from ._log import get_logger
+from .errors import DriverVerificationError
+
+log = get_logger("sigcheck")
+
+__all__ = ["SignatureStatus", "SignatureReport", "verify_signer", "evaluate_trust", "POWERSHELL"]
+
+POWERSHELL = "powershell.exe"
+_CREATE_NO_WINDOW = 0x08000000
+
+#: Files inside a driver package that must carry a trusted signature.  The PE files come first so
+#: that a signer thumbprint is available for the allow-list check; the catalog is verified too and
+#: is what Windows itself enforces when the driver is installed.
+SIGNATURE_TARGETS = (".dll", ".sys", ".cat")
+
+
+class SignatureStatus(str, Enum):
+    VALID = "valid"
+    NOT_SIGNED = "not-signed"
+    HASH_MISMATCH = "hash-mismatch"
+    NOT_TRUSTED = "not-trusted"
+    UNKNOWN_ERROR = "unknown-error"
+    UNKNOWN = "unknown"
+
+
+_TRUSTED_STATUSES = {SignatureStatus.VALID.value}
+_BAD_STATUSES = {
+    SignatureStatus.NOT_SIGNED.value,
+    SignatureStatus.HASH_MISMATCH.value,
+    SignatureStatus.NOT_TRUSTED.value,
+}
+
+
+@dataclass
+class SignatureReport:
+    path: Path
+    status: SignatureStatus = SignatureStatus.UNKNOWN
+    subject: str = ""
+    issuer: str = ""
+    thumbprint: str = ""
+    kind: str = "none"  # embedded | catalog | none
+    message: str = ""
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status is SignatureStatus.VALID
+
+    def to_dict(self) -> dict:
+        return {
+            "path": str(self.path),
+            "status": self.status.value,
+            "subject": self.subject,
+            "issuer": self.issuer,
+            "thumbprint": self.thumbprint,
+            "kind": self.kind,
+            "message": self.message,
+            "error": self.error,
+            "ok": self.ok,
+        }
+
+
+_SCRIPT_PATH = Path(__file__).with_name("_sigcheck.ps1")
+
+
+def _fallback_script() -> str:
+    """Inline equivalent of ``_sigcheck.ps1`` for the (unlikely) case it is missing."""
+    try:
+        return _SCRIPT_PATH.read_text(encoding="utf-8")
+    except OSError:  # pragma: no cover - packaged wheels always ship the file
+        return (
+            "$paths=@($input);$out=New-Object System.Collections.ArrayList;"
+            "foreach($p in $paths){$line=\"$p\".Trim();if(-not $line){continue};"
+            "$e=[ordered]@{path=$line;ok=$false;status='unknown';subject='';issuer='';"
+            "thumbprint='';kind='none';message='';error=''};"
+            "try{$s=Get-AuthenticodeSignature -LiteralPath $line -ErrorAction Stop;"
+            "$e.status=\"$($s.Status)\";$e.message=\"$($s.StatusMessage)\";"
+            "if($s.SignerCertificate){$e.subject=\"$($s.SignerCertificate.Subject)\";"
+            "$e.issuer=\"$($s.SignerCertificate.Issuer)\";"
+            "$e.thumbprint=\"$($s.SignerCertificate.Thumbprint)\"};"
+            "if(@($s.PSObject.Properties.Name) -contains 'SignatureType'){$e.kind=\"$($s.SignatureType)\".ToLower()}"
+            "elseif($s.IsOSBinary){$e.kind='os'}else{$e.kind='embedded'};$e.ok=($e.status -eq 'Valid')}"
+            "catch{$e.status='unknown-error';$e.error=\"$($_.Exception.Message)\"};"
+            "[void]$out.Add([pscustomobject]$e)};"
+            "[Console]::Out.WriteLine((ConvertTo-Json -InputObject @($out) -Compress -Depth 4))"
+        )
+
+
+def _powershell_path() -> Optional[str]:
+    found = shutil.which(POWERSHELL)
+    return found
+
+
+def verify_signer(paths: Sequence[os.PathLike], *, timeout: float = 120.0) -> List[SignatureReport]:
+    """Verify Authenticode signatures for one or more files in a single PowerShell call.
+
+    The file list travels through a UTF-8 scratch file that the verifier reads, rather than over
+    stdin or through the command line.  Both alternatives were measured and rejected:
+
+    * piping ``script + "\\n" + paths`` into ``powershell -Command -`` produced **no output at
+      all** on Windows PowerShell 5.1 — the verifier answered ``[]`` for a driver package whose
+      signatures are both valid, which reads like "nothing is signed";
+    * passing the paths as command-line arguments needs quoting rules that differ between
+      PowerShell 5.1 and 7 and break on paths containing quotes.
+
+    A file has neither problem, and ``Get-Content -Encoding UTF8`` keeps non-ASCII paths intact.
+    """
+    targets = [Path(p) for p in paths]
+    if not targets:
+        return []
+    unknown = [
+        SignatureReport(path=target, status=SignatureStatus.UNKNOWN, error="verifier-unavailable")
+        for target in targets
+    ]
+    if os.name != "nt":  # pragma: no cover - Windows-only library
+        return [
+            SignatureReport(path=t, status=SignatureStatus.UNKNOWN, error="not-windows")
+            for t in targets
+        ]
+    ps = _powershell_path()
+    if not ps:
+        log.warning("no powershell.exe available; signature verification reported as unknown")
+        return unknown
+
+    script = _SCRIPT_PATH if _SCRIPT_PATH.is_file() else None
+    scratch_dir = Path(tempfile.mkdtemp(prefix="VirtualDesktop-sigcheck-"))
+    list_path = scratch_dir / "paths.txt"
+    try:
+        list_path.write_text("\n".join(str(t) for t in targets) + "\n", encoding="utf-8")
+        if script is not None:
+            expression = (
+                f"Get-Content -LiteralPath '{list_path}' -Encoding UTF8 | "
+                f"& '{script}'"
+            )
+            command = [
+                ps, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-Command", expression,
+            ]
+            stdin_payload = None
+        else:  # pragma: no cover - packaged wheels always ship the script
+            command = [
+                ps, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-Command", "-",
+            ]
+            stdin_payload = _fallback_script() + "\n"
+        try:
+            completed = subprocess.run(
+                command,
+                input=stdin_payload,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                creationflags=_CREATE_NO_WINDOW,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:  # pragma: no cover - env specific
+            log.warning("signature verification failed to run: %s", exc)
+            return [
+                SignatureReport(path=t, status=SignatureStatus.UNKNOWN, error=str(exc))
+                for t in targets
+            ]
+    finally:
+        shutil.rmtree(scratch_dir, ignore_errors=True)
+
+    payload = (completed.stdout or "").strip()
+    if not payload:
+        return [
+            SignatureReport(
+                path=t,
+                status=SignatureStatus.UNKNOWN,
+                error=(completed.stderr or "").strip()[:500] or "empty verifier output",
+            )
+            for t in targets
+        ]
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as exc:  # pragma: no cover - defensive
+        log.warning("could not parse signature report: %s", exc)
+        return unknown
+    if isinstance(data, dict):
+        data = [data]
+    by_path: dict = {}
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        raw_status = str(item.get("status", "unknown")).strip().lower().replace(" ", "-")
+        try:
+            status = SignatureStatus(raw_status)
+        except ValueError:
+            status = SignatureStatus.UNKNOWN
+        report = SignatureReport(
+            path=Path(str(item.get("path", ""))),
+            status=status,
+            subject=str(item.get("subject", "")),
+            issuer=str(item.get("issuer", "")),
+            thumbprint=str(item.get("thumbprint", "")).replace(" ", "").upper(),
+            kind=str(item.get("kind", "none")),
+            message=str(item.get("message", "")),
+            error=str(item.get("error", "")),
+        )
+        by_path[str(report.path).lower()] = report
+    return [by_path.get(str(t).lower(), unknown[i]) for i, t in enumerate(targets)]
+
+
+def evaluate_trust(
+    reports: Iterable[SignatureReport],
+    trusted_thumbprints: Sequence[str],
+    *,
+    strict: bool = False,
+) -> tuple:
+    """Fold signature reports into ``(trusted, findings)``.
+
+    ``trusted`` is True only when at least one *driver-significant* file has a valid
+    signature and no report is outright bad.  ``findings`` is a list of human-readable
+    lines suitable for a warning banner or a CLI report.
+    """
+    trusted_set = {t.replace(" ", "").upper() for t in trusted_thumbprints if t}
+    findings: List[str] = []
+    any_valid = False
+    bad = False
+    for report in reports:
+        if report.status is SignatureStatus.VALID:
+            any_valid = True
+            if trusted_set and report.thumbprint not in trusted_set:
+                findings.append(
+                    f"{report.path.name}: signed by an unexpected publisher "
+                    f"({report.subject or 'unknown'}, thumbprint {report.thumbprint or 'n/a'})"
+                )
+                if strict:
+                    bad = True
+            else:
+                findings.append(f"{report.path.name}: valid signature ({report.subject})")
+        elif report.status.value in _BAD_STATUSES:
+            findings.append(
+                f"{report.path.name}: signature {report.status.value} ({report.message or report.error})"
+            )
+            bad = True
+        else:
+            findings.append(
+                f"{report.path.name}: signature could not be verified "
+                f"({report.error or report.message or report.status.value})"
+            )
+            if strict:
+                bad = True
+    if not any_valid:
+        findings.append("no file in the driver package carried a verifiable signature")
+        bad = True
+    return (any_valid and not bad), findings
+
+
+def assert_driver_trusted(
+    inf_dir: os.PathLike,
+    trusted_thumbprints: Sequence[str],
+    *,
+    strict: bool = False,
+    policy: str = "warn",
+) -> List[str]:
+    """Verify the driver package next to ``MttVDD.inf``.
+
+    ``policy`` is ``warn`` (log and continue), ``strict`` (raise on any doubt) or ``off``.
+    Returns the findings so the caller can surface them in a report.
+    """
+    if policy == "off":
+        return ["signature verification disabled by configuration"]
+    directory = Path(inf_dir)
+    targets = sorted(
+        (p for p in directory.iterdir() if p.is_file() and p.suffix.lower() in SIGNATURE_TARGETS),
+        # PE files first so a signer certificate is available for the allow-list check.
+        key=lambda p: (SIGNATURE_TARGETS.index(p.suffix.lower()), p.name),
+    )
+    if not targets:
+        return ["no signature targets found next to the INF"]
+    reports = verify_signer(targets)
+    trusted, findings = evaluate_trust(reports, trusted_thumbprints, strict=strict)
+    for line in findings:
+        log.info("driver signature: %s", line)
+    if not trusted:
+        message = "driver package signature verification did not succeed: " + "; ".join(findings)
+        if policy == "strict" or strict:
+            raise DriverVerificationError(
+                message,
+                code="driver-signature-untrusted",
+                hint="Re-download the driver, or pin the expected signer thumbprint in your manifest.",
+            )
+        log.warning("%s (continuing because signature_policy='warn')", message)
+    return findings