sandbox-mcp
Let AI agents test Windows apps and installers, drive their UI, and see what untrusted files do, on a fresh, throwaway Windows Sandbox machine.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/shanselman/sandbox-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/shanselman/sandbox-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/shanselman--sandbox-mcp)HTML
<a href="/listings/shanselman--sandbox-mcp"><img src="/api/listings/shanselman--sandbox-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
The clone command below retrieves the public default branch. Check out `v1.2.0` to reproduce that release's source and WinUI/WPF samples exactly. Samples are not included in the portable ZIP.
git clone https://github.com/shanselman/sandbox-mcp cd sandbox-mcp npm ci --omit=dev npm link # puts `sbx` and `sandbox-mcp` on your PATH (or use `node src/cli.js`) sbx doctor # is Windows Sandbox ready? (see above) sbx run C:\Windows\System32\charmap.exe --open # try it on something that exists everywhere
Try the included sample (needs nothing but Windows; it compiles with the .NET Framework's `csc.exe`):
.\samples\HelloSandbox\build.ps1 sbx run .\samples\HelloSandbox\bin --test .\samples\HelloSandbox\test.ps1 # passes sbx run .\samples\HelloSandbox\bin --args --crash # fails, and shows the crash sbx install-test .\samples\LeakyApp\install.ps1 # an installer whose uninstaller forgets things sbx detonate .\samples\Suspicious\suspicious.ps1 # a harmless script that acts like malware
Use it from an agent (optional MCP)
The `sbx` CLI is fully usable without an MCP server. If your agent can run shell commands, use `sbx` (or `.\sbx.cmd` from the portable ZIP) directly. Configure the MCP adapter only when the client benefits from discoverable tool schemas, structured tool results and inline screenshot images.
For source installs, use the same client-specific shapes above, replacing the bundled command with your installed Node executable. For example, VS Code (`.vscode\mcp.json`):
{
"servers": {
"windows-sandbox": {
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\sandbox-mcp\\src\\server.js"]
}
}
}Use the Copilot CLI or Claude shape above for those clients; their top-level keys differ from VS Code. An absolute Node path avoids differences between your terminal PATH and the MCP client's environment.
Then ask: *"Build the app, run it in a fresh Windows Sandbox, type my name in the box, click Greet and show me a screenshot."*
There are also agent skills in [`skills/`](skills) that teach agents each workflow: setup, clean-machine runs, interactive UI testing, installer testing and detonating untrusted files. Copy the ones you want into your agent's skills folder (for example `~/.copilot/skills/`), or install the plugin below to get them all with the optional MCP adapter.
Install the agent plugin
The [agent plugin](docs/agent-plugin.md) bundles the MCP adapter and skills, so you don't need to clone anything or edit MCP configuration. It needs Node.js 20 or later. The plugin is optional if you use the CLI directly. With GitHub Copilot CLI:
copilot plugin marketplace add shanselman/sandbox-mcp copilot plugin install sandbox-mcp@sandbox-mcp
In VS Code, add `shanselman/sandbox-mcp` as a marketplace in **Chat: Open Customizations**, or run **Chat: Install Plugin from Source**. See the [plugin guide](docs/agent-plugin.md) for details.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
plugin.json · Manifest · 14 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
- "name": "sandbox-mcp",
- "version": "1.2.0",
- "description": "Let AI agents test Windows apps and installers, drive their UI, and see what untrusted files do, on a fresh, throwaway Windows Sandbox machine.",
- "author": {
- "name": "Scott Hanselman",
- "url": "https://github.com/shanselman"
- },
- "homepage": "https://github.com/shanselman/sandbox-mcp/blob/main/docs/agent-plugin.md",
- "repository": "https://github.com/shanselman/sandbox-mcp",
- "license": "MIT",
- "keywords": ["windows-sandbox", "windows", "sandbox", "testing", "installer", "ui-automation", "mcp"]
- }
README.md · README · 820 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # sandbox-mcp
- ## Give your AI agent a brand-new Windows PC. Then throw it away.
- Not your desktop. Not a container pretending to be Windows. **A real, disposable Windows 11 machine**:
- boot it, deploy your app, drive the controls, catch the crash, keep the evidence, delete the PC.
- Run it directly with `sbx`; the optional MCP adapter exposes discoverable tools and inline images for clients that want them.
- Both interfaces use the same engine. The measured GUI samples take roughly **40-50 seconds** end to end.
- See the [website](https://shanselman.github.io/sandbox-mcp/).
- 
- *Real app, real guest: Haptics Everywhere's self-contained WPF/WinForms desktop app in a fresh, network-off Sandbox.
- UIA selects the Inspector, the guest switches light to dark, the app relaunches and exits, then the guest is destroyed.
- 10-second, 183 KB edited footage: light Inspector slowed for readability, repeated dark frames trimmed.
- Boot/teardown title cards summarize actual logs, not filmed boot/shutdown.
- No guest runtime installation or haptic-hardware claim. [Fresh dark lab screenshot](docs/haptics-teaser.png) ·
- [Earlier light-theme inspector](docs/haptics-inspector.png).*
- ### 🤖 Let your agent set it up
- Give this to your bot. It checks the PC, verifies the download and asks before admin changes or a restart.
- The CLI works on its own; configure MCP only if your agent needs that interface:
- ```text
- Set up the sandbox-mcp CLI by following:
- https://raw.githubusercontent.com/shanselman/sandbox-mcp/main/docs/agent-setup.md
- Install the latest verified release. The CLI must work without MCP; configure the optional MCP adapter only if my agent needs it. Ask before admin changes or a restart.
- ```
- **[Download v1.2.0](https://github.com/shanselman/sandbox-mcp/releases/tag/v1.2.0)**: portable CLI + optional MCP server,
- bundled Node.js, guest agent and setup instructions. No Node/npm installation needed.
- ### “Works on my machine.” Caught in 30 seconds.
- The dev box had Visual C++ installed. The fresh, **network-off** customer PC did not:
- ```text
- FAIL NativeProof.exe on a fresh Windows Sandbox (29.8s)
- why exited with code -1073741515; Missing dependency: VC++ redistributable.
- ```
- Opt in to the verified runtime install, then repeat on another fresh guest:
- ```text
- PASS NativeProof.exe on a fresh Windows Sandbox (30.9s)
- baseline PROVISIONED (not a clean-machine pass): VC++ redistributable x64
- process exited with code 0
- ```
- Those are [actual measured results](docs/compatibility.md#combined-feature-verification), not illustrative output.
- The installer was Microsoft-signed **14.51.36247.0**, downloaded and verified on the host. Guest networking stayed
- off. `sbx deps app.exe` diagnoses; `sbx run app.exe --provision auto` installs **only when explicitly requested**.
- ### What your agent gets
- | A clean customer PC | A real desktop to drive | Evidence that survives |
- |---|---|---|
- | Fresh on every boot; no implicit app-runtime installs | Native UIA: inspect, type, click, toggle, wait | PNGs, bounded recordings, self-contained HTML, optional MP4 |
- | Dependency diagnosis; explicit verified provisioning | WinUI, WPF, WinForms, Win32; MSIX/AUMID activation | Process state, exit codes, crash events, reports |
- | Network **off / firewall / on** | CLI + MCP share state; verified warm incremental deploy | Installer/uninstaller diffs; detonation observations |
- Same clean-machine loop, different frameworks:
- | WinUI 3, packaged | WPF, self-contained | Native Win32, packaged |
- |---|---|---|
- |  |  |  |
- These are real offline-guest screenshots, not host mockups. WinUI/WPF were refreshed against the final integrated
- source; the full matrix covers seven configurations. Exact builds, timings, startup defects
- found and remaining coverage gaps are in the [compatibility evidence](docs/compatibility.md).
- [Download/setup](#download-and-try-it-no-nodejs-install) · [Agent setup guide](docs/agent-setup.md) ·
- [Measured compatibility and honest limits](docs/compatibility.md) · [CLI and MCP interfaces](#one-engine-two-interfaces)
- <details>
- <summary>See a fresh, recorded UI Automation session</summary>
- 
- This 138 KB animation comes from a new 74-frame guest recording: UIA changes the text, invokes buttons and
- increments the counter. The guest was stopped afterward; the HTML viewer, MP4 and frames remained on the host.
- No synthetic screenshots. This small fixture proves the automation path; the rich app above shows the real-app use case.
- </details>
- ## Why
- **A Windows Sandbox showcase, not a framework gate.** WinUI 3 is welcome, but the entry point is a Windows
- executable or package, not a particular UI framework. Bring an app that can run in Sandbox and its prerequisites:
- Win32, WinForms, WPF, WinUI, console, PyInstaller or Electron builds use the same clean-machine workflow.
- Installers and untrusted files have their own audit/detonation workflows. This is not a promise that every
- Windows app or hardware-dependent workload works in Sandbox. See the [measured compatibility matrix](docs/compatibility.md)
- and [small source samples](samples/README.md) in this matching checkout for the configurations actually exercised.
- [winapp CLI's Sandbox execution](https://github.com/microsoft/winappCli/blob/5f379fb55517b7a47f9aad11885a7c1676dcca2e/docs/sandbox-execution.md)
- also supports packaged and unpackaged apps: its `--on sandbox` offers a warm, identity-aware developer loop,
- runtime preparation and WinUI diagnostics. sandbox-mcp emphasizes **fresh-by-default clean-machine reports**,
- network-off shared-folder mailbox transport, installer/uninstaller diffs and detonation. The tools have
- overlapping app support but different defaults and goals; sandbox-mcp never implicitly installs app prerequisites.
- Inbox Framework/CBS components can exist, but are not proof that an app's requested runtime is available.
- "It works on my machine" is usually true: your machine has every runtime, SDK, redistributable, font, registry key
- and PATH entry you ever installed. Your users' machines don't. Windows Sandbox is a pristine Windows that boots in
- seconds and is **deleted** when it closes, which makes it the perfect "brand-new customer PC". Its supported `wsb`
- CLI provides automation; sandbox-mcp adds orchestrated app deployment, UI Automation, clean-machine checks and
- durable test evidence around it.
- | | sandbox-mcp (Windows Sandbox) | Hyper-V / VMware VM | Windows containers | Cloud dev VMs (devvm, Codespaces, Dev Box) |
- |------------------------------|-------------------------------------|----------------------------|------------------------------|--------------------------------------------|
- | Real Windows desktop + GUI | ✅ | ✅ | ❌ no desktop | Linux mostly / ✅ (Dev Box) |
- | Clean state every run | ✅ always, by design | snapshots to manage | ✅ | ❌ persistent |
- | Startup | ~15 s | minutes | seconds | minutes |
- | Images to build or download | none (uses your installed Windows) | a 20+ GB VHD | multi-GB base images | none, but it's someone else's computer |
- | Cost | free with Windows Pro/Enterprise | free-ish + disk | free | 💸 |
- | Runs offline / local | ✅ | ✅ | ✅ | ❌ |
- | Parallel instances | ❌ one at a time | ✅ | ✅ | ✅ |
- | Persistent environment | ❌ | ✅ | via volumes | ✅ |
- If you need many machines, persistence, or Linux, use a VM or a cloud box. If you want to know *"does my Windows app
- install, launch and work on a clean PC, and what does it look like?"* as quickly and cheaply as possible, this is it.
- ## What you can do
- `sbx deps <app.exe|folder>` (MCP: `sandbox_deps`) inspects dependencies on the host without running or installing
- anything: PE architecture/imports, app-local VC++ DLLs, .NET runtime configs, .NET Framework configs, package
- dependencies and script interpreters. `sbx run` includes this diagnosis in its report and names likely missing
- runtimes after a failed launch. This is a conservative static scan, not proof that every dynamic dependency is
- present. Optional guest components such as WebView2 must be checked in the actual guest.
- The default never installs dependencies. To **explicitly opt in**, use `sbx run <app> --provision auto`
- (`sandbox_run` parameter `provision: "auto"`), or specify a comma-separated list such as
- `--provision desktop:10.0:x64,vcredist:x64`. Supported components: `dotnet:<version>:<arch>`,
- `desktop:<version>:<arch>`, `aspnetcore:<version>:<arch>`, `vcredist:<arch>` and
- `windows-app-runtime:<major.minor>:<arch>`. Architecture is `x86`, `x64` or `arm64` (explicit lists default
- to x64). `sbx provision <host app path> --provision <auto|list>` / `sandbox_provision` does the same in
- an already-started sandbox; it never starts or adopts a guest. Unknown versions/architectures or unsupported
- auto-provision requests fail explicitly; Java and Python require application-specific setup.
- Downloads happen on the **host**, are cached under the sandbox-mcp home `cache\redistributables` folder,
- verified with published SHA-512 hashes for .NET and a valid Microsoft Authenticode signature for every
- installer, then copied in and installed silently. Guest networking can stay **off**. A cached installer
- is reverified before reuse; remove its specific cache file to refresh a mutable VC++/Windows App Runtime
- download. Reports record the requested provisioning, completed installs, source and verification details
- and say **PROVISIONED (not a clean-machine test)**. A provisioned pass never means the original clean machine
- had those runtimes. .NET resolution conservatively stays within the requested major/minor channel and
- honors exact-version requests (`rollForward: Disable` / `applyPatches: false`) rather than silently changing
- the app configuration. A reboot-required installer result fails the run.
- Step-by-step provisioning also writes `provisioning.json` in the run folder and marks `sbx status` /
- `sandbox_status`, so switching clients does not lose the non-clean-machine provenance. This records explicit
- provisioning only, not arbitrary installers a user runs with `exec`. For a live regression, publish a small
- framework-dependent .NET desktop app and run `node test\deps-offline.js <publish folder>` with exclusive use
- of Windows Sandbox. The observed optional-component baseline for build 26100.9882 is recorded in
- `test\fixtures\sandbox-26100.9882.json`; it is evidence for that build, not a promise about future guest images.
- - **Clean-machine smoke tests:** does the exe even start without the VC++ runtime / .NET runtime / WebView2 you
- forgot to bundle? `sbx run` tells you, with a screenshot and the crash events.
- - **Test installers and uninstallers:** `sbx install-test setup.msi` installs on a clean machine, uninstalls, and
- reports every file, registry key, service, scheduled task and autorun the installer added and the uninstaller
- forgot. Hung installers waiting on a hidden dialog get screenshotted instead of hanging your CI.
- - **Drive the UI with UI Automation, not pixels:** read the control tree (`Button "Save" #SaveButton {invoke}`),
- set text, click, toggle, select, wait for results. Works for WinForms, WPF, Win32 and WinUI apps, and things like
- File Explorer. Screenshots, mouse and keyboard are there for everything else.
- - **Let an agent close the loop:** "build it, test it on a clean machine, look at the screenshot, fix it, repeat",
- without the agent touching your real desktop.
- - **Run things with no network at all:** `--network off` boots the sandbox with no network adapter. Control still
- works (through a shared folder), so you can watch an app's offline behavior or open something you don't trust.
- - **See what a file you don't trust actually does:** `sbx detonate invoice.js` runs it in a sandbox with no network
- and reports every process it started (with command lines), the names it looked up, the addresses it tried, and the
- autoruns, scheduled tasks, services and files it planted. Then the whole machine is deleted.
- - **Collect evidence:** every run keeps screenshots, copied-out files, a markdown report and an audit log on the
- host after the sandbox is gone.
- ## Download and try it (no Node.js install)
- Download the **Windows x64 portable ZIP** from the [latest GitHub release](https://github.com/shanselman/sandbox-mcp/releases/latest)
- and extract it into its own folder. The standard ZIP bundles Node.js; releases that also offer a `-bun.zip` bundle
- the runtime into `sbx.exe`. **Either runtime ZIP is all you need**; the `-bun-relink-source.zip` is only for
- rebuilding or relinking. Both include the CLI, MCP server, guest agent and skills. You do not need to clone the repo,
- install Node, npm or Bun, or add anything to PATH. Keep the extracted files together and use `sbx.cmd` directly
- for CLI-only operation; you do not need an MCP client, server configuration or plugin. The packages are built and
- tested on native Windows x64; ARM64 is not currently packaged.
- Verify the ZIP against its adjacent `.sha256` file before extracting; the [agent setup guide](docs/agent-setup.md)
- does that automatically and preserves existing client configuration.
- Open PowerShell in the extracted folder and start with the read-only readiness check:
- ```powershell
- .\sbx.cmd doctor
- ```
- `doctor` explains what is missing and how to fix it. It never enables Windows features, elevates, changes PATH, or
- restarts the PC for you. Windows Sandbox is only available on Windows Pro, Enterprise or Education; Windows Home
- and Windows Server cannot run it.
- If the Sandbox feature is off, open **an administrator PowerShell**, run the command below, then restart Windows:
- ```powershell
- Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
- ```
- After restarting, open **Windows Sandbox from the Start menu once**, then close it. This updates Sandbox and installs
- the `wsb` command-line tool that `sbx` uses. Run the check again and try a built-in Windows app:
- ```powershell
- .\sbx.cmd doctor
- .\sbx.cmd run C:\Windows\System32\charmap.exe --open
- ```
- A passing run leaves `report.md`, `report.json`, screenshots and `audit.jsonl` under
- `%LOCALAPPDATA%\sandbox-mcp\runs\<timestamp>` (`out` contains the report and media), even after teardown.
- `--open` opens the report. Add `--record` for a self-contained viewer under
- `out\recordings\<recordingId>\recording.html` and MP4 when host ffmpeg is available. `SANDBOX_MCP_HOME`
- changes the artifact root. No ffmpeg or app runtime is silently installed.
- For an MCP client using the standard ZIP, configure its stdio server with the full paths to the bundled runtime and
- server. Replace the example folder with the location where you extracted the ZIP:
- ```json
- {
- "servers": {
- "windows-sandbox": {
- "type": "stdio",
- "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
- "args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"]
- }
- }
- }
- ```
- That is the VS Code `.vscode\mcp.json` shape. For GitHub Copilot CLI's
- `%USERPROFILE%\.copilot\mcp-config.json`, use:
- ```json
- {
- "mcpServers": {
- "windows-sandbox": {
- "type": "local",
- "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
- "args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"],
- "tools": ["*"]
- }
- }
- }
- ```
- For the Bun ZIP, replace the `command` and `args` in either example with:
- ```json
- {
- "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\sbx.exe",
- "args": ["mcp"]
- }
- ```
- For Claude Desktop, use `"mcpServers"` with the same command/args and omit `type` and `tools`.
- Restart or reload the client's server configuration, then ask it to run Character Map in a fresh offline Sandbox
- and return the report and screenshot. The server writes logs to stderr; stdout is reserved for MCP messages.
- ## Turn on Windows Sandbox
- If you have Windows Pro, Enterprise or Education, you already own one of the best tools in Windows and it's probably
- switched off. [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview)
- is a whole, real Windows desktop that:
- - **comes with Windows:** nothing to download, no VHD, no license key. It's built from the Windows you're running.
- - **is brand new every time:** it boots as clean as the day Windows was installed, in about 15 seconds.
- - **is thrown away when you close it:** guest files, registry keys and installed apps are deleted.
- Explicitly shared output folders remain on the host as test evidence.
- - **is properly isolated:** it runs on its own kernel behind the Microsoft hypervisor (the same hardware
- virtualization as Hyper-V), not just a separate user account.
- - **is light:** it shares memory and files with your PC where it safely can, and uses your GPU.
- Turn it on with one line in an **admin** PowerShell, then restart:
- ```powershell
- Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
- ```
- (Or *Turn Windows features on or off* > tick *Windows Sandbox*.) After the restart, **open Windows Sandbox from the
- Start menu once**. That updates it to the Store version, which includes the `wsb` command-line tool this project
- drives. Then check everything with:
- ```powershell
- sbx doctor
- ```
- ```text
- ✅ Windows 11 Pro, build 26100
- ✅ Windows Sandbox feature is on
- ✅ Virtualization is on
- ✅ wsb command-line tool: C:\Users\you\AppData\Local\Microsoft\WindowsApps\wsb.exe (Windows Sandbox 0.8.107.0)
- ✅ Node.js 22.11.0
- Ready. Try: sbx run C:\Windows\System32\charmap.exe --open
- ```
- If something's missing, `sbx doctor` says what and how to fix it, and every other command tells you the same thing
- if it can't reach Windows Sandbox. The full list of what you need:
- - Windows 11 24H2 (build 26100) or later, Pro / Enterprise / Education. Windows Sandbox isn't available on Home or Windows Server.
- - Virtualization turned on in your PC's UEFI/BIOS (Intel VT-x or AMD-V). Most PCs ship with it on.
- - At least 4 GB of RAM (8 GB recommended), 2 CPU cores and 1 GB of free disk.
- - Running inside a VM? Turn on nested virtualization on the host first:
- `Set-VMProcessor -VMName <name> -ExposeVirtualizationExtensions $true`.
- - Either portable ZIP includes its runtime for Windows x64. If installing from source, use Node.js 20+ (`winget install OpenJS.NodeJS.LTS`).
- ## Install from source
- The clone command below retrieves the public default branch. Check out `v1.2.0` to reproduce that release's
- source and WinUI/WPF samples exactly. Samples are not included in the portable ZIP.
- ```powershell
- git clone https://github.com/shanselman/sandbox-mcp
- cd sandbox-mcp
- npm ci --omit=dev
- npm link # puts `sbx` and `sandbox-mcp` on your PATH (or use `node src/cli.js`)
- sbx doctor # is Windows Sandbox ready? (see above)
- sbx run C:\Windows\System32\charmap.exe --open # try it on something that exists everywhere
- ```
- Try the included sample (needs nothing but Windows; it compiles with the .NET Framework's `csc.exe`):
- ```powershell
- .\samples\HelloSandbox\build.ps1
- sbx run .\samples\HelloSandbox\bin --test .\samples\HelloSandbox\test.ps1 # passes
- sbx run .\samples\HelloSandbox\bin --args --crash # fails, and shows the crash
- sbx install-test .\samples\LeakyApp\install.ps1 # an installer whose uninstaller forgets things
- sbx detonate .\samples\Suspicious\suspicious.ps1 # a harmless script that acts like malware
- ```
- ### Use it from an agent (optional MCP)
- The `sbx` CLI is fully usable without an MCP server. If your agent can run shell commands, use `sbx` (or
- `.\sbx.cmd` from the portable ZIP) directly. Configure the MCP adapter only when the client benefits from
- discoverable tool schemas, structured tool results and inline screenshot images.
- For source installs, use the same client-specific shapes above, replacing the bundled command with your
- installed Node executable. For example, VS Code (`.vscode\mcp.json`):
- ```json
- {
- "servers": {
- "windows-sandbox": {
- "type": "stdio",
- "command": "node",
- "args": ["C:\\path\\to\\sandbox-mcp\\src\\server.js"]
- }
- }
- }
- ```
- Use the Copilot CLI or Claude shape above for those clients; their top-level keys differ from VS Code.
- An absolute Node path avoids differences between your terminal PATH and the MCP client's environment.
- Then ask: *"Build the app, run it in a fresh Windows Sandbox, type my name in the box, click Greet and show me a
- screenshot."*
- There are also agent skills in [`skills/`](skills) that teach agents each workflow: setup, clean-machine runs,
- interactive UI testing, installer testing and detonating untrusted files. Copy the ones you want into your agent's
- skills folder (for example `~/.copilot/skills/`), or install the plugin below to get them all with the optional MCP adapter.
- ### Install the agent plugin
- The [agent plugin](docs/agent-plugin.md) bundles the MCP adapter and skills, so you don't need to clone anything
- or edit MCP configuration. It needs Node.js 20 or later. The plugin is optional if you use the CLI directly.
- With GitHub Copilot CLI:
- ```powershell
- copilot plugin marketplace add shanselman/sandbox-mcp
- copilot plugin install sandbox-mcp@sandbox-mcp
- ```
- In VS Code, add `shanselman/sandbox-mcp` as a marketplace in **Chat: Open Customizations**, or run
- **Chat: Install Plugin from Source**. See the [plugin guide](docs/agent-plugin.md) for details.
- ## Fast inner loop
- Start once, then build and deploy repeatedly into that **warm** sandbox (any framework, no guest prerequisites
- installed implicitly):
- ```powershell
- sbx start --network off
- powershell -File .\samples\HelloSandbox\build.ps1
- sbx deploy .\samples\HelloSandbox\bin C:\apps\HelloSandbox --launch HelloSandbox.exe --restart
- sbx shot --window "Hello Sandbox"
- # Edit, build, deploy --restart, screenshot again; when done:
- sbx stop
- ```
- `deploy` transfers only added/changed files through a fresh shared staging folder, removes deleted files, and verifies
- the entire destination using SHA256. Its report includes added/changed/removed/unchanged counts, bytes transferred,
- elapsed milliseconds and `verified: true`. `--restart` stops processes whose executable is under the destination before
- applying and requires `--launch` to relaunch the app; `--launch` alone launches after verification. Arguments use
- `--args "..."`. TCP and network-off shared-folder transport both work.
- Use a dedicated destination: **extra guest files there are deleted**. Links, junctions and reparse points are rejected.
- If a build changes while staging, deployment fails with `build output changed during deploy; rerun` before touching the
- destination. Apply/verification failures restore the previous touched files where possible; rollback failures explicitly
- identify the retained guest backup. Stopped processes are not automatically restarted after a failed apply.
- `push` / `sandbox_copy_in` still perform a full replacement. `run`, `install-test` and `detonate` still start fresh;
- incremental deployment never adopts an unrelated sandbox.
- ## One engine, two interfaces
- The `sbx` CLI and MCP server are two interfaces to the same implementation: both import and use `src/core.js`,
- and the higher-level run, installer and detonation workflows are shared too. The CLI is the complete standalone
- interface; MCP is an optional adapter for agents that benefit from discoverable tool schemas, structured results
- and inline screenshot images. They are not separate engines, and their names or output formats are not meant to
- be identical.
- For example, both forms run Character Map on a fresh offline guest, capture evidence and destroy the guest:
- ```powershell
- sbx run C:\Windows\System32\charmap.exe --network off
- ```
- Or call MCP tool `sandbox_run` with these arguments:
- ```json
- {
- "app": "C:\\Windows\\System32\\charmap.exe",
- "network": "off"
- }
- ```
- The supported workflows map across the interfaces:
- | Workflow | CLI | MCP adapter |
- |---|---|---|
- | Fresh app test | `sbx run` | `sandbox_run` |
- | Guest lifecycle and shared state | `sbx start`, `status`, `stop`, `desktop-release` | `sandbox_start`, `sandbox_status`, `sandbox_stop`, `sandbox_desktop_release` |
- | Commands, processes and files | `sbx exec`, `launch`, `proc`, `push`, `pull`, `deploy`, `errors` | `sandbox_exec`, `sandbox_launch`, `sandbox_process`, `sandbox_copy_in`, `sandbox_copy_out`, `sandbox_deploy`, `sandbox_app_errors` |
- | UI automation and capture | `sbx ui`, `ui wait`, `shot`, `windows`, `click`, `type` | `sandbox_ui_tree`, `sandbox_ui_action`, `sandbox_ui_wait`, `sandbox_screenshot`, `sandbox_windows`, `sandbox_click`, `sandbox_type` |
- | Recording | `sbx record start`, `record stop` | `sandbox_record_start`, `sandbox_record_stop` |
- | Dependencies and provisioning | `sbx deps`, `provision` | `sandbox_deps`, `sandbox_provision` |
- | Installer and untrusted-file tests | `sbx install-test`, `detonate` | `sandbox_install_test`, `sandbox_detonate` |
- | System snapshots | `sbx snapshot`, `diff` | `sandbox_snapshot`, `sandbox_diff` |
- Use the CLI's human-readable output and process exit codes in a shell; add `--json` for machine-readable output.
- The MCP adapter presents schemas and structured results to compatible clients and can return screenshots inline.
- ## MCP tools
- | Tool | What it does |
- |---|---|
- | `sandbox_deps` | Host-only conservative dependency diagnosis; does not execute or install the app. |
- | `sandbox_provision` | Explicit opt-in verified runtime installation into the current owned guest; persists non-clean provenance. |
- | `sandbox_run` | The whole loop in one call: boot, copy/install, launch or run, observe, test script, collect, destroy, report. |
- | `sandbox_start` | Boot a fresh sandbox (`network`: on / firewall / off, `memoryMB`, `vGpu`). Waits for the agent and an interactive desktop; reports readiness timings. |
- | `sandbox_status` | Is one running, its id/IP/network mode, agent health and current interactive-desktop facts. |
- | `sandbox_desktop_release` | End this workflow's desktop turn immediately. |
- | `sandbox_stop` | Destroy it. Lists the artifacts left on the host. |
- | `sandbox_copy_in` | Copy a host file or folder in (default `C:\apps\<name>`). |
- | `sandbox_deploy` | Deploy a host directory into an already running sandbox, transfer only changes and verify hashes; optional launch/restart. |
- | `sandbox_copy_out` | Copy a sandbox file or folder out to the run's `out\files`. |
- | `sandbox_exec` | Run a PowerShell (or `cmd`) command; returns stdout, stderr, exit code. |
- | `sandbox_launch` | Start an EXE or installed package AUMID; returns the app pid and main window. |
- | `sandbox_process` | Running? Exit code? Window title? |
- | `sandbox_windows` | Visible top-level windows with titles, pids and bounds. |
- | `sandbox_screenshot` | PNG of the desktop or one window, returned inline (and saved on the host), with its own `captureId`, bounds and scale. |
- | `sandbox_record_start` / `sandbox_record_stop` | Bounded desktop recording: frames stream straight to the host share; stop publishes a self-contained HTML flipbook and MP4 if host ffmpeg is available. |
- | `sandbox_click` / `sandbox_type` | Mouse and keyboard, in screenshot coordinates / SendKeys syntax. Click accepts `captureId` (default latest); out-of-image points and moved/resized captured windows are rejected. |
- | `sandbox_ui_tree` | The UI Automation tree of a window: type, name, automation id, value, state, supported actions. |
- | `sandbox_ui_action` | Find a control by name / automation id / type and click, set a value, toggle, select, expand, read... |
- | `sandbox_ui_wait` | Wait for a control (a result, a dialog) to appear. |
- | `sandbox_app_errors` | Application event log errors: crashes, hangs, .NET unhandled exceptions. |
- | `sandbox_install_test` | The installer loop in one call: snapshot, install, snapshot, optional test, uninstall, snapshot, report what was added and left behind. |
- | `sandbox_detonate` | Run an untrusted file (no network by default) and report its processes, lookups, connections, persistence and changes. |
- | `sandbox_snapshot` | Record files, registry, services, autoruns and installed programs under a name. |
- | `sandbox_diff` | Compare two snapshots: what changed in between. |
- ## CLI
- ```text
- sbx run <app.exe|folder|app.msix> [--exe <name>] [--args "<args>"] [--console] [--wait <sec>]
- [--cert <file.cer>] [--deps <folder>] [--app-id <id>]
- [--record] [--provision <auto|list>]
- [--test <script.ps1>] [--collect <sandbox path>]... [--keep] [--open]
- sbx install-test <setup.msi|.exe|.ps1|.cmd> [--args "/S"] [--uninstall auto|none|"<cmd>"]
- [--uninstall-args "/S"] [--test <script.ps1>] [--fail-on-leftovers] [--exclude <path>]...
- sbx detonate <file> [--args "<args>"] [--network off|firewall|on] [--duration <sec>] [--full] [--every <sec>]
- sbx start [--network on|firewall|off] [--memory <MB>] [--no-gpu] [--minimized]
- sbx deps <host app path> sbx provision <host app path> --provision <auto|list>
- sbx desktop-release
- sbx push <host path> [sandbox path] sbx pull <sandbox path> [name]
- sbx deploy <hostDir> [guestDir] [--launch <exe>] [--args "..."] [--restart]
- sbx exec [--cmd] [--cwd <dir>] <command...> sbx launch <exe|PackageFamilyName!AppId> [--args "..."]
- sbx shot [--window <title>|--pid <pid>] sbx windows sbx proc <pid>
- sbx record start [--fps 2 --duration 120] sbx record stop
- sbx ui [tree] [--pid <pid>] sbx ui click --name Save
- sbx ui set --id NameBox --value Scott sbx ui wait --name "Saved" --timeout 10
- sbx snapshot <name> [--exclude <path>]... sbx diff <from> <to>
- sbx click <x> <y> sbx type "text" [--keys] sbx errors sbx status sbx stop
- sbx doctor # can this PC run Windows Sandbox? how to fix it if not
- sbx mcp # run the MCP server
- ```
- `exec` treats the command and everything after it as raw guest input. Put CLI options first:
- `sbx exec --json --timeout 30 'Get-Date'`, not `sbx exec 'Get-Date' --json`.
- Add `--json` to any command for machine-readable output. `sbx exec` and `sbx run` exit with meaningful codes, so they
- drop straight into scripts. `sbx help` has the details.
- CLI and MCP processes share locked, atomically written state, including copy and mailbox sequence numbers.
- Desktop-changing operations (launch, click, type, UI actions and window-focusing screenshots) take cooperative
- FIFO turns; observing windows, UI trees, processes, status and executing commands does not reserve the desktop.
- An MCP instance retains its turn for four idle seconds. Set `SANDBOX_MCP_WORKFLOW` to the same identifier across
- CLI commands to retain a multi-command turn too; anonymous CLI commands release immediately. End a turn with
- `sbx desktop-release` or `sandbox_desktop_release`. A contender waits at most 60 seconds, then reports
- `desktop busy: held by <owner>`. These are cooperative turns, not isolation: `exec` can itself start GUI programs.
- Each boot has an epoch and a verified agent identity (protocol version, agent version and SHA256 of staged
- agent files), included in `status --json`. A stale boot or incompatible protocol is refused: start a new sandbox.
- Both TCP and offline mailbox messages use directional HKDF-SHA256 keys, AES-256-CBC encryption and
- HMAC-SHA256 authentication with counters, random IVs and timestamp/replay checks. The random transport key
- stays in the read-only agent share, never in `current.json`, command-line arguments or request/response messages.
- This protects the transport, not against an administrator inside the guest: code there can read its agent share.
- ## Packaged apps (MSIX and Appx)
- `sbx run` also accepts `.msix`, `.msixbundle`, `.appx` and `.appxbundle`. It copies the package into a
- **fresh** guest, installs it with `Add-AppxPackage`, resolves its manifest Application Id, and activates the
- installed AUMID. Screenshots, UI Automation, crash checks, test scripts and reports use the actual app process,
- not the short-lived shell launcher.
- ```powershell
- sbx run .\build\MyApp.msix --cert .\build\devcert.cer --network off --test .\smoke.ps1
- sbx run .\build\MyApp.msixbundle --deps .\build\Dependencies\x64 --app-id App --network off
- # Inside an already-running sbx session, activate an installed package:
- sbx launch 'MyApp_0123456789abc!App'
- ```
- `--cert` explicitly trusts a public `.cer` in **the guest's** `LocalMachine\TrustedPeople` store; it never
- installs a certificate on the host. Store-signed/trusted packages do not need it. Provide offline framework
- packages in an adjacent `deps` folder, or choose another folder with `--deps`; every package in that folder is
- passed as a `DependencyPath`. Nothing is downloaded or preinstalled automatically. Select `--app-id` when
- a manifest contains more than one application. Deployment failures include Windows' error and activity log
- when available. Package activation is GUI mode, not `--console`.
- The equivalent `sandbox_run` inputs are `app`, `cert`, `deps` and `appId`. `sandbox_launch` accepts `aumid`
- instead of `path`, and the CLI also recognizes `shell:AppsFolder\PackageFamilyName!ApplicationId`.
- Tests receive `$env:SBX_APP_AUMID` as well as the usual process/executable paths. Installed package directories
- are read-only: write test output to `$env:SBX_OUT` or an app-data directory, not `$env:SBX_APP_DIR`.
- ## Recording and capture coordinates
- For visual evidence across an entire session, use `sbx run <app> --record` (MCP: `sandbox_run` with
- `record: true`), or `sbx record start` / `sbx record stop` for interactive work. Recording runs in a separate
- guest process, including while a long command is running. Defaults: 2 fps, 120 seconds; hard limits:
- 5 fps, 300 seconds, 600 frames. `--max-frames` sets a smaller frame budget. Frames (up to 1280 pixels wide)
- and append-only `frames.jsonl` metadata go directly to `out\recordings\<id>`; partial evidence survives
- a guest crash or timeout. Stop publishes `recording.html` with embedded images and playback controls,
- plus `recording.mp4` when ffmpeg is already on the host PATH. No guest installation or network is needed.
- MP4 uses the requested frame rate; the HTML player preserves captured timestamps. Neither format includes audio.
- The run report links the artifacts. `sbx stop` also publishes any tracked recording before destroying the guest.
- Only one recording can be reserved across CLI/MCP clients. Tracking is bound to the boot epoch and recording ID;
- failed publication retains recovery metadata so `sbx record stop` can retry without touching a replacement guest.
- Rejected starts release a zero-frame reservation only after confirming that its recorder cannot still be active;
- uncertain starts retain tracking and report the error explicitly.
- Guest-returned screenshot filenames are checked as confined PNG leaf paths before host reads or cleanup.
- After a guest crash or abrupt MCP disconnect, `sbx record stop` can still publish the preserved partial evidence,
- even if `sbx status` already noticed the guest is gone. Truncated final recorder status is reported as partial,
- not allowed to hide otherwise valid frames; malformed frame metadata is still rejected.
- Start verifies the Default input desktop, explorer shell, screen size and a successful capture before declaring
- ready. Screenshot, click, type and UI actions reject locked/secure desktops (including UAC) explicitly.
- Screenshot coordinates are pixels in the returned preview, not the full-resolution saved PNG.
- MCP clicks default to the latest screenshot; use `captureId` to select an earlier image. CLI clicks still default
- to raw screen pixels: use `--coordinates screenshot --capture-id <id>` for a preview. Captured windows that
- move, resize, minimize or close must be captured again before clicking.
- ## Test scripts
- `sbx run --test smoke.ps1` (or `sandbox_run` with `test`) runs your script **inside** the sandbox after the app
- starts, with:
- - `$env:SBX_APP_PID`, `$env:SBX_APP_DIR`, `$env:SBX_OUT` (anything you write to `SBX_OUT` comes back to the host),
- - these commands already imported:
- ```powershell
- Get-SbxUiTree [-ProcessId <pid>] [-WindowTitle <title>] [-Depth <n>] # objects: type, name, automationId, value, actions...
- Invoke-SbxUi -Action <click|setvalue|toggle|select|expand|read|...> [-Name <text>] [-AutomationId <id>]
- [-ControlType <Button|Edit|...>] [-Index <n>] [-Value <text>] [-ProcessId <pid>]
- Wait-SbxUi [-Name <text>] [-AutomationId <id>] [-ControlType <type>] [-TimeoutSec <n>] [-ProcessId <pid>]
- ```
- Throw, or exit non-zero, to fail the run. Example ([samples/HelloSandbox/test.ps1](samples/HelloSandbox/test.ps1)):
- ```powershell
- $app = [int]$env:SBX_APP_PID
- Invoke-SbxUi -ProcessId $app -AutomationId NameBox -Action setvalue -Value 'Sandbox'
- Invoke-SbxUi -ProcessId $app -Name Greet -Action click
- Wait-SbxUi -ProcessId $app -Name 'Hello, Sandbox!' -TimeoutSec 5 | Out-Null
- ```
- ## Installer testing
- Installers are the part of an app that only ever runs on clean machines, so they're the part you test least.
- `sbx install-test` takes a system snapshot of a fresh sandbox, runs your installer silently, snapshots again,
- uninstalls it the way Add/Remove Programs would, snapshots a third time and diffs them:
- ```text
- > sbx install-test .\7z2501-x64.msi --offline
- PASS 7z2501-x64.msi on a fresh Windows Sandbox (117.5s)
- install exit 0 in 2.5s
- added 7-Zip 25.01 (x64 edition); 111 files, 18 registry keys, 0 services, 0 autorun/env values
- uninstall 7-Zip 25.01 (x64 edition): exit 0 in 2.3s
- leftovers none, clean uninstall
- ```
- The report lists what was added (here: `C:\Program Files\7-Zip`, the Start menu folder, the shell extension
- CLSIDs and context-menu handlers, App Paths and the uninstall entry) and what's **left behind**. Try the included
- deliberately sloppy installer, whose uninstaller only deletes its program folder:
- ```text
- > sbx install-test .\samples\LeakyApp\install.ps1
- ## Left behind after uninstall
- Services: added service LeakyUpdater "Leaky App Updater", automatic: "C:\Program Files\LeakyApp\updater.exe"
- Autoruns: added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\LeakyUpdater
- Files: C:\ProgramData\LeakyApp\ C:\Users\WDAGUtilityAccount\AppData\Roaming\LeakyApp\
- C:\Windows\System32\Tasks\LeakyApp Daily Check
- Registry: HKLM\SOFTWARE\LeakyApp
- ```
- - `.msi` files get `msiexec /i /qn /norestart` with a verbose log (brought back, with its errors in the report).
- For `.exe` installers pass the silent switch: `--args /S` (NSIS), `/VERYSILENT` (Inno), `--silent` (Squirrel).
- - The uninstall uses what the installer registered: `msiexec /x {ProductCode}`, else `QuietUninstallString`, else
- `UninstallString` plus `--uninstall-args`. The run fails if the program is still in Add/Remove Programs afterwards.
- - An installer that doesn't exit within `--timeout` is screenshotted (and its new windows' UI Automation tree
- recorded) before it's killed. That's usually a "silent" install that's waiting for someone to click a dialog.
- - Processes the installer leaves running (tray apps, updaters) are listed and stopped before uninstalling.
- - `--test smoke.ps1` runs between install and uninstall with `$env:SBX_INSTALL_DIR` and `$env:SBX_PROGRAM`.
- - `--fail-on-leftovers` turns leftovers into a failure, for CI.
- - The snapshots skip the things Windows changes on its own (caches, telemetry, Defender, Windows Update, Start menu
- and Explorer bookkeeping, Windows Installer's internal database), so a 30-second idle sandbox diffs to "No changes".
- `--exclude` adds more.
- The same snapshots are available step by step: `sbx snapshot before`, do anything, `sbx snapshot after`,
- `sbx diff before after` (or the `sandbox_snapshot` / `sandbox_diff` tools).
- ## Detonate: what does this file actually do?
- Someone sent you `invoice.js`, a "driver update", a script from a forum. `sbx detonate` runs it the way a
- double-click would, in a fresh sandbox with **no network adapter**, with Windows' own auditing switched on, and
- tells you what it did:
- ```text
- > sbx detonate .\samples\Suspicious\suspicious.ps1 --network firewall
- suspicious.ps1: 3 red flag(s) (watched 40s, network firewall)
- findings 🔴 starts itself with Windows: added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ContosoUpdater =
- powershell.exe -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\Users\...\ContosoUpdater\updater.ps1"
- 🔴 created a scheduled task: ContosoUpdate
- 🔴 put something in a Startup folder: C:\Users\...\Start Menu\Programs\Startup\contoso.cmd
- 🟠 wrote 2 runnable file(s): C:\Users\...\ContosoUpdater\updater.ps1, ...\Startup\contoso.cmd
- 🟠 ran built-in Windows tools that malware often uses: schtasks.exe, whoami.exe, ipconfig.exe, net.exe, net1.exe
- 🟠 looked up 1 internet name(s): c2.contoso-updates.example
- 🟠 tried to connect to 2 address(es): 198.51.100.7:4444, 203.0.113.10:80
- processes 7 (powershell.exe → conhost.exe → schtasks.exe → whoami.exe → ipconfig.exe …)
- network 1 name lookup(s), 2 connection attempt(s)
- changed 4 files added, 0 changed, 2 registry keys, 1 autorun/env values, 0 services
- ```
- ([samples/Suspicious/suspicious.ps1](samples/Suspicious/suspicious.ps1) is harmless; it just behaves like
- something that isn't.) The report also has a timeline:
- ```text
- +0.0s start powershell.exe (pid 8180) ... -File "C:\Users\WDAGUtilityAccount\Downloads\suspicious.ps1"
- +1.5s start schtasks.exe (pid 7848) /Create /F /TN ContosoUpdate /SC ONLOGON /TR "powershell.exe -WindowStyle Hidden ..."
- +1.6s start whoami.exe (pid 7616) /all
- +1.7s start net.exe (pid 9064) user
- +1.7s start net1.exe (pid 8096) C:\Windows\system32\net1 user
- +15.0s lookup c2.contoso-updates.example (failed)
- +15.1s connect 203.0.113.10:80/TCP blocked (powershell.exe)
- +15.2s connect 198.51.100.7:4444/TCP blocked (powershell.exe)
- ```
- plus the process tree, a before/after diff of files, registry, services and autoruns, the windows it opened,
- screenshots, and "everything else that happened" (usually Windows itself, kept separate rather than hidden).
- - **How:** process creation auditing with command lines (Security 4688), Windows Filtering Platform connection
- auditing (5156/5157) and the DNS client log, collected from inside the guest, plus the same snapshots as
- `install-test`. Activity is attributed to the file's own process tree, so the agent's own work isn't mixed in.
- - **Network:** `off` (default) has no adapter at all. Name lookups are still recorded, but nothing leaves the
- machine. `--network firewall` also shows the IP addresses and ports it tries, blocked by the guest firewall.
- `on` gives it the internet; only use that for things you're prepared to let talk to the world.
- - **Runs:** `.exe`, `.msi` (silently), `.ps1`, `.cmd`, `.bat`, `.js`/`.jse`/`.vbs`/`.vbe`/`.wsf` (with `wscript`) and
- `.hta` (with `mshta`), from the user's Downloads folder.
- - **Watching:** up to `--duration` seconds (60), stopping early once everything it started has exited, unless
- `--full`. A screenshot every `--every` seconds (15).
- - **Collection health:** if process/connection audit setup or DNS log setup fails, the file is not launched.
- If an event log cannot be read, the run reports a collection error rather than treating it as no activity.
- A successful query with no matching events still produces an empty activity list.
- - **Findings are heuristics, not a verdict.** Installers add autoruns and services too. Exit code 0 means "it was
- observed", not "it's safe". This is a quick first look on your own PC, not a malware lab: something that checks
- whether it's in a sandbox can just behave nicely.
- ## Network modes
- | Mode | How | Use it for |
- |---|---|---|
- | `on` (default) | Normal NAT networking. | Apps that need the internet, downloading prerequisites. |
- | `firewall` | Guest firewall blocks all outbound traffic (DNS included); only the control channel from the host is allowed. | Testing offline behavior quickly. Admin code in the guest *could* undo it. |
- | `off` | The sandbox has **no network adapter**. sandbox-mcp talks to it through a shared-folder mailbox (~100 ms per call). | Untrusted files (the default for `detonate`), and proving an app works with no network at all. |
- In `firewall` and `off` mode, sandbox-mcp also switches off Smart App Control in the guest. It ships in evaluation
- mode and asks the cloud about every new exe and msi; with no internet each of those lookups hangs for about two
- minutes (a 2 MB MSI took 125 s to install instead of 1 s).
- ## Security notes
- - Each sandbox is a separate Hyper-V-isolated kernel. It's thrown away on stop, together with everything that ran in it.
- - Hardened defaults: clipboard, printer, microphone and camera redirection are off, and *Protected Client* mode is on.
- - The host shares exactly three folders: the guest agent (read-only), a staging folder for files you copy in
- (read-only) and an output folder (read-write). Nothing else from your disk is visible.
- - The control channel needs a random per-sandbox token. In `on`/`firewall` mode it's TCP to the sandbox's private
- NAT address; in `off` mode it's the shared folder.
- - `SANDBOX_MCP_ALLOWED_ROOTS` limits which host folders can be copied in (handy when an agent is driving).
- - Every operation is appended to `audit.jsonl` in the run folder.
- - When the MCP client disconnects, only the boot it started is destroyed, unless `SANDBOX_MCP_KEEP_ON_EXIT=1`.
- A client joining a CLI-started guest does not own it. An idle watchdog shuts the guest down after 30 minutes
- with no calls.
- - With `network: on` the guest has internet access like any other machine on your network's NAT. Use `off` for
- anything you don't trust.
- - The `out` folder is writable from inside the sandbox, so treat what comes back (screenshots, pulled files, logs)
- as untrusted, especially after `detonate`. sandbox-mcp reads data from it but never runs anything from it.
- - Windows Sandbox is strong isolation, but not a guarantee: a hypervisor or Windows Sandbox escape would be a
- zero-day. For real malware analysis use a dedicated, disposable analysis machine.
- ## Configuration
- | Environment variable | Default | |
- |---|---|---|
- | `SANDBOX_MCP_HOME` | `%LOCALAPPDATA%\sandbox-mcp` | Where runs, screenshots and reports are kept. |
- | `SANDBOX_MCP_ALLOWED_ROOTS` | (any) | `;`-separated host folders that may be copied into the sandbox. |
- | `SANDBOX_MCP_IDLE_MINUTES` | `30` | Guest shuts itself down after this long with no calls. `0` disables. |
- | `SANDBOX_MCP_KEEP_ON_EXIT` | (unset) | Set to `1` to leave the sandbox running when the MCP client disconnects. |
- ## How it works
- Since Windows 11 24H2 the Store version of Windows Sandbox ships the supported `wsb.exe` CLI
- (`start / stop / list / ip / exec / share / connect`), but `wsb exec` returns only an exit code: no output, no
- screenshots, no UI. So:
- 1. The host creates a run folder and calls `wsb start` with a hardened config (and `<Networking>Disable` in `off` mode).
- 2. It shares the guest agent folder and starts [`agent/agent.ps1`](agent/agent.ps1) inside with `wsb exec`, in the
- interactive user session (it needs a desktop for windows and screenshots).
- 3. The agent is a small PowerShell server: exec with real output, file copy, process launch, screenshots, mouse and
- keyboard, window list, event log, and UI Automation through [`agent/uia.cs`](agent/uia.cs). That uses *native* UI
- Automation (the managed `System.Windows.Automation` can't see inside WinForms apps), with an interop assembly
- generated on the fly from the OS type library, so nothing needs installing.
- 4. With the network on, the host talks to it over TCP. In `off` mode it uses a mailbox in the shared folders.
- (The guest caches "file not found" for ~5 s, so the host bumps a sequence file the guest polls, bringing a round
- trip from 5 s down to ~100 ms.)
- 5. `wsb stop` destroys the VM. The run folder stays on the host.
- ## Limits
- - **One sandbox at a time.** That's a Windows Sandbox rule. `sbx run` calls queue nothing; they fail fast if one is running.
- - Every boot is pristine. Bundle app-local prerequisites or explicitly opt in to provisioning for each fresh guest;
- automatic runtime installation is never the default.
- - No Microsoft Store apps, winget, Notepad, Calculator or Windows Terminal inside. Windows PowerShell 5.1 and
- .NET Framework 4.8 are there.
- - The first UI Automation call in a sandbox takes ~4 s (it generates the interop); later calls are fast.
- - A system snapshot takes 10-20 s (about 11k files, 340k registry keys, 700 services), so `install-test` takes
- roughly two minutes plus your installer's own time.
- - The guest desktop gets a plain background so screenshots stay around 100 KB instead of 16 MB.
- - Needs a logged-in Windows session on the host (Windows Sandbox is a desktop feature).
- ## Verifying changes locally
- `npm test` checks the host logic and parses/compiles the guest PowerShell and C# helpers without booting a guest.
- Real desktop verification requires this Windows host's single Sandbox slot; coordinate with other users first
- and never stop somebody else's guest.
- ```powershell
- $env:SANDBOX_MCP_HOME = Join-Path $PWD 'work\integration'
- node test\integration.js off
- node test\integration.js on
- node test\integration.js firewall
- node test\evidence.js
- npm run package:win
- node test\package-smoke.js dist\sandbox-mcp-win-x64-v1.2.0.zip
- ```
- The integration harness drives the actual MCP stdio server and CLI against the same fresh guest, verifies UIA,
- copies evidence back, and fails if its guest cannot be torn down. JSON results are saved beneath
- `$env:SANDBOX_MCP_HOME\integration`. The package smoke test extracts the ZIP, removes host Node from PATH, checks
- CLI/MCP initialization and command surfaces, and compares every shipped source, agent and skill file with the
- working tree. It does not boot a Sandbox and is not a substitute for the live tests.
- `node test\agent-setup.js --download` follows the stable-download checksum/doctor instructions in a temporary
- home, tests all three JSON client destinations on PowerShell 5.1/7, checks native `copilot mcp add` with isolated
- `COPILOT_HOME`, and requires an actual MCP `sandbox_status` response. It needs the installed Copilot CLI for
- the native-command check. Use `--portable=<extracted-path>` for an already downloaded package, or `--candidate`
- to exercise the explicitly optional developer-preview discovery instructions.
- For a live extracted-package check, run the integration harness with the extracted `node.exe` and set
- `SANDBOX_MCP_TEST_ROOT` to the extracted folder. `SANDBOX_MCP_TEST_SHA` records the source commit when Git is not on
- the isolated PATH. Set `SANDBOX_MCP_EXPECT_NO_HOST_NODE=1` to require both the bundled runtime and no `node` on PATH;
- keep Windows system directories and the WindowsApps `wsb.exe` alias on PATH.
- ## Related projects
- - [fmuecke/windows-sandbox-mcp](https://github.com/fmuecke/windows-sandbox-mcp) is another MCP server for Windows
- Sandbox, focused on running agent-generated code safely and with `Networking Disable` by default. Its ideas
- (true offline by default, stop on disconnect, an idle watchdog, an audit log, allowed folders) shaped this
- project. sandbox-mcp leans the other way: testing *your* app on a clean machine, with UI Automation, screenshots
- and one-shot reports.
- - [devvm.dev](https://devvm.dev/): disposable cloud dev machines for agents. The inspiration for "just give the agent a fresh box".
- ## License
- [MIT](LICENSE)
src/detonate.js · Bundled script · 337 lines · 1 finding marked
- // "What does this file actually do when I run it?" Boot a fresh sandbox (no network adapter by default), turn on
- // Windows' own auditing, run the file, watch it, then report every process it started (with command lines), the
- // names it looked up, the connections it tried, what it changed on disk and in the registry (autoruns, services,
- // scheduled tasks, dropped executables) and what was on screen. The sandbox, and anything the file did, is then deleted.
- import fs from 'node:fs';
- import path from 'node:path';
- import { createHash } from 'node:crypto';
- import * as sbx from './core.js';
- import { shot } from './run.js';
- import { installCommand } from './install.js';
- const GUEST_DIR = 'C:\\Users\\WDAGUtilityAccount\\Downloads';
- const WATCH = `${sbx.GUEST.agent}\\watch.ps1`;
- /** Built-in Windows programs that malware leans on ("living off the land"). Seeing them is a reason to look closer, not proof. */
- export const LOLBINS = new Set(['powershell.exe', 'pwsh.exe', 'cmd.exe', 'wscript.exe', 'cscript.exe', 'mshta.exe', 'rundll32.exe',
- 'regsvr32.exe', 'certutil.exe', 'bitsadmin.exe', 'schtasks.exe', 'reg.exe', 'wmic.exe', 'net.exe', 'net1.exe', 'sc.exe',
- 'vssadmin.exe', 'bcdedit.exe', 'wbadmin.exe', 'whoami.exe', 'nltest.exe', 'curl.exe', 'installutil.exe', 'msbuild.exe',
- 'regasm.exe', 'cmstp.exe', 'attrib.exe', 'icacls.exe', 'takeown.exe', 'netsh.exe', 'wevtutil.exe', 'fodhelper.exe',
- 'msiexec.exe', 'forfiles.exe', 'hh.exe', 'odbcconf.exe', 'msxsl.exe', 'tasklist.exe', 'systeminfo.exe', 'ipconfig.exe']);
- const exeName = (p) => String(p || '').split('\\').pop().toLowerCase();
- /** How to run a file the way a double-click would (installers silently, scripts with their default host). */
- export function detonateCommand(guestPath, args = '') {
- const ext = path.extname(guestPath).toLowerCase();
- if (['.js', '.jse', '.vbs', '.vbe', '.wsf'].includes(ext)) return { file: 'wscript.exe', args: `"${guestPath}" ${args}`.trim() };
- if (ext === '.hta') return { file: 'mshta.exe', args: `"${guestPath}"` };
- if (['.msi', '.ps1', '.cmd', '.bat', '.exe'].includes(ext)) return installCommand(guestPath, args);
- throw new Error(`Don't know how to run ${ext || 'this file'}: use an .exe, .msi, .ps1, .cmd, .bat, .js, .vbs, .wsf or .hta.`);
- }
- /**
- * Split audited process starts into the file's own process tree and everything else, dropping the agent's own helpers.
- * events: [{pid, ppid, path, commandLine, time}] from 4688. The root is the process the agent launched.
- */
- export function processTree(events, rootPid, agentPid) {
- const byParent = new Map();
- for (const e of events) byParent.set(e.ppid, [...(byParent.get(e.ppid) || []), e]);
- const walk = (starts) => {
- const seen = new Set(starts);
- const queue = [...starts];
- while (queue.length) for (const c of byParent.get(queue.shift()) || []) if (!seen.has(c.pid)) { seen.add(c.pid); queue.push(c.pid); }
- return seen;
- };
- const mine = walk([rootPid]);
- const noise = walk(events.filter((e) => e.ppid === agentPid && e.pid !== rootPid).map((e) => e.pid));
- const byTime = (a, b) => String(a.time).localeCompare(String(b.time));
- const depth = (e) => { let d = 0; for (let p = e; p && p.pid !== rootPid && d < 50; p = events.find((x) => x.pid === p.ppid && mine.has(x.pid))) d++; return d; };
- return {
- pids: mine,
- tree: events.filter((e) => mine.has(e.pid)).sort(byTime).map((e) => ({ ...e, depth: depth(e) })),
- others: events.filter((e) => !mine.has(e.pid) && !noise.has(e.pid)).sort(byTime),
- };
- }
- /** Plain-language findings, most serious first. level: high (persistence, tampering), medium (worth a look), info. */
- export function findings({ tree = [], lookups = [], connections = [], diff, windows = [], crashes = [] }) {
- const out = [];
- const add = (level, text) => out.push({ level, text });
- const children = tree.filter((p) => p.depth > 0);
- if (diff) {
- const autoruns = diff.values.filter((v) => v.change !== 'removed' && /\\(Run|RunOnce)\\|\\Winlogon\\|\\Image File Execution Options\\/i.test(v.name));
- for (const v of autoruns) add('high', `starts itself with Windows: ${v.change} \`${v.name}\` = \`${v.after}\``);
- for (const s of diff.services.filter((x) => x.change === 'added')) add('high', `installed a service or driver: \`${s.name}\` (${(s.after || '').split('|')[3] || 'no image path'})`);
- const tasks = diff.files.added.filter((f) => /^C:\\Windows\\System32\\Tasks\\/i.test(f.path));
- for (const t of tasks) add('high', `created a scheduled task: \`${t.path.slice('C:\\Windows\\System32\\Tasks\\'.length)}\``);
- const startup = [...diff.files.added.map((f) => f.path), ...diff.files.executables].filter((p) => /\\Start Menu\\Programs\\Startup\\/i.test(p));
- Dismissed after review: Puts a file in the Windows Startup folder, so it runs at every login
- Line 68 on GitHub
- for (const p of [...new Set(startup)]) add('high', `put something in a Startup folder: \`${p}\``);
- if (diff.files.changed.some((p) => /\\drivers\\etc\\hosts$/i.test(p))) add('high', 'changed the hosts file (can redirect websites)');
- const policy = diff.registry.added.filter((k) => /\\Policies\\Microsoft\\(Windows Defender|WindowsFirewall)|\\SharedAccess\\Parameters\\FirewallPolicy/i.test(k.path));
- for (const k of policy) add('high', `changed security policy: \`${k.path}\``);
- const env = diff.values.filter((v) => /\\Environment\\/i.test(v.name));
- if (env.length) add('medium', `changed environment variables: ${env.map((v) => `\`${v.name.split('\\').pop()}\``).join(', ')}`);
- if (diff.files.executableCount) {
- const shown = diff.files.executables.slice(0, 5).map((p) => `\`${p}\``).join(', ');
- add('medium', `wrote ${diff.files.executableCount} runnable file(s): ${shown}${diff.files.executableCount > 5 ? ', …' : ''}`);
- }
- for (const p of diff.programsAdded) add('info', `installed ${p.displayName}${p.displayVersion ? ` ${p.displayVersion}` : ''}`);
- }
- const tools = [...new Set(children.map((p) => exeName(p.path)).filter((n) => LOLBINS.has(n)))];
- if (tools.length) add('medium', `ran built-in Windows tools that malware often uses: ${tools.join(', ')}`);
- if (lookups.length) add('medium', `looked up ${lookups.length} internet name(s): ${lookups.slice(0, 6).map((l) => l.name).join(', ')}${lookups.length > 6 ? ', …' : ''}`);
- if (connections.length) {
- const ends = connections.slice(0, 6).map((c) => `${c.address}:${c.port}`).join(', ');
- add('medium', `tried to connect to ${connections.length} address(es): ${ends}${connections.length > 6 ? ', …' : ''}`);
- }
- if (children.length) add('info', `started ${children.length} other process(es)`);
- if (windows.length) add('info', `opened ${windows.length} window(s): ${windows.map((w) => `"${w.title}"`).join(', ')}`);
- if (crashes.length) add('info', `${crashes.length} application error(s) in the event log`);
- const rank = { high: 0, medium: 1, info: 2 };
- return out.sort((a, b) => rank[a.level] - rank[b.level]);
- }
- /** Dedupe DNS events into one row per name (failed unless any attempt succeeded) and connections into one row per endpoint. */
- export function network(c, pids) {
- const names = new Map();
- for (const d of c.dns.filter((x) => pids.has(x.pid))) {
- const n = names.get(d.name.toLowerCase()) || { name: d.name, pid: d.pid, time: d.time, ok: false };
- if (d.status === '0') n.ok = true;
- names.set(d.name.toLowerCase(), n);
- }
- const ends = new Map();
- for (const x of c.connections.filter((y) => pids.has(y.pid))) {
- const k = `${x.address}|${x.port}|${x.protocol}`;
- const e = ends.get(k) || { ...x, count: 0 };
- e.count++; e.blocked = e.blocked && x.blocked;
- ends.set(k, e);
- }
- return { lookups: [...names.values()], connections: [...ends.values()] };
- }
- async function collect(since) {
- const r = await sbx.exec({ command: `& '${WATCH}' -Since '${since}'`, timeoutSec: 120 });
- if (r.exitCode !== 0) throw new Error(`collecting events failed: ${r.stderr || r.stdout}`);
- const c = JSON.parse(r.stdout.trim());
- for (const k of ['processes', 'connections', 'dns', 'alive']) c[k] = [].concat(c[k] ?? []);
- return c;
- }
- /**
- * file: host path. Options: args, durationSec (max watch time, default 60), full (always watch the whole time instead of
- * stopping once everything it started has exited), shotEverySec (default 15), exclude[], keep, plus startSandbox options
- * (network defaults to 'off').
- */
- export async function detonate(o) {
- const src = path.resolve(o.file);
- if (!fs.existsSync(src) || !fs.statSync(src).isFile()) throw new Error(`File not found: ${src}`);
- const name = path.basename(src);
- detonateCommand(name); // validate the extension before booting
- const net = o.network ?? (o.internet === true ? 'on' : 'off');
- const durationSec = o.durationSec ?? 60;
- const r = {
- file: name, hostPath: src, sha256: createHash('sha256').update(fs.readFileSync(src)).digest('hex'), args: o.args || '',
- startedAt: new Date().toISOString(), shots: [], windows: [], crashes: [],
- };
- const t0 = Date.now();
- let booted = false;
- try {
- const boot = await sbx.startSandbox({ ...o, network: net });
- booted = true;
- r.sandbox = { id: boot.id, epoch: boot.epoch, network: boot.network, bootSeconds: boot.bootSeconds };
- r.runDir = boot.runDir; r.outDir = boot.outDir;
- const guest = `${GUEST_DIR}\\${name}`;
- await sbx.copyIn(src, guest);
- const ag = await sbx.exec({ command: '(Get-CimInstance Win32_Process -Filter "ProcessId=$PID").ParentProcessId', timeoutSec: 60 });
- const agentPid = Number(ag.stdout.trim());
- sbx.log('turning on process, connection and DNS auditing');
- const armed = await sbx.exec({ command: `& '${WATCH}' -Arm`, timeoutSec: 60 });
- if (armed.exitCode !== 0) throw new Error(`could not turn on auditing: ${armed.stderr || armed.stdout}`);
- r.since = armed.stdout.trim();
- sbx.log('snapshot before');
- await sbx.snapshot('before', o.exclude);
- const windowsBefore = await sbx.windows();
- const cmd = detonateCommand(guest, o.args);
- sbx.log(`running ${name} and watching for up to ${durationSec}s`);
- const l = await sbx.launch({ path: cmd.file, args: cmd.args, cwd: GUEST_DIR, waitForWindowSec: 0 });
- r.command = `${cmd.file} ${cmd.args || ''}`.trim();
- r.rootPid = l.pid;
- const every = o.shotEverySec ?? 15;
- let nextShot = 5, quiet = 0, w0 = Date.now();
- for (;;) {
- await sbx.sleep(2500);
- const s = (Date.now() - w0) / 1000;
- if (s >= nextShot) { r.shots.push(await shot({ name: `t+${Math.round(s)}s` })); nextShot += every; }
- if (s >= durationSec) break;
- const p = await sbx.processInfo(l.pid);
- if (p.hasExited) {
- r.exitCode ??= p.exitCode;
- if (o.full) continue;
- const c = await collect(r.since);
- const t = processTree(c.processes, l.pid, agentPid);
- if (c.alive.some((pid) => t.pids.has(pid))) quiet = 0;
- else if (++quiet >= 3) { r.stoppedEarly = true; break; }
- }
- }
- r.watchedSeconds = (Date.now() - w0) / 1000;
- sbx.log('collecting what happened');
- r.shots.push(await shot({ name: 'end' }));
- const seen = new Set(windowsBefore.map((w) => `${w.pid}|${w.title}`));
- r.windows = (await sbx.windows()).filter((w) => !seen.has(`${w.pid}|${w.title}`));
- const c = await collect(r.since);
- const t = processTree(c.processes, l.pid, agentPid);
- // Measure from the file's own start, and leave out background activity from before it ran (the snapshot, boot tasks).
- r.launchedAt = t.tree[0]?.time ?? r.since;
- const after = (x) => ms(x.time) >= ms(r.launchedAt) - 1000;
- r.tree = t.tree; r.others = t.others.filter(after);
- r.stillRunning = t.tree.filter((p) => c.alive.includes(p.pid)).map((p) => p.pid);
- Object.assign(r, network(c, t.pids));
- const otherPids = new Set(r.others.map((p) => p.pid));
- r.otherLookups = [...new Set(c.dns.filter((d) => !t.pids.has(d.pid) && after(d)).map((d) => d.name.toLowerCase()))];
- r.otherConnections = network(c, otherPids).connections;
- r.crashes = await sbx.appErrors(r.since);
- sbx.log('snapshot after');
- await sbx.snapshot('after', o.exclude);
- r.diff = await sbx.diffSnapshots('before', 'after', o.max ?? 200);
- } catch (e) {
- r.error = e.message;
- r.errorStack = e.stack;
- } finally {
- if (booted && !o.keep) {
- sbx.log('destroying the sandbox');
- const st = await sbx.stopSandbox({ target: r.sandbox }).catch((e) => ({ error: e.message }));
- if (st.error) r.stopError = st.error;
- }
- r.kept = booted && !!o.keep;
- }
- r.seconds = (Date.now() - t0) / 1000;
- r.findings = r.error ? [] : findings(r);
- if (r.outDir) {
- fs.mkdirSync(r.outDir, { recursive: true });
- r.reportPath = path.join(r.outDir, 'report.md');
- fs.writeFileSync(r.reportPath, renderDetonateReport(r));
- fs.writeFileSync(path.join(r.outDir, 'report.json'), JSON.stringify({ ...r, shots: r.shots.map(({ previewBase64, ...s }) => s) }, null, 2));
- }
- return r;
- }
- const icon = { high: '🔴', medium: '🟠', info: '⚪' };
- const count = (r, level) => r.findings.filter((f) => f.level === level).length;
- const plain = (s) => s.replace(/`/g, '');
- export function headline(r) {
- if (r.error) return `ERROR ${r.file}: ${r.error.split('\n')[0]}`;
- const h = count(r, 'high'), m = count(r, 'medium');
- const verdict = h ? `${h} red flag(s)` : m ? `${m} thing(s) worth a look` : 'nothing notable';
- return `${r.file}: ${verdict} (watched ${r.watchedSeconds?.toFixed(0) ?? '?'}s, network ${r.sandbox?.network ?? '?'})`;
- }
- export function detonateSummary(r) {
- const lines = [headline(r)];
- const row = (k, v) => lines.push(` ${k.padEnd(10)} ${v}`);
- for (const [i, f] of r.findings.filter((x) => x.level !== 'info').entries()) row(i ? '' : 'findings', `${icon[f.level]} ${plain(f.text)}`);
- if (r.tree) row('processes', `${r.tree.length} (${r.tree.slice(0, 5).map((p) => exeName(p.path)).join(' → ')}${r.tree.length > 5 ? ' …' : ''})`);
- if (r.lookups) row('network', `${r.lookups.length} name lookup(s), ${r.connections.length} connection attempt(s)`);
- if (r.diff) {
- const d = r.diff;
- row('changed', `${d.files.addedCount} files added, ${d.files.changedCount} changed, ${d.registry.addedCount} registry keys, ` +
- `${d.values.length} autorun/env values, ${d.services.length} services`);
- }
- if (r.reportPath) row('report', r.reportPath);
- return lines.join('\n');
- }
- const fence = (s) => '```text\n' + (s || '').trimEnd().slice(-20_000) + '\n```';
- const md = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
- /** Guest ISO times have 7-digit fractions; trim to 3 for Date.parse. */
- const ms = (s) => Date.parse(String(s).replace(/(\.\d{3})\d+/, '$1'));
- /** Seconds since `since`, e.g. "+3.2s". */
- const at = (since, t) => {
- const d = (ms(t) - ms(since)) / 1000;
- return Number.isFinite(d) ? `${d < 0 ? '' : '+'}${d.toFixed(1)}s` : '';
- };
- export function renderDetonateReport(r) {
- const rel = (p) => path.relative(r.outDir, p).split(path.sep).join('/');
- const lines = [`# sbx detonate: ${r.file}`, '', `**${headline(r)}**`, '', '| | |', '|---|---|',
- `| File | \`${r.hostPath}\`${r.args ? ` \`${r.args}\`` : ''} |`,
- `| SHA-256 | \`${r.sha256}\` |`,
- `| Sandbox | fresh Windows Sandbox, network ${r.sandbox?.network ?? '?'}, booted in ${r.sandbox?.bootSeconds?.toFixed(1) ?? '?'}s |`,
- `| Ran | ${r.command ? `\`${md(r.command)}\`` : 'not run'} |`,
- `| Watched | ${r.watchedSeconds?.toFixed(0) ?? '?'}s${r.stoppedEarly ? ' (stopped early: everything it started had exited)' : ''}` +
- `${r.exitCode !== undefined && r.exitCode !== null ? `, exit code ${r.exitCode}` : ''}${r.stillRunning?.length ? `, ${r.stillRunning.length} process(es) still running at the end` : ''} |`,
- `| Total time | ${r.seconds.toFixed(1)}s |`, ''];
- if (r.findings.length) {
- lines.push('## Findings', '');
- for (const f of r.findings) lines.push(`- ${icon[f.level]} ${f.text}`);
- lines.push('', '_Heuristics, not a verdict: installers legitimately add autoruns and services. Read the details below._', '');
- }
- if (r.tree) {
- const events = [
- ...r.tree.map((p) => ({ time: p.time, text: `start ${exeName(p.path)} (pid ${p.pid}) ${p.commandLine || p.path}` })),
- ...(r.lookups || []).map((l) => ({ time: l.time, text: `lookup ${l.name} (${l.ok ? 'resolved' : 'failed'})` })),
- ...(r.connections || []).map((c) => ({ time: c.time, text: `connect ${c.address}:${c.port}/${c.protocol} ${c.blocked ? 'blocked' : 'allowed'} (${exeName(c.path)})` })),
- ].sort((a, b) => String(a.time).localeCompare(String(b.time)));
- lines.push('## Timeline', '', fence(events.slice(0, 200).map((e) => `${at(r.launchedAt || r.since, e.time).padStart(7)} ${e.text}`).join('\n')), '');
- lines.push('## Processes it started', '', '```text');
- for (const p of r.tree) lines.push(`${' '.repeat(p.depth)}${exeName(p.path)} (pid ${p.pid})${r.stillRunning?.includes(p.pid) ? ' [still running]' : ''} ${p.commandLine || p.path}`);
- lines.push('```', '');
- }
- if (r.lookups?.length || r.connections?.length) {
- lines.push('## Network', '');
- if (r.lookups.length) {
- lines.push('| Name looked up | Result | By |', '|---|---|---|');
- for (const l of r.lookups) lines.push(`| \`${md(l.name)}\` | ${l.ok ? 'resolved' : 'failed'} | pid ${l.pid} |`);
- lines.push('');
- }
- if (r.connections.length) {
- lines.push('| Connection | Result | By |', '|---|---|---|');
- for (const c of r.connections) lines.push(`| ${c.address}:${c.port}/${c.protocol}${c.count > 1 ? ` ×${c.count}` : ''} | ${c.blocked ? 'blocked' : 'allowed'} | \`${md(c.path)}\` (pid ${c.pid}) |`);
- lines.push('');
- }
- }
- if (r.sandbox?.network === 'off') {
- lines.push('_Network was off (no adapter): name lookups are still recorded, but connections to IP addresses never leave the process. ' +
- 'Use `--network firewall` to also see the addresses it tries to reach (blocked by the guest firewall)._', '');
- }
- if (r.diff) lines.push('## What it changed', '', sbx.formatDiff(r.diff, { title: 'before → after' }), '');
- if (r.diff?.files.executables.length) {
- lines.push('**Runnable files written**', '');
- for (const p of r.diff.files.executables) lines.push(`- \`${p}\``);
- if (r.diff.files.executableCount > r.diff.files.executables.length) lines.push(`- … and ${r.diff.files.executableCount - r.diff.files.executables.length} more`);
- lines.push('');
- }
- if (r.windows.length) {
- lines.push('## Windows it opened', '');
- for (const w of r.windows) lines.push(`- ${w.process} (pid ${w.pid}): "${w.title}"`);
- lines.push('');
- }
- if (r.crashes.length) {
- lines.push('## Application errors', '');
- for (const e of r.crashes.slice(0, 10)) lines.push(`- ${e.source} ${e.id}: ${md(String(e.message).slice(0, 300))}`);
- lines.push('');
- }
- if (r.others?.length || r.otherLookups?.length) {
- lines.push('## Everything else that happened', '', 'Usually Windows itself, but a file can also act through services, WMI or scheduled tasks.', '');
- if (r.others.length) {
- lines.push('```text');
- for (const p of r.others.slice(0, 40)) lines.push(`${at(r.launchedAt || r.since, p.time).padStart(7)} ${exeName(p.path)} (pid ${p.pid}, parent ${exeName(p.parentPath)}) ${p.commandLine || p.path}`);
- if (r.others.length > 40) lines.push(`… and ${r.others.length - 40} more`);
- lines.push('```', '');
- }
- if (r.otherLookups?.length) lines.push(`Other name lookups: ${r.otherLookups.slice(0, 30).map((n) => `\`${n}\``).join(', ')}`, '');
- if (r.otherConnections?.length) lines.push(`Other connections: ${r.otherConnections.slice(0, 20).map((c) => `${c.address}:${c.port} (${exeName(c.path)})`).join(', ')}`, '');
- }
- if (r.shots.length) {
- lines.push('## Screenshots', '');
- for (const s of r.shots) lines.push(`**${s.name}**`, '', `})`, '');
- }
- if (r.error) lines.push('## Error', '', fence(r.errorStack || r.error), '');
- lines.push('---', 'Files in this folder were written by the sandbox: treat them as untrusted. ' +
- `Audit log: \`${path.join(r.runDir || '', 'audit.jsonl')}\`${r.kept ? ' · sandbox left running (--keep)' : ''}`);
- return lines.join('\n') + '\n';
- }
src/provision.js · Bundled script · 222 lines · 2 findings marked
- // Explicit opt-in only: verified downloads happen on the host, never on the network-isolated guest.
- import fs from 'node:fs';
- import path from 'node:path';
- import { createHash, randomUUID } from 'node:crypto';
- import { execFile } from 'node:child_process';
- import { Readable } from 'node:stream';
- import { pipeline } from 'node:stream/promises';
- import * as sbx from './core.js';
- import { scanDependencies } from './deps.js';
- import { atomicJson, readJson, withStateLock } from './coordination.js';
- const q = (s) => `'${String(s).replace(/'/g, "''")}'`;
- const FRAMEWORKS = {
- 'Microsoft.NETCore.App': 'runtime',
- 'Microsoft.WindowsDesktop.App': 'windowsdesktop',
- 'Microsoft.AspNetCore.App': 'aspnetcore-runtime',
- };
- const arches = new Set(['x86', 'x64', 'arm64']);
- const official = (url) => {
- const u = new URL(url);
- if (u.protocol !== 'https:' || !['aka.ms', 'download.visualstudio.microsoft.com', 'download.microsoft.com',
- 'builds.dotnet.microsoft.com', 'dotnetcli.azureedge.net', 'dotnetcli.blob.core.windows.net',
- 'ci.dot.net'].includes(u.hostname)) throw new Error(`Not an approved Microsoft download URL: ${url}`);
- return u;
- };
- async function downloadResponse(url) {
- for (let i = 0; i < 10; i++) {
- official(url);
- const r = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(120_000) });
- if ([301, 302, 303, 307, 308].includes(r.status)) {
- await r.body?.cancel();
- const location = r.headers.get('location');
- if (!location) throw new Error(`Microsoft download redirect has no Location: ${url}`);
- url = new URL(location, url).href;
- continue;
- }
- if (!r.ok) { await r.body?.cancel(); throw new Error(`Microsoft download failed: HTTP ${r.status} (${url})`); }
- return r;
- }
- throw new Error('Too many Microsoft download redirects');
- }
- export function planProvision(scan, requested) {
- if (typeof requested !== 'string' || !requested.trim()) throw new Error('Provisioning requires auto or a comma-separated component list');
- let items;
- if (requested === 'auto') {
- items = [];
- for (const r of scan.requirements) {
- if (r.status === 'missing') {
- if (!FRAMEWORKS[r.component] && r.component !== 'VC++ redistributable') {
- throw new Error(`Cannot auto-provision ${r.component}. ${r.remediation}`);
- }
- items.push({ component: r.component, version: r.version, architecture: r.architecture, rollForward: r.rollForward, applyPatches: r.applyPatches });
- } else {
- const war = /^Microsoft\.WindowsAppRuntime\.(\d+\.\d+)$/.exec(r.component);
- if (war) items.push({ component: 'Windows App Runtime', version: war[1], architecture: r.architecture || 'unknown' });
- else if (r.component === 'Windows App Runtime' && r.status !== 'app-local') {
- throw new Error('Windows App Runtime version cannot be inferred. Pass --provision windows-app-runtime:<major.minor>:<architecture> explicitly.');
- } else if (r.status === 'unknown') {
- throw new Error(`Cannot auto-provision an unknown requirement: ${r.component}. ${r.remediation}`);
- }
- }
- }
- } else {
- items = requested.split(',').map((token) => {
- const [name, version, architecture, extra] = token.trim().split(':');
- const component = ({ vcredist: 'VC++ redistributable', dotnet: 'Microsoft.NETCore.App',
- desktop: 'Microsoft.WindowsDesktop.App', aspnetcore: 'Microsoft.AspNetCore.App', 'windows-app-runtime': 'Windows App Runtime' })[name];
- if (!component || extra) throw new Error(`Unknown provision component: ${token}`);
- if (name === 'vcredist') {
- if (architecture) throw new Error('Use vcredist:<architecture>');
- return { component, architecture: version || 'x64' };
- }
- if (!/^\d+\.\d+(?:\.\d+)?$/.test(version || '')) throw new Error(`Use ${name}:<version>:<architecture> (for example desktop:10.0:x64)`);
- return { component, version, architecture: architecture || 'x64', rollForward: 'LatestPatch' };
- });
- }
- for (const item of items) {
- if (!arches.has(item.architecture)) throw new Error(`Cannot provision ${item.component} for unknown architecture; supply an explicit component list.`);
- if (FRAMEWORKS[item.component] && !/^\d+\.\d+(?:\.\d+)?$/.test(item.version || '')) throw new Error(`Cannot resolve runtime version ${item.version}`);
- }
- const exact = (r) => r.rollForward === 'Disable' || r.applyPatches === false;
- const unique = [];
- for (const item of items) {
- const previous = unique.find((x) => x.component === item.component && x.version === item.version && x.architecture === item.architecture);
- if (!previous) unique.push({ ...item });
- else if (exact(item)) { previous.rollForward = 'Disable'; previous.applyPatches = false; }
- }
- if (requested === 'auto') {
- for (const item of unique.filter((r) => FRAMEWORKS[r.component])) {
- const channel = item.version.split('.').slice(0, 2).join('.');
- const other = unique.find((r) => FRAMEWORKS[r.component] && r.architecture === item.architecture &&
- r.version.split('.').slice(0, 2).join('.') === channel && r !== item &&
- (r.component === item.component || [r.component, item.component].every((c) => ['Microsoft.NETCore.App', 'Microsoft.WindowsDesktop.App'].includes(c))) &&
- (exact(item) || exact(r)) && (r.version !== item.version || exact(item) !== exact(r)));
- if (other) throw new Error(`Conflicting auto runtime policies for ${item.component} and ${other.component}. An exact runtime cannot be replaced by a newer desktop bundle; use an explicit installer list and verify the app's required versions.`);
- }
- }
- // The desktop runtime bundle also installs the same-channel core runtime.
- return unique.filter((r) => !(r.component === 'Microsoft.NETCore.App' &&
- unique.some((x) => x.component === 'Microsoft.WindowsDesktop.App' && x.version === r.version && x.architecture === r.architecture)));
- }
- export function selectDotnetFile(metadata, item) {
- const key = FRAMEWORKS[item.component], channel = item.version.split('.').slice(0, 2).join('.');
- const minimum = item.version.split('.').map(Number);
- const acceptable = (v) => {
- if (!/^\d+\.\d+\.\d+$/.test(v || '')) return false;
- const parts = v.split('.').map(Number);
- if (parts.slice(0, 2).join('.') !== channel) return false;
- if (item.rollForward === 'Disable' || item.applyPatches === false) return v === item.version;
- return parts[2] >= (minimum[2] || 0);
- };
- const candidates = (metadata.releases || []).map((r) => r[key]).filter((r) => r && acceptable(r.version))
- .sort((a, b) => Number(b.version.split('.')[2]) - Number(a.version.split('.')[2]));
- for (const release of candidates) {
- const file = release.files?.find((f) => f.rid === `win-${item.architecture}` && /\.exe$/i.test(f.name));
- if (file) {
- official(file.url);
- if (!/^[a-f0-9]{128}$/i.test(file.hash || '')) throw new Error('Official .NET metadata has no valid SHA-512 hash');
- return { ...item, version: release.version, url: file.url, sha512: file.hash.toLowerCase(), args: '/install /quiet /norestart' };
- }
- }
- throw new Error(`No compatible official ${item.component} installer for ${item.version} ${item.architecture} (rollForward ${item.rollForward || 'Minor'}).`);
- }
- async function resolveInstaller(item) {
- if (FRAMEWORKS[item.component]) {
- const channel = item.version.split('.').slice(0, 2).join('.');
- const response = await downloadResponse(`https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/${channel}/releases.json`);
- return selectDotnetFile(await response.json(), item);
- }
- if (item.component === 'VC++ redistributable') return { ...item,
- url: `https://aka.ms/vc14/vc_redist.${item.architecture}.exe`, args: '/install /quiet /norestart' };
- Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
- Line 135 on GitHub
- if (item.component === 'Windows App Runtime') {
- if (!/^\d+\.\d+$/.test(item.version)) throw new Error('Windows App Runtime requires a major.minor release channel');
- return { ...item, url: `https://aka.ms/windowsappsdk/${item.version}/latest/windowsappruntimeinstall-${item.architecture}.exe`, args: '--quiet' };
- Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
- Line 138 on GitHub
- }
- throw new Error(`Unsupported redistributable: ${item.component}`);
- }
- async function verify(file, expected) {
- const hash = createHash(expected ? 'sha512' : 'sha256');
- for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
- const digest = hash.digest('hex');
- if (expected && digest !== expected.toLowerCase()) throw new Error(`SHA-512 mismatch for ${file}`);
- const script = `$ErrorActionPreference='Stop'; Import-Module ($PSHOME+'\\Modules\\Microsoft.PowerShell.Security\\Microsoft.PowerShell.Security.psd1') -Force; $s=Get-AuthenticodeSignature -LiteralPath ${q(file)}; if ($s.Status -ne 'Valid' -or $s.SignerCertificate.Subject -notmatch '(^|,\\s*)O=Microsoft Corporation(,|$)') { throw ('Not a valid Microsoft-signed installer: '+$s.Status) }; $v=[Diagnostics.FileVersionInfo]::GetVersionInfo(${q(file)}); @{signer=$s.SignerCertificate.Subject;fileVersion=$v.FileVersion;productVersion=$v.ProductVersion} | ConvertTo-Json -Compress`;
- const signature = await new Promise((resolve, reject) => execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script],
- { timeout: 120_000, windowsHide: true }, (err, stdout, stderr) => err ? reject(new Error(`Installer signature verification failed: ${stderr || err.message}`)) : resolve(stdout.trim())));
- return { algorithm: expected ? 'sha512' : 'sha256', hash: digest, ...JSON.parse(signature) };
- }
- export async function prepareProvision(scan, requested) {
- const prepared = [];
- for (const item of planProvision(scan, requested)) {
- const installer = await resolveInstaller(item);
- const cache = path.join(sbx.HOME, 'cache', 'redistributables');
- fs.mkdirSync(cache, { recursive: true });
- const name = createHash('sha256').update(installer.url + (installer.sha512 || '')).digest('hex') + '.exe';
- const file = path.join(cache, name);
- if (!fs.existsSync(file)) {
- const partial = `${file}.${randomUUID()}.partial`;
- try {
- sbx.log(`downloading ${installer.component} ${installer.version || ''} ${installer.architecture} on the host`);
- const response = await downloadResponse(installer.url);
- await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(partial, { flags: 'wx' }));
- const verification = await verify(partial, installer.sha512);
- fs.renameSync(partial, file);
- prepared.push({ ...installer, file, verification });
- } finally {
- if (fs.existsSync(partial)) fs.unlinkSync(partial);
- }
- } else prepared.push({ ...installer, file, verification: await verify(file, installer.sha512) });
- }
- return prepared;
- }
- export function recordProvisioning(runDir, requested, provisioned) {
- const file = path.join(runDir, 'provisioning.json');
- withStateLock(runDir, () => {
- const previous = readJson(file);
- const records = new Map((previous?.provisioned || []).map((record) => [JSON.stringify(record), record]));
- for (const record of provisioned) records.set(JSON.stringify(record), record);
- atomicJson(file, { cleanMachine: false, requested, provisioned: [...records.values()], updatedAt: new Date().toISOString() });
- });
- }
- export async function installProvision(prepared, onInstalled = () => {}, target) {
- const installed = [];
- if (prepared.length && !target) target = await sbx.current();
- if (prepared.length && !target) throw new Error('Start a sandbox before provisioning into it.');
- for (const item of prepared) {
- const copied = await sbx.copyIn(item.file, `C:\\sbx-provision\\${path.basename(item.file)}`, target);
- const command = `$ErrorActionPreference='Stop'; $p=Start-Process -FilePath ${q(copied.path)} -ArgumentList ${q(item.args)} -Wait -PassThru; exit $p.ExitCode`;
- const result = await sbx.exec({ command, timeoutSec: 600 }, target);
- // 3010 is a successful install requiring reboot, not proof the current guest is usable.
- if (result.timedOut || result.exitCode !== 0) throw new Error(`Provisioning ${item.component} failed (exit ${result.exitCode}${result.timedOut ? ', timed out' : ''}). ${result.exitCode === 3010 ? 'Installer requires reboot; this run cannot be called a pass.' : result.stderr || result.stdout || ''}`);
- const record = { component: item.component, version: item.version, architecture: item.architecture,
- source: item.url, verification: item.verification, exitCode: result.exitCode };
- installed.push(record);
- onInstalled(record);
- }
- return installed;
- }
- /** Provision an already-started sandbox; never starts or adopts one. */
- export async function provisionSandbox(app, requested) {
- const state = await sbx.current();
- if (!state) throw new Error('Start a sandbox before provisioning into it.');
- const dependencies = scanDependencies(app);
- const prepared = await prepareProvision(dependencies, requested);
- const current = await sbx.status();
- if (!current.running || current.id !== state.id || current.epoch !== state.epoch) throw new Error('Sandbox changed while preparing dependencies; nothing installed.');
- const provisioned = current.provisioning?.provisioned || [];
- recordProvisioning(current.runDir, requested, provisioned);
- const installed = await installProvision(prepared, (record) => {
- provisioned.push(record);
- recordProvisioning(current.runDir, requested, provisioned);
- }, state);
- return { cleanMachine: false, dependencies, provisioned: installed, provenancePath: path.join(current.runDir, 'provisioning.json') };
- }
Version history
v1.2.011/7/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.