A controlled Windows VM sandbox for UI analysis, automation, and evidence collection.
UIAnalysis Sandbox is a controlled foundation for launching an isolated Windows guest, running a guest-side UI collector, and storing UI trees, screenshots, palette data, process snapshots, and evidence manifests outside the repository.
It is a control foundation, not a complete UI extraction product. It is also not a general-purpose malware sandbox and does not expose arbitrary shell execution.
| Path | Purpose |
|---|---|
tools/sandboxctl.ps1 |
Stable public automation CLI with a JSON envelope |
tools/vmctl.ps1 |
Low-level VMware Workstation control and guest file/process operations |
tools/vmware-dialog-watcher.ps1 |
Opt-in, short-lived VMware informational dialog observer |
tools/labctl.ps1 |
Analysis run orchestration and evidence collection |
tools/guest/ui-agent.ps1 |
Guest-side UI Automation and screenshot collector |
guest/bootstrap/ |
Optional Windows development base provisioning scripts |
mcp/ |
Dependency-free MCP stdio adapter over sandboxctl |
config/ |
Sanitized configuration templates |
docs/ |
CLI contracts and maintainer development notes |
- VM credentials stay in the local user configuration store.
- Host file access is restricted by configured read/write roots.
- The MCP surface exposes fixed operations, not arbitrary shell commands.
- Snapshot restore and VM power-state changes require explicit confirmation.
- VMware dialog handling defaults to detect-only and never uses coordinates or global keyboard input.
- Evidence and audit files are written under
%LOCALAPPDATA%, not the repo.
See SECURITY.md for the full security policy.
The host-side control plane does not require GitHub. The optional guest bootstrap package downloads PowerShell or Git directly from GitHub when they are missing or outdated, and uses winget for the remaining development tools.
The bootstrap is run only after outbound HTTPS/TCP 443 is available, DNS resolution and the system clock are correct, and any required proxy or TLS-inspection configuration is in place. See guest/bootstrap/README-WindowsDevBase.md for the complete GitHub, winget, proxy, retry, and offline-installer guidance.
The following checks are required before configuring credentials, creating a baseline snapshot, or restoring a VM.
- VMware Workstation must be installed, and
vmrun.exemust be available. The host-side scripts support Windows PowerShell 5.1 and PowerShell 7. - A Windows guest with VMware Tools installed and running is required.
- The guest network must be reachable, and the guest account must have a working password.
.\tools\vmctl.ps1 -Action Doctormust be run and all reported errors resolved before the baseline snapshot is created.
If the PowerShell execution policy blocks .ps1 files, bypass it only for the
current process:
Set-ExecutionPolicy -Scope Process BypassA single script can also be launched with:
powershell -NoProfile -ExecutionPolicy Bypass -File .\script.ps1The machine-wide execution policy should not be changed just to run this project.
- Snapshot names such as
Clean_windowsmust not be hardcoded. The actual names are listed and passed with-Snapshot <name>, ordefaultSnapshotis set. If multiple snapshots exist and neither is set, restore fails before changing the VM. - The baseline snapshot must be created after the guest password is set. A pre-password snapshot can be listed, but guest login and automated script execution will fail against it.
- The DPAPI credential store is the normal option. Plaintext credentials are appropriate only in a disposable test VM and must not be committed.
- A snapshot restore may power off the VM. VMware Tools and the guest IP must be ready before an analysis run starts.
- VMware Snapshot Manager must not be operated while a restore is running. If VMware reports an error dialog, close it before retrying.
- VMware dialog handling defaults to
Detect. After a VMware upgrade or when a new dialog type appears, keep detect-only mode until the dialog has been reviewed. - Credentials, VMX files, screenshots, run results, and VM files must remain outside the repository. Host file access is limited to the configured read/write roots.
- NAT is supported, but the guest IP must be discoverable. A
Doctorfailure requires VMware Tools, the guest network adapter, or the guest firewall to be corrected before analysis runs. - The optional guest bootstrap requires access to GitHub and winget unless
offline installers are provided. Offline files are placed in
C:\Dev\downloads, and their SHA-256 values must match the manifest.
The following commands are run from the project root:
# Inspect the host-side VM configuration.
.\tools\vmctl.ps1 -Action Doctor -AsJson
# Run one analysis pass against an already prepared guest.
.\tools\labctl.ps1 -Action Run -WaitSec 3 -AsJson
# Inspect the stable public CLI.
.\tools\sandboxctl.ps1 -Action Status -AsJson
# Start and inspect an asynchronous operation.
$start = .\tools\sandboxctl.ps1 -Action RunStart -WaitSec 3 -AsJson | ConvertFrom-Json
.\tools\sandboxctl.ps1 -Action RunStatus -OperationId $start.operationId -AsJson
.\tools\sandboxctl.ps1 -Action RunResult -OperationId $start.operationId -AsJsonRunStart is not read-only. Even without -StartVm or -RestoreAfter, it
launches the guest program, creates guest-side temporary files and evidence,
and may change guest state. The RUN_STATECHANGE confirmation token is
currently required only when the run starts the VM or restores a snapshot.
The public automation interface is defined in
docs/CLI-CONTRACT.md. vmctl and labctl remain the
implementation layers; new callers should prefer sandboxctl. The MCP server
in mcp/server.mjs is a thin adapter over that same CLI.
The lower-level orchestration workflow is documented in tools/labctl.README.md.
Configuration begins with the templates in config/. The runtime copies or
overrides belong in %APPDATA%\vmctl\vmctl.config.local.json; they are never
committed.
$vmctlConfigDir = Join-Path $env:APPDATA 'vmctl'
New-Item -ItemType Directory -Path $vmctlConfigDir -Force | Out-Null
Copy-Item .\config\vmctl.config.example.json (Join-Path $vmctlConfigDir 'vmctl.config.local.json')
Copy-Item .\config\labctl.config.example.json .\tools\labctl.config.local.json
Copy-Item .\config\sandboxctl.config.example.json .\tools\sandboxctl.config.local.jsonCredentials, VMX paths, run results, screenshots, and VM files must not be placed in the repository.
vmctl does not guess snapshot names. The snapshot is selected with
-Snapshot <name> or defaultSnapshot in the local configuration. If multiple
snapshots exist and neither is set, snapshot restore fails before changing the
VM.
Configuration details and dialog-handling policies are documented in config/README.md.
The host-side scripts target Windows PowerShell 5.1 and PowerShell 7. Tests
are kept under tests/ and tools/tests/.
Implementation, testing, VMware, dialog-watcher, MCP, and packaging pitfalls are documented in docs/DEVELOPMENT-NOTES.md.
.\tools\run-tests.ps1 -IncludePssa
.\tools\build-dist.ps1The test runner performs PowerShell syntax checks, Pester contract tests, MCP
schema tests, and the guest bootstrap tests by default. PSScriptAnalyzer is
optional: -IncludePssa reports it as skipped when unavailable, while
-RequirePssa fails the run. The analyzer uses
PSScriptAnalyzerSettings.psd1, which gates correctness and portability rules
and excludes documented project-style or best-effort cleanup warnings. Use
-SkipBootstrap, -SkipMcp, or -SkipPester only for focused local runs.
The package builder reads VERSION, recursively scans package text and nested
ZIP contents for private markers, and writes the foundation package, the nested
guest bootstrap package, a manifest, and a SHA-256 sidecar under dist/.
dist/ is ignored by Git.
UIAnalysis Sandbox is licensed under the MIT License. See LICENSE and THIRD-PARTY-NOTICES.md. The third-party notices list the tools installed or referenced by the project and distinguish external installations from code bundled with this repository.