Skip to content
Back to search

sandbox-mcp

SkillWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shanselman--sandbox-mcp/badge.svg)](/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

i

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.

  1. {
  2. "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  3. "name": "sandbox-mcp",
  4. "version": "1.2.0",
  5. "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.",
  6. "author": {
  7. "name": "Scott Hanselman",
  8. "url": "https://github.com/shanselman"
  9. },
  10. "homepage": "https://github.com/shanselman/sandbox-mcp/blob/main/docs/agent-plugin.md",
  11. "repository": "https://github.com/shanselman/sandbox-mcp",
  12. "license": "MIT",
  13. "keywords": ["windows-sandbox", "windows", "sandbox", "testing", "installer", "ui-automation", "mcp"]
  14. }
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.

  1. # sandbox-mcp
  2. ## Give your AI agent a brand-new Windows PC. Then throw it away.
  3. Not your desktop. Not a container pretending to be Windows. **A real, disposable Windows 11 machine**:
  4. boot it, deploy your app, drive the controls, catch the crash, keep the evidence, delete the PC.
  5. Run it directly with `sbx`; the optional MCP adapter exposes discoverable tools and inline images for clients that want them.
  6. Both interfaces use the same engine. The measured GUI samples take roughly **40-50 seconds** end to end.
  7. See the [website](https://shanselman.github.io/sandbox-mcp/).
  8. ![Real offline Sandbox: Haptics app UI Automation, light-to-dark theme, app exit and guest teardown](docs/sandbox-teaser.gif)
  9. *Real app, real guest: Haptics Everywhere's self-contained WPF/WinForms desktop app in a fresh, network-off Sandbox.
  10. UIA selects the Inspector, the guest switches light to dark, the app relaunches and exits, then the guest is destroyed.
  11. 10-second, 183 KB edited footage: light Inspector slowed for readability, repeated dark frames trimmed.
  12. Boot/teardown title cards summarize actual logs, not filmed boot/shutdown.
  13. No guest runtime installation or haptic-hardware claim. [Fresh dark lab screenshot](docs/haptics-teaser.png) ·
  14. [Earlier light-theme inspector](docs/haptics-inspector.png).*
  15. ### 🤖 Let your agent set it up
  16. Give this to your bot. It checks the PC, verifies the download and asks before admin changes or a restart.
  17. The CLI works on its own; configure MCP only if your agent needs that interface:
  18. ```text
  19. Set up the sandbox-mcp CLI by following:
  20. https://raw.githubusercontent.com/shanselman/sandbox-mcp/main/docs/agent-setup.md
  21. 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.
  22. ```
  23. **[Download v1.2.0](https://github.com/shanselman/sandbox-mcp/releases/tag/v1.2.0)**: portable CLI + optional MCP server,
  24. bundled Node.js, guest agent and setup instructions. No Node/npm installation needed.
  25. ### “Works on my machine.” Caught in 30 seconds.
  26. The dev box had Visual C++ installed. The fresh, **network-off** customer PC did not:
  27. ```text
  28. FAIL NativeProof.exe on a fresh Windows Sandbox (29.8s)
  29. why exited with code -1073741515; Missing dependency: VC++ redistributable.
  30. ```
  31. Opt in to the verified runtime install, then repeat on another fresh guest:
  32. ```text
  33. PASS NativeProof.exe on a fresh Windows Sandbox (30.9s)
  34. baseline PROVISIONED (not a clean-machine pass): VC++ redistributable x64
  35. process exited with code 0
  36. ```
  37. Those are [actual measured results](docs/compatibility.md#combined-feature-verification), not illustrative output.
  38. The installer was Microsoft-signed **14.51.36247.0**, downloaded and verified on the host. Guest networking stayed
  39. off. `sbx deps app.exe` diagnoses; `sbx run app.exe --provision auto` installs **only when explicitly requested**.
  40. ### What your agent gets
  41. | A clean customer PC | A real desktop to drive | Evidence that survives |
  42. |---|---|---|
  43. | Fresh on every boot; no implicit app-runtime installs | Native UIA: inspect, type, click, toggle, wait | PNGs, bounded recordings, self-contained HTML, optional MP4 |
  44. | Dependency diagnosis; explicit verified provisioning | WinUI, WPF, WinForms, Win32; MSIX/AUMID activation | Process state, exit codes, crash events, reports |
  45. | Network **off / firewall / on** | CLI + MCP share state; verified warm incremental deploy | Installer/uninstaller diffs; detonation observations |
  46. Same clean-machine loop, different frameworks:
  47. | WinUI 3, packaged | WPF, self-contained | Native Win32, packaged |
  48. |---|---|---|
  49. | ![WinUI greeting and counter after final integrated MCP test](docs/integration-winui-msix.png) | ![WPF greeting after final integrated UIA test](docs/integration-wpf.png) | ![Native Win32 greeting after UIA](docs/compatibility/native-msix.png) |
  50. These are real offline-guest screenshots, not host mockups. WinUI/WPF were refreshed against the final integrated
  51. source; the full matrix covers seven configurations. Exact builds, timings, startup defects
  52. found and remaining coverage gaps are in the [compatibility evidence](docs/compatibility.md).
  53. [Download/setup](#download-and-try-it-no-nodejs-install) · [Agent setup guide](docs/agent-setup.md) ·
  54. [Measured compatibility and honest limits](docs/compatibility.md) · [CLI and MCP interfaces](#one-engine-two-interfaces)
  55. <details>
  56. <summary>See a fresh, recorded UI Automation session</summary>
  57. ![UI Automation changes real WinUI controls inside a network-off Sandbox](docs/sandbox-in-action.gif)
  58. This 138 KB animation comes from a new 74-frame guest recording: UIA changes the text, invokes buttons and
  59. increments the counter. The guest was stopped afterward; the HTML viewer, MP4 and frames remained on the host.
  60. No synthetic screenshots. This small fixture proves the automation path; the rich app above shows the real-app use case.
  61. </details>
  62. ## Why
  63. **A Windows Sandbox showcase, not a framework gate.** WinUI 3 is welcome, but the entry point is a Windows
  64. executable or package, not a particular UI framework. Bring an app that can run in Sandbox and its prerequisites:
  65. Win32, WinForms, WPF, WinUI, console, PyInstaller or Electron builds use the same clean-machine workflow.
  66. Installers and untrusted files have their own audit/detonation workflows. This is not a promise that every
  67. Windows app or hardware-dependent workload works in Sandbox. See the [measured compatibility matrix](docs/compatibility.md)
  68. and [small source samples](samples/README.md) in this matching checkout for the configurations actually exercised.
  69. [winapp CLI's Sandbox execution](https://github.com/microsoft/winappCli/blob/5f379fb55517b7a47f9aad11885a7c1676dcca2e/docs/sandbox-execution.md)
  70. also supports packaged and unpackaged apps: its `--on sandbox` offers a warm, identity-aware developer loop,
  71. runtime preparation and WinUI diagnostics. sandbox-mcp emphasizes **fresh-by-default clean-machine reports**,
  72. network-off shared-folder mailbox transport, installer/uninstaller diffs and detonation. The tools have
  73. overlapping app support but different defaults and goals; sandbox-mcp never implicitly installs app prerequisites.
  74. Inbox Framework/CBS components can exist, but are not proof that an app's requested runtime is available.
  75. "It works on my machine" is usually true: your machine has every runtime, SDK, redistributable, font, registry key
  76. and PATH entry you ever installed. Your users' machines don't. Windows Sandbox is a pristine Windows that boots in
  77. seconds and is **deleted** when it closes, which makes it the perfect "brand-new customer PC". Its supported `wsb`
  78. CLI provides automation; sandbox-mcp adds orchestrated app deployment, UI Automation, clean-machine checks and
  79. durable test evidence around it.
  80. | | sandbox-mcp (Windows Sandbox) | Hyper-V / VMware VM | Windows containers | Cloud dev VMs (devvm, Codespaces, Dev Box) |
  81. |------------------------------|-------------------------------------|----------------------------|------------------------------|--------------------------------------------|
  82. | Real Windows desktop + GUI | ✅ | ✅ | ❌ no desktop | Linux mostly / ✅ (Dev Box) |
  83. | Clean state every run | ✅ always, by design | snapshots to manage | ✅ | ❌ persistent |
  84. | Startup | ~15 s | minutes | seconds | minutes |
  85. | 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 |
  86. | Cost | free with Windows Pro/Enterprise | free-ish + disk | free | 💸 |
  87. | Runs offline / local | ✅ | ✅ | ✅ | ❌ |
  88. | Parallel instances | ❌ one at a time | ✅ | ✅ | ✅ |
  89. | Persistent environment | ❌ | ✅ | via volumes | ✅ |
  90. If you need many machines, persistence, or Linux, use a VM or a cloud box. If you want to know *"does my Windows app
  91. install, launch and work on a clean PC, and what does it look like?"* as quickly and cheaply as possible, this is it.
  92. ## What you can do
  93. `sbx deps <app.exe|folder>` (MCP: `sandbox_deps`) inspects dependencies on the host without running or installing
  94. anything: PE architecture/imports, app-local VC++ DLLs, .NET runtime configs, .NET Framework configs, package
  95. dependencies and script interpreters. `sbx run` includes this diagnosis in its report and names likely missing
  96. runtimes after a failed launch. This is a conservative static scan, not proof that every dynamic dependency is
  97. present. Optional guest components such as WebView2 must be checked in the actual guest.
  98. The default never installs dependencies. To **explicitly opt in**, use `sbx run <app> --provision auto`
  99. (`sandbox_run` parameter `provision: "auto"`), or specify a comma-separated list such as
  100. `--provision desktop:10.0:x64,vcredist:x64`. Supported components: `dotnet:<version>:<arch>`,
  101. `desktop:<version>:<arch>`, `aspnetcore:<version>:<arch>`, `vcredist:<arch>` and
  102. `windows-app-runtime:<major.minor>:<arch>`. Architecture is `x86`, `x64` or `arm64` (explicit lists default
  103. to x64). `sbx provision <host app path> --provision <auto|list>` / `sandbox_provision` does the same in
  104. an already-started sandbox; it never starts or adopts a guest. Unknown versions/architectures or unsupported
  105. auto-provision requests fail explicitly; Java and Python require application-specific setup.
  106. Downloads happen on the **host**, are cached under the sandbox-mcp home `cache\redistributables` folder,
  107. verified with published SHA-512 hashes for .NET and a valid Microsoft Authenticode signature for every
  108. installer, then copied in and installed silently. Guest networking can stay **off**. A cached installer
  109. is reverified before reuse; remove its specific cache file to refresh a mutable VC++/Windows App Runtime
  110. download. Reports record the requested provisioning, completed installs, source and verification details
  111. and say **PROVISIONED (not a clean-machine test)**. A provisioned pass never means the original clean machine
  112. had those runtimes. .NET resolution conservatively stays within the requested major/minor channel and
  113. honors exact-version requests (`rollForward: Disable` / `applyPatches: false`) rather than silently changing
  114. the app configuration. A reboot-required installer result fails the run.
  115. Step-by-step provisioning also writes `provisioning.json` in the run folder and marks `sbx status` /
  116. `sandbox_status`, so switching clients does not lose the non-clean-machine provenance. This records explicit
  117. provisioning only, not arbitrary installers a user runs with `exec`. For a live regression, publish a small
  118. framework-dependent .NET desktop app and run `node test\deps-offline.js <publish folder>` with exclusive use
  119. of Windows Sandbox. The observed optional-component baseline for build 26100.9882 is recorded in
  120. `test\fixtures\sandbox-26100.9882.json`; it is evidence for that build, not a promise about future guest images.
  121. - **Clean-machine smoke tests:** does the exe even start without the VC++ runtime / .NET runtime / WebView2 you
  122. forgot to bundle? `sbx run` tells you, with a screenshot and the crash events.
  123. - **Test installers and uninstallers:** `sbx install-test setup.msi` installs on a clean machine, uninstalls, and
  124. reports every file, registry key, service, scheduled task and autorun the installer added and the uninstaller
  125. forgot. Hung installers waiting on a hidden dialog get screenshotted instead of hanging your CI.
  126. - **Drive the UI with UI Automation, not pixels:** read the control tree (`Button "Save" #SaveButton {invoke}`),
  127. set text, click, toggle, select, wait for results. Works for WinForms, WPF, Win32 and WinUI apps, and things like
  128. File Explorer. Screenshots, mouse and keyboard are there for everything else.
  129. - **Let an agent close the loop:** "build it, test it on a clean machine, look at the screenshot, fix it, repeat",
  130. without the agent touching your real desktop.
  131. - **Run things with no network at all:** `--network off` boots the sandbox with no network adapter. Control still
  132. works (through a shared folder), so you can watch an app's offline behavior or open something you don't trust.
  133. - **See what a file you don't trust actually does:** `sbx detonate invoice.js` runs it in a sandbox with no network
  134. and reports every process it started (with command lines), the names it looked up, the addresses it tried, and the
  135. autoruns, scheduled tasks, services and files it planted. Then the whole machine is deleted.
  136. - **Collect evidence:** every run keeps screenshots, copied-out files, a markdown report and an audit log on the
  137. host after the sandbox is gone.
  138. ## Download and try it (no Node.js install)
  139. Download the **Windows x64 portable ZIP** from the [latest GitHub release](https://github.com/shanselman/sandbox-mcp/releases/latest)
  140. and extract it into its own folder. The standard ZIP bundles Node.js; releases that also offer a `-bun.zip` bundle
  141. the runtime into `sbx.exe`. **Either runtime ZIP is all you need**; the `-bun-relink-source.zip` is only for
  142. rebuilding or relinking. Both include the CLI, MCP server, guest agent and skills. You do not need to clone the repo,
  143. install Node, npm or Bun, or add anything to PATH. Keep the extracted files together and use `sbx.cmd` directly
  144. for CLI-only operation; you do not need an MCP client, server configuration or plugin. The packages are built and
  145. tested on native Windows x64; ARM64 is not currently packaged.
  146. Verify the ZIP against its adjacent `.sha256` file before extracting; the [agent setup guide](docs/agent-setup.md)
  147. does that automatically and preserves existing client configuration.
  148. Open PowerShell in the extracted folder and start with the read-only readiness check:
  149. ```powershell
  150. .\sbx.cmd doctor
  151. ```
  152. `doctor` explains what is missing and how to fix it. It never enables Windows features, elevates, changes PATH, or
  153. restarts the PC for you. Windows Sandbox is only available on Windows Pro, Enterprise or Education; Windows Home
  154. and Windows Server cannot run it.
  155. If the Sandbox feature is off, open **an administrator PowerShell**, run the command below, then restart Windows:
  156. ```powershell
  157. Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
  158. ```
  159. After restarting, open **Windows Sandbox from the Start menu once**, then close it. This updates Sandbox and installs
  160. the `wsb` command-line tool that `sbx` uses. Run the check again and try a built-in Windows app:
  161. ```powershell
  162. .\sbx.cmd doctor
  163. .\sbx.cmd run C:\Windows\System32\charmap.exe --open
  164. ```
  165. A passing run leaves `report.md`, `report.json`, screenshots and `audit.jsonl` under
  166. `%LOCALAPPDATA%\sandbox-mcp\runs\<timestamp>` (`out` contains the report and media), even after teardown.
  167. `--open` opens the report. Add `--record` for a self-contained viewer under
  168. `out\recordings\<recordingId>\recording.html` and MP4 when host ffmpeg is available. `SANDBOX_MCP_HOME`
  169. changes the artifact root. No ffmpeg or app runtime is silently installed.
  170. For an MCP client using the standard ZIP, configure its stdio server with the full paths to the bundled runtime and
  171. server. Replace the example folder with the location where you extracted the ZIP:
  172. ```json
  173. {
  174. "servers": {
  175. "windows-sandbox": {
  176. "type": "stdio",
  177. "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
  178. "args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"]
  179. }
  180. }
  181. }
  182. ```
  183. That is the VS Code `.vscode\mcp.json` shape. For GitHub Copilot CLI's
  184. `%USERPROFILE%\.copilot\mcp-config.json`, use:
  185. ```json
  186. {
  187. "mcpServers": {
  188. "windows-sandbox": {
  189. "type": "local",
  190. "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
  191. "args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"],
  192. "tools": ["*"]
  193. }
  194. }
  195. }
  196. ```
  197. For the Bun ZIP, replace the `command` and `args` in either example with:
  198. ```json
  199. {
  200. "command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\sbx.exe",
  201. "args": ["mcp"]
  202. }
  203. ```
  204. For Claude Desktop, use `"mcpServers"` with the same command/args and omit `type` and `tools`.
  205. Restart or reload the client's server configuration, then ask it to run Character Map in a fresh offline Sandbox
  206. and return the report and screenshot. The server writes logs to stderr; stdout is reserved for MCP messages.
  207. ## Turn on Windows Sandbox
  208. If you have Windows Pro, Enterprise or Education, you already own one of the best tools in Windows and it's probably
  209. switched off. [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview)
  210. is a whole, real Windows desktop that:
  211. - **comes with Windows:** nothing to download, no VHD, no license key. It's built from the Windows you're running.
  212. - **is brand new every time:** it boots as clean as the day Windows was installed, in about 15 seconds.
  213. - **is thrown away when you close it:** guest files, registry keys and installed apps are deleted.
  214. Explicitly shared output folders remain on the host as test evidence.
  215. - **is properly isolated:** it runs on its own kernel behind the Microsoft hypervisor (the same hardware
  216. virtualization as Hyper-V), not just a separate user account.
  217. - **is light:** it shares memory and files with your PC where it safely can, and uses your GPU.
  218. Turn it on with one line in an **admin** PowerShell, then restart:
  219. ```powershell
  220. Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
  221. ```
  222. (Or *Turn Windows features on or off* > tick *Windows Sandbox*.) After the restart, **open Windows Sandbox from the
  223. Start menu once**. That updates it to the Store version, which includes the `wsb` command-line tool this project
  224. drives. Then check everything with:
  225. ```powershell
  226. sbx doctor
  227. ```
  228. ```text
  229. ✅ Windows 11 Pro, build 26100
  230. ✅ Windows Sandbox feature is on
  231. ✅ Virtualization is on
  232. ✅ wsb command-line tool: C:\Users\you\AppData\Local\Microsoft\WindowsApps\wsb.exe (Windows Sandbox 0.8.107.0)
  233. ✅ Node.js 22.11.0
  234. Ready. Try: sbx run C:\Windows\System32\charmap.exe --open
  235. ```
  236. If something's missing, `sbx doctor` says what and how to fix it, and every other command tells you the same thing
  237. if it can't reach Windows Sandbox. The full list of what you need:
  238. - Windows 11 24H2 (build 26100) or later, Pro / Enterprise / Education. Windows Sandbox isn't available on Home or Windows Server.
  239. - Virtualization turned on in your PC's UEFI/BIOS (Intel VT-x or AMD-V). Most PCs ship with it on.
  240. - At least 4 GB of RAM (8 GB recommended), 2 CPU cores and 1 GB of free disk.
  241. - Running inside a VM? Turn on nested virtualization on the host first:
  242. `Set-VMProcessor -VMName <name> -ExposeVirtualizationExtensions $true`.
  243. - Either portable ZIP includes its runtime for Windows x64. If installing from source, use Node.js 20+ (`winget install OpenJS.NodeJS.LTS`).
  244. ## Install from source
  245. The clone command below retrieves the public default branch. Check out `v1.2.0` to reproduce that release's
  246. source and WinUI/WPF samples exactly. Samples are not included in the portable ZIP.
  247. ```powershell
  248. git clone https://github.com/shanselman/sandbox-mcp
  249. cd sandbox-mcp
  250. npm ci --omit=dev
  251. npm link # puts `sbx` and `sandbox-mcp` on your PATH (or use `node src/cli.js`)
  252. sbx doctor # is Windows Sandbox ready? (see above)
  253. sbx run C:\Windows\System32\charmap.exe --open # try it on something that exists everywhere
  254. ```
  255. Try the included sample (needs nothing but Windows; it compiles with the .NET Framework's `csc.exe`):
  256. ```powershell
  257. .\samples\HelloSandbox\build.ps1
  258. sbx run .\samples\HelloSandbox\bin --test .\samples\HelloSandbox\test.ps1 # passes
  259. sbx run .\samples\HelloSandbox\bin --args --crash # fails, and shows the crash
  260. sbx install-test .\samples\LeakyApp\install.ps1 # an installer whose uninstaller forgets things
  261. sbx detonate .\samples\Suspicious\suspicious.ps1 # a harmless script that acts like malware
  262. ```
  263. ### Use it from an agent (optional MCP)
  264. The `sbx` CLI is fully usable without an MCP server. If your agent can run shell commands, use `sbx` (or
  265. `.\sbx.cmd` from the portable ZIP) directly. Configure the MCP adapter only when the client benefits from
  266. discoverable tool schemas, structured tool results and inline screenshot images.
  267. For source installs, use the same client-specific shapes above, replacing the bundled command with your
  268. installed Node executable. For example, VS Code (`.vscode\mcp.json`):
  269. ```json
  270. {
  271. "servers": {
  272. "windows-sandbox": {
  273. "type": "stdio",
  274. "command": "node",
  275. "args": ["C:\\path\\to\\sandbox-mcp\\src\\server.js"]
  276. }
  277. }
  278. }
  279. ```
  280. Use the Copilot CLI or Claude shape above for those clients; their top-level keys differ from VS Code.
  281. An absolute Node path avoids differences between your terminal PATH and the MCP client's environment.
  282. Then ask: *"Build the app, run it in a fresh Windows Sandbox, type my name in the box, click Greet and show me a
  283. screenshot."*
  284. There are also agent skills in [`skills/`](skills) that teach agents each workflow: setup, clean-machine runs,
  285. interactive UI testing, installer testing and detonating untrusted files. Copy the ones you want into your agent's
  286. skills folder (for example `~/.copilot/skills/`), or install the plugin below to get them all with the optional MCP adapter.
  287. ### Install the agent plugin
  288. The [agent plugin](docs/agent-plugin.md) bundles the MCP adapter and skills, so you don't need to clone anything
  289. or edit MCP configuration. It needs Node.js 20 or later. The plugin is optional if you use the CLI directly.
  290. With GitHub Copilot CLI:
  291. ```powershell
  292. copilot plugin marketplace add shanselman/sandbox-mcp
  293. copilot plugin install sandbox-mcp@sandbox-mcp
  294. ```
  295. In VS Code, add `shanselman/sandbox-mcp` as a marketplace in **Chat: Open Customizations**, or run
  296. **Chat: Install Plugin from Source**. See the [plugin guide](docs/agent-plugin.md) for details.
  297. ## Fast inner loop
  298. Start once, then build and deploy repeatedly into that **warm** sandbox (any framework, no guest prerequisites
  299. installed implicitly):
  300. ```powershell
  301. sbx start --network off
  302. powershell -File .\samples\HelloSandbox\build.ps1
  303. sbx deploy .\samples\HelloSandbox\bin C:\apps\HelloSandbox --launch HelloSandbox.exe --restart
  304. sbx shot --window "Hello Sandbox"
  305. # Edit, build, deploy --restart, screenshot again; when done:
  306. sbx stop
  307. ```
  308. `deploy` transfers only added/changed files through a fresh shared staging folder, removes deleted files, and verifies
  309. the entire destination using SHA256. Its report includes added/changed/removed/unchanged counts, bytes transferred,
  310. elapsed milliseconds and `verified: true`. `--restart` stops processes whose executable is under the destination before
  311. applying and requires `--launch` to relaunch the app; `--launch` alone launches after verification. Arguments use
  312. `--args "..."`. TCP and network-off shared-folder transport both work.
  313. Use a dedicated destination: **extra guest files there are deleted**. Links, junctions and reparse points are rejected.
  314. If a build changes while staging, deployment fails with `build output changed during deploy; rerun` before touching the
  315. destination. Apply/verification failures restore the previous touched files where possible; rollback failures explicitly
  316. identify the retained guest backup. Stopped processes are not automatically restarted after a failed apply.
  317. `push` / `sandbox_copy_in` still perform a full replacement. `run`, `install-test` and `detonate` still start fresh;
  318. incremental deployment never adopts an unrelated sandbox.
  319. ## One engine, two interfaces
  320. The `sbx` CLI and MCP server are two interfaces to the same implementation: both import and use `src/core.js`,
  321. and the higher-level run, installer and detonation workflows are shared too. The CLI is the complete standalone
  322. interface; MCP is an optional adapter for agents that benefit from discoverable tool schemas, structured results
  323. and inline screenshot images. They are not separate engines, and their names or output formats are not meant to
  324. be identical.
  325. For example, both forms run Character Map on a fresh offline guest, capture evidence and destroy the guest:
  326. ```powershell
  327. sbx run C:\Windows\System32\charmap.exe --network off
  328. ```
  329. Or call MCP tool `sandbox_run` with these arguments:
  330. ```json
  331. {
  332. "app": "C:\\Windows\\System32\\charmap.exe",
  333. "network": "off"
  334. }
  335. ```
  336. The supported workflows map across the interfaces:
  337. | Workflow | CLI | MCP adapter |
  338. |---|---|---|
  339. | Fresh app test | `sbx run` | `sandbox_run` |
  340. | Guest lifecycle and shared state | `sbx start`, `status`, `stop`, `desktop-release` | `sandbox_start`, `sandbox_status`, `sandbox_stop`, `sandbox_desktop_release` |
  341. | 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` |
  342. | 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` |
  343. | Recording | `sbx record start`, `record stop` | `sandbox_record_start`, `sandbox_record_stop` |
  344. | Dependencies and provisioning | `sbx deps`, `provision` | `sandbox_deps`, `sandbox_provision` |
  345. | Installer and untrusted-file tests | `sbx install-test`, `detonate` | `sandbox_install_test`, `sandbox_detonate` |
  346. | System snapshots | `sbx snapshot`, `diff` | `sandbox_snapshot`, `sandbox_diff` |
  347. Use the CLI's human-readable output and process exit codes in a shell; add `--json` for machine-readable output.
  348. The MCP adapter presents schemas and structured results to compatible clients and can return screenshots inline.
  349. ## MCP tools
  350. | Tool | What it does |
  351. |---|---|
  352. | `sandbox_deps` | Host-only conservative dependency diagnosis; does not execute or install the app. |
  353. | `sandbox_provision` | Explicit opt-in verified runtime installation into the current owned guest; persists non-clean provenance. |
  354. | `sandbox_run` | The whole loop in one call: boot, copy/install, launch or run, observe, test script, collect, destroy, report. |
  355. | `sandbox_start` | Boot a fresh sandbox (`network`: on / firewall / off, `memoryMB`, `vGpu`). Waits for the agent and an interactive desktop; reports readiness timings. |
  356. | `sandbox_status` | Is one running, its id/IP/network mode, agent health and current interactive-desktop facts. |
  357. | `sandbox_desktop_release` | End this workflow's desktop turn immediately. |
  358. | `sandbox_stop` | Destroy it. Lists the artifacts left on the host. |
  359. | `sandbox_copy_in` | Copy a host file or folder in (default `C:\apps\<name>`). |
  360. | `sandbox_deploy` | Deploy a host directory into an already running sandbox, transfer only changes and verify hashes; optional launch/restart. |
  361. | `sandbox_copy_out` | Copy a sandbox file or folder out to the run's `out\files`. |
  362. | `sandbox_exec` | Run a PowerShell (or `cmd`) command; returns stdout, stderr, exit code. |
  363. | `sandbox_launch` | Start an EXE or installed package AUMID; returns the app pid and main window. |
  364. | `sandbox_process` | Running? Exit code? Window title? |
  365. | `sandbox_windows` | Visible top-level windows with titles, pids and bounds. |
  366. | `sandbox_screenshot` | PNG of the desktop or one window, returned inline (and saved on the host), with its own `captureId`, bounds and scale. |
  367. | `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. |
  368. | `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. |
  369. | `sandbox_ui_tree` | The UI Automation tree of a window: type, name, automation id, value, state, supported actions. |
  370. | `sandbox_ui_action` | Find a control by name / automation id / type and click, set a value, toggle, select, expand, read... |
  371. | `sandbox_ui_wait` | Wait for a control (a result, a dialog) to appear. |
  372. | `sandbox_app_errors` | Application event log errors: crashes, hangs, .NET unhandled exceptions. |
  373. | `sandbox_install_test` | The installer loop in one call: snapshot, install, snapshot, optional test, uninstall, snapshot, report what was added and left behind. |
  374. | `sandbox_detonate` | Run an untrusted file (no network by default) and report its processes, lookups, connections, persistence and changes. |
  375. | `sandbox_snapshot` | Record files, registry, services, autoruns and installed programs under a name. |
  376. | `sandbox_diff` | Compare two snapshots: what changed in between. |
  377. ## CLI
  378. ```text
  379. sbx run <app.exe|folder|app.msix> [--exe <name>] [--args "<args>"] [--console] [--wait <sec>]
  380. [--cert <file.cer>] [--deps <folder>] [--app-id <id>]
  381. [--record] [--provision <auto|list>]
  382. [--test <script.ps1>] [--collect <sandbox path>]... [--keep] [--open]
  383. sbx install-test <setup.msi|.exe|.ps1|.cmd> [--args "/S"] [--uninstall auto|none|"<cmd>"]
  384. [--uninstall-args "/S"] [--test <script.ps1>] [--fail-on-leftovers] [--exclude <path>]...
  385. sbx detonate <file> [--args "<args>"] [--network off|firewall|on] [--duration <sec>] [--full] [--every <sec>]
  386. sbx start [--network on|firewall|off] [--memory <MB>] [--no-gpu] [--minimized]
  387. sbx deps <host app path> sbx provision <host app path> --provision <auto|list>
  388. sbx desktop-release
  389. sbx push <host path> [sandbox path] sbx pull <sandbox path> [name]
  390. sbx deploy <hostDir> [guestDir] [--launch <exe>] [--args "..."] [--restart]
  391. sbx exec [--cmd] [--cwd <dir>] <command...> sbx launch <exe|PackageFamilyName!AppId> [--args "..."]
  392. sbx shot [--window <title>|--pid <pid>] sbx windows sbx proc <pid>
  393. sbx record start [--fps 2 --duration 120] sbx record stop
  394. sbx ui [tree] [--pid <pid>] sbx ui click --name Save
  395. sbx ui set --id NameBox --value Scott sbx ui wait --name "Saved" --timeout 10
  396. sbx snapshot <name> [--exclude <path>]... sbx diff <from> <to>
  397. sbx click <x> <y> sbx type "text" [--keys] sbx errors sbx status sbx stop
  398. sbx doctor # can this PC run Windows Sandbox? how to fix it if not
  399. sbx mcp # run the MCP server
  400. ```
  401. `exec` treats the command and everything after it as raw guest input. Put CLI options first:
  402. `sbx exec --json --timeout 30 'Get-Date'`, not `sbx exec 'Get-Date' --json`.
  403. Add `--json` to any command for machine-readable output. `sbx exec` and `sbx run` exit with meaningful codes, so they
  404. drop straight into scripts. `sbx help` has the details.
  405. CLI and MCP processes share locked, atomically written state, including copy and mailbox sequence numbers.
  406. Desktop-changing operations (launch, click, type, UI actions and window-focusing screenshots) take cooperative
  407. FIFO turns; observing windows, UI trees, processes, status and executing commands does not reserve the desktop.
  408. An MCP instance retains its turn for four idle seconds. Set `SANDBOX_MCP_WORKFLOW` to the same identifier across
  409. CLI commands to retain a multi-command turn too; anonymous CLI commands release immediately. End a turn with
  410. `sbx desktop-release` or `sandbox_desktop_release`. A contender waits at most 60 seconds, then reports
  411. `desktop busy: held by <owner>`. These are cooperative turns, not isolation: `exec` can itself start GUI programs.
  412. Each boot has an epoch and a verified agent identity (protocol version, agent version and SHA256 of staged
  413. agent files), included in `status --json`. A stale boot or incompatible protocol is refused: start a new sandbox.
  414. Both TCP and offline mailbox messages use directional HKDF-SHA256 keys, AES-256-CBC encryption and
  415. HMAC-SHA256 authentication with counters, random IVs and timestamp/replay checks. The random transport key
  416. stays in the read-only agent share, never in `current.json`, command-line arguments or request/response messages.
  417. This protects the transport, not against an administrator inside the guest: code there can read its agent share.
  418. ## Packaged apps (MSIX and Appx)
  419. `sbx run` also accepts `.msix`, `.msixbundle`, `.appx` and `.appxbundle`. It copies the package into a
  420. **fresh** guest, installs it with `Add-AppxPackage`, resolves its manifest Application Id, and activates the
  421. installed AUMID. Screenshots, UI Automation, crash checks, test scripts and reports use the actual app process,
  422. not the short-lived shell launcher.
  423. ```powershell
  424. sbx run .\build\MyApp.msix --cert .\build\devcert.cer --network off --test .\smoke.ps1
  425. sbx run .\build\MyApp.msixbundle --deps .\build\Dependencies\x64 --app-id App --network off
  426. # Inside an already-running sbx session, activate an installed package:
  427. sbx launch 'MyApp_0123456789abc!App'
  428. ```
  429. `--cert` explicitly trusts a public `.cer` in **the guest's** `LocalMachine\TrustedPeople` store; it never
  430. installs a certificate on the host. Store-signed/trusted packages do not need it. Provide offline framework
  431. packages in an adjacent `deps` folder, or choose another folder with `--deps`; every package in that folder is
  432. passed as a `DependencyPath`. Nothing is downloaded or preinstalled automatically. Select `--app-id` when
  433. a manifest contains more than one application. Deployment failures include Windows' error and activity log
  434. when available. Package activation is GUI mode, not `--console`.
  435. The equivalent `sandbox_run` inputs are `app`, `cert`, `deps` and `appId`. `sandbox_launch` accepts `aumid`
  436. instead of `path`, and the CLI also recognizes `shell:AppsFolder\PackageFamilyName!ApplicationId`.
  437. Tests receive `$env:SBX_APP_AUMID` as well as the usual process/executable paths. Installed package directories
  438. are read-only: write test output to `$env:SBX_OUT` or an app-data directory, not `$env:SBX_APP_DIR`.
  439. ## Recording and capture coordinates
  440. For visual evidence across an entire session, use `sbx run <app> --record` (MCP: `sandbox_run` with
  441. `record: true`), or `sbx record start` / `sbx record stop` for interactive work. Recording runs in a separate
  442. guest process, including while a long command is running. Defaults: 2 fps, 120 seconds; hard limits:
  443. 5 fps, 300 seconds, 600 frames. `--max-frames` sets a smaller frame budget. Frames (up to 1280 pixels wide)
  444. and append-only `frames.jsonl` metadata go directly to `out\recordings\<id>`; partial evidence survives
  445. a guest crash or timeout. Stop publishes `recording.html` with embedded images and playback controls,
  446. plus `recording.mp4` when ffmpeg is already on the host PATH. No guest installation or network is needed.
  447. MP4 uses the requested frame rate; the HTML player preserves captured timestamps. Neither format includes audio.
  448. The run report links the artifacts. `sbx stop` also publishes any tracked recording before destroying the guest.
  449. Only one recording can be reserved across CLI/MCP clients. Tracking is bound to the boot epoch and recording ID;
  450. failed publication retains recovery metadata so `sbx record stop` can retry without touching a replacement guest.
  451. Rejected starts release a zero-frame reservation only after confirming that its recorder cannot still be active;
  452. uncertain starts retain tracking and report the error explicitly.
  453. Guest-returned screenshot filenames are checked as confined PNG leaf paths before host reads or cleanup.
  454. After a guest crash or abrupt MCP disconnect, `sbx record stop` can still publish the preserved partial evidence,
  455. even if `sbx status` already noticed the guest is gone. Truncated final recorder status is reported as partial,
  456. not allowed to hide otherwise valid frames; malformed frame metadata is still rejected.
  457. Start verifies the Default input desktop, explorer shell, screen size and a successful capture before declaring
  458. ready. Screenshot, click, type and UI actions reject locked/secure desktops (including UAC) explicitly.
  459. Screenshot coordinates are pixels in the returned preview, not the full-resolution saved PNG.
  460. MCP clicks default to the latest screenshot; use `captureId` to select an earlier image. CLI clicks still default
  461. to raw screen pixels: use `--coordinates screenshot --capture-id <id>` for a preview. Captured windows that
  462. move, resize, minimize or close must be captured again before clicking.
  463. ## Test scripts
  464. `sbx run --test smoke.ps1` (or `sandbox_run` with `test`) runs your script **inside** the sandbox after the app
  465. starts, with:
  466. - `$env:SBX_APP_PID`, `$env:SBX_APP_DIR`, `$env:SBX_OUT` (anything you write to `SBX_OUT` comes back to the host),
  467. - these commands already imported:
  468. ```powershell
  469. Get-SbxUiTree [-ProcessId <pid>] [-WindowTitle <title>] [-Depth <n>] # objects: type, name, automationId, value, actions...
  470. Invoke-SbxUi -Action <click|setvalue|toggle|select|expand|read|...> [-Name <text>] [-AutomationId <id>]
  471. [-ControlType <Button|Edit|...>] [-Index <n>] [-Value <text>] [-ProcessId <pid>]
  472. Wait-SbxUi [-Name <text>] [-AutomationId <id>] [-ControlType <type>] [-TimeoutSec <n>] [-ProcessId <pid>]
  473. ```
  474. Throw, or exit non-zero, to fail the run. Example ([samples/HelloSandbox/test.ps1](samples/HelloSandbox/test.ps1)):
  475. ```powershell
  476. $app = [int]$env:SBX_APP_PID
  477. Invoke-SbxUi -ProcessId $app -AutomationId NameBox -Action setvalue -Value 'Sandbox'
  478. Invoke-SbxUi -ProcessId $app -Name Greet -Action click
  479. Wait-SbxUi -ProcessId $app -Name 'Hello, Sandbox!' -TimeoutSec 5 | Out-Null
  480. ```
  481. ## Installer testing
  482. Installers are the part of an app that only ever runs on clean machines, so they're the part you test least.
  483. `sbx install-test` takes a system snapshot of a fresh sandbox, runs your installer silently, snapshots again,
  484. uninstalls it the way Add/Remove Programs would, snapshots a third time and diffs them:
  485. ```text
  486. > sbx install-test .\7z2501-x64.msi --offline
  487. PASS 7z2501-x64.msi on a fresh Windows Sandbox (117.5s)
  488. install exit 0 in 2.5s
  489. added 7-Zip 25.01 (x64 edition); 111 files, 18 registry keys, 0 services, 0 autorun/env values
  490. uninstall 7-Zip 25.01 (x64 edition): exit 0 in 2.3s
  491. leftovers none, clean uninstall
  492. ```
  493. The report lists what was added (here: `C:\Program Files\7-Zip`, the Start menu folder, the shell extension
  494. CLSIDs and context-menu handlers, App Paths and the uninstall entry) and what's **left behind**. Try the included
  495. deliberately sloppy installer, whose uninstaller only deletes its program folder:
  496. ```text
  497. > sbx install-test .\samples\LeakyApp\install.ps1
  498. ## Left behind after uninstall
  499. Services: added service LeakyUpdater "Leaky App Updater", automatic: "C:\Program Files\LeakyApp\updater.exe"
  500. Autoruns: added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\LeakyUpdater
  501. Files: C:\ProgramData\LeakyApp\ C:\Users\WDAGUtilityAccount\AppData\Roaming\LeakyApp\
  502. C:\Windows\System32\Tasks\LeakyApp Daily Check
  503. Registry: HKLM\SOFTWARE\LeakyApp
  504. ```
  505. - `.msi` files get `msiexec /i /qn /norestart` with a verbose log (brought back, with its errors in the report).
  506. For `.exe` installers pass the silent switch: `--args /S` (NSIS), `/VERYSILENT` (Inno), `--silent` (Squirrel).
  507. - The uninstall uses what the installer registered: `msiexec /x {ProductCode}`, else `QuietUninstallString`, else
  508. `UninstallString` plus `--uninstall-args`. The run fails if the program is still in Add/Remove Programs afterwards.
  509. - An installer that doesn't exit within `--timeout` is screenshotted (and its new windows' UI Automation tree
  510. recorded) before it's killed. That's usually a "silent" install that's waiting for someone to click a dialog.
  511. - Processes the installer leaves running (tray apps, updaters) are listed and stopped before uninstalling.
  512. - `--test smoke.ps1` runs between install and uninstall with `$env:SBX_INSTALL_DIR` and `$env:SBX_PROGRAM`.
  513. - `--fail-on-leftovers` turns leftovers into a failure, for CI.
  514. - The snapshots skip the things Windows changes on its own (caches, telemetry, Defender, Windows Update, Start menu
  515. and Explorer bookkeeping, Windows Installer's internal database), so a 30-second idle sandbox diffs to "No changes".
  516. `--exclude` adds more.
  517. The same snapshots are available step by step: `sbx snapshot before`, do anything, `sbx snapshot after`,
  518. `sbx diff before after` (or the `sandbox_snapshot` / `sandbox_diff` tools).
  519. ## Detonate: what does this file actually do?
  520. Someone sent you `invoice.js`, a "driver update", a script from a forum. `sbx detonate` runs it the way a
  521. double-click would, in a fresh sandbox with **no network adapter**, with Windows' own auditing switched on, and
  522. tells you what it did:
  523. ```text
  524. > sbx detonate .\samples\Suspicious\suspicious.ps1 --network firewall
  525. suspicious.ps1: 3 red flag(s) (watched 40s, network firewall)
  526. findings 🔴 starts itself with Windows: added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ContosoUpdater =
  527. powershell.exe -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\Users\...\ContosoUpdater\updater.ps1"
  528. 🔴 created a scheduled task: ContosoUpdate
  529. 🔴 put something in a Startup folder: C:\Users\...\Start Menu\Programs\Startup\contoso.cmd
  530. 🟠 wrote 2 runnable file(s): C:\Users\...\ContosoUpdater\updater.ps1, ...\Startup\contoso.cmd
  531. 🟠 ran built-in Windows tools that malware often uses: schtasks.exe, whoami.exe, ipconfig.exe, net.exe, net1.exe
  532. 🟠 looked up 1 internet name(s): c2.contoso-updates.example
  533. 🟠 tried to connect to 2 address(es): 198.51.100.7:4444, 203.0.113.10:80
  534. processes 7 (powershell.exe → conhost.exe → schtasks.exe → whoami.exe → ipconfig.exe …)
  535. network 1 name lookup(s), 2 connection attempt(s)
  536. changed 4 files added, 0 changed, 2 registry keys, 1 autorun/env values, 0 services
  537. ```
  538. ([samples/Suspicious/suspicious.ps1](samples/Suspicious/suspicious.ps1) is harmless; it just behaves like
  539. something that isn't.) The report also has a timeline:
  540. ```text
  541. +0.0s start powershell.exe (pid 8180) ... -File "C:\Users\WDAGUtilityAccount\Downloads\suspicious.ps1"
  542. +1.5s start schtasks.exe (pid 7848) /Create /F /TN ContosoUpdate /SC ONLOGON /TR "powershell.exe -WindowStyle Hidden ..."
  543. +1.6s start whoami.exe (pid 7616) /all
  544. +1.7s start net.exe (pid 9064) user
  545. +1.7s start net1.exe (pid 8096) C:\Windows\system32\net1 user
  546. +15.0s lookup c2.contoso-updates.example (failed)
  547. +15.1s connect 203.0.113.10:80/TCP blocked (powershell.exe)
  548. +15.2s connect 198.51.100.7:4444/TCP blocked (powershell.exe)
  549. ```
  550. plus the process tree, a before/after diff of files, registry, services and autoruns, the windows it opened,
  551. screenshots, and "everything else that happened" (usually Windows itself, kept separate rather than hidden).
  552. - **How:** process creation auditing with command lines (Security 4688), Windows Filtering Platform connection
  553. auditing (5156/5157) and the DNS client log, collected from inside the guest, plus the same snapshots as
  554. `install-test`. Activity is attributed to the file's own process tree, so the agent's own work isn't mixed in.
  555. - **Network:** `off` (default) has no adapter at all. Name lookups are still recorded, but nothing leaves the
  556. machine. `--network firewall` also shows the IP addresses and ports it tries, blocked by the guest firewall.
  557. `on` gives it the internet; only use that for things you're prepared to let talk to the world.
  558. - **Runs:** `.exe`, `.msi` (silently), `.ps1`, `.cmd`, `.bat`, `.js`/`.jse`/`.vbs`/`.vbe`/`.wsf` (with `wscript`) and
  559. `.hta` (with `mshta`), from the user's Downloads folder.
  560. - **Watching:** up to `--duration` seconds (60), stopping early once everything it started has exited, unless
  561. `--full`. A screenshot every `--every` seconds (15).
  562. - **Collection health:** if process/connection audit setup or DNS log setup fails, the file is not launched.
  563. If an event log cannot be read, the run reports a collection error rather than treating it as no activity.
  564. A successful query with no matching events still produces an empty activity list.
  565. - **Findings are heuristics, not a verdict.** Installers add autoruns and services too. Exit code 0 means "it was
  566. observed", not "it's safe". This is a quick first look on your own PC, not a malware lab: something that checks
  567. whether it's in a sandbox can just behave nicely.
  568. ## Network modes
  569. | Mode | How | Use it for |
  570. |---|---|---|
  571. | `on` (default) | Normal NAT networking. | Apps that need the internet, downloading prerequisites. |
  572. | `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. |
  573. | `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. |
  574. In `firewall` and `off` mode, sandbox-mcp also switches off Smart App Control in the guest. It ships in evaluation
  575. mode and asks the cloud about every new exe and msi; with no internet each of those lookups hangs for about two
  576. minutes (a 2 MB MSI took 125 s to install instead of 1 s).
  577. ## Security notes
  578. - Each sandbox is a separate Hyper-V-isolated kernel. It's thrown away on stop, together with everything that ran in it.
  579. - Hardened defaults: clipboard, printer, microphone and camera redirection are off, and *Protected Client* mode is on.
  580. - The host shares exactly three folders: the guest agent (read-only), a staging folder for files you copy in
  581. (read-only) and an output folder (read-write). Nothing else from your disk is visible.
  582. - The control channel needs a random per-sandbox token. In `on`/`firewall` mode it's TCP to the sandbox's private
  583. NAT address; in `off` mode it's the shared folder.
  584. - `SANDBOX_MCP_ALLOWED_ROOTS` limits which host folders can be copied in (handy when an agent is driving).
  585. - Every operation is appended to `audit.jsonl` in the run folder.
  586. - When the MCP client disconnects, only the boot it started is destroyed, unless `SANDBOX_MCP_KEEP_ON_EXIT=1`.
  587. A client joining a CLI-started guest does not own it. An idle watchdog shuts the guest down after 30 minutes
  588. with no calls.
  589. - With `network: on` the guest has internet access like any other machine on your network's NAT. Use `off` for
  590. anything you don't trust.
  591. - The `out` folder is writable from inside the sandbox, so treat what comes back (screenshots, pulled files, logs)
  592. as untrusted, especially after `detonate`. sandbox-mcp reads data from it but never runs anything from it.
  593. - Windows Sandbox is strong isolation, but not a guarantee: a hypervisor or Windows Sandbox escape would be a
  594. zero-day. For real malware analysis use a dedicated, disposable analysis machine.
  595. ## Configuration
  596. | Environment variable | Default | |
  597. |---|---|---|
  598. | `SANDBOX_MCP_HOME` | `%LOCALAPPDATA%\sandbox-mcp` | Where runs, screenshots and reports are kept. |
  599. | `SANDBOX_MCP_ALLOWED_ROOTS` | (any) | `;`-separated host folders that may be copied into the sandbox. |
  600. | `SANDBOX_MCP_IDLE_MINUTES` | `30` | Guest shuts itself down after this long with no calls. `0` disables. |
  601. | `SANDBOX_MCP_KEEP_ON_EXIT` | (unset) | Set to `1` to leave the sandbox running when the MCP client disconnects. |
  602. ## How it works
  603. Since Windows 11 24H2 the Store version of Windows Sandbox ships the supported `wsb.exe` CLI
  604. (`start / stop / list / ip / exec / share / connect`), but `wsb exec` returns only an exit code: no output, no
  605. screenshots, no UI. So:
  606. 1. The host creates a run folder and calls `wsb start` with a hardened config (and `<Networking>Disable` in `off` mode).
  607. 2. It shares the guest agent folder and starts [`agent/agent.ps1`](agent/agent.ps1) inside with `wsb exec`, in the
  608. interactive user session (it needs a desktop for windows and screenshots).
  609. 3. The agent is a small PowerShell server: exec with real output, file copy, process launch, screenshots, mouse and
  610. keyboard, window list, event log, and UI Automation through [`agent/uia.cs`](agent/uia.cs). That uses *native* UI
  611. Automation (the managed `System.Windows.Automation` can't see inside WinForms apps), with an interop assembly
  612. generated on the fly from the OS type library, so nothing needs installing.
  613. 4. With the network on, the host talks to it over TCP. In `off` mode it uses a mailbox in the shared folders.
  614. (The guest caches "file not found" for ~5 s, so the host bumps a sequence file the guest polls, bringing a round
  615. trip from 5 s down to ~100 ms.)
  616. 5. `wsb stop` destroys the VM. The run folder stays on the host.
  617. ## Limits
  618. - **One sandbox at a time.** That's a Windows Sandbox rule. `sbx run` calls queue nothing; they fail fast if one is running.
  619. - Every boot is pristine. Bundle app-local prerequisites or explicitly opt in to provisioning for each fresh guest;
  620. automatic runtime installation is never the default.
  621. - No Microsoft Store apps, winget, Notepad, Calculator or Windows Terminal inside. Windows PowerShell 5.1 and
  622. .NET Framework 4.8 are there.
  623. - The first UI Automation call in a sandbox takes ~4 s (it generates the interop); later calls are fast.
  624. - A system snapshot takes 10-20 s (about 11k files, 340k registry keys, 700 services), so `install-test` takes
  625. roughly two minutes plus your installer's own time.
  626. - The guest desktop gets a plain background so screenshots stay around 100 KB instead of 16 MB.
  627. - Needs a logged-in Windows session on the host (Windows Sandbox is a desktop feature).
  628. ## Verifying changes locally
  629. `npm test` checks the host logic and parses/compiles the guest PowerShell and C# helpers without booting a guest.
  630. Real desktop verification requires this Windows host's single Sandbox slot; coordinate with other users first
  631. and never stop somebody else's guest.
  632. ```powershell
  633. $env:SANDBOX_MCP_HOME = Join-Path $PWD 'work\integration'
  634. node test\integration.js off
  635. node test\integration.js on
  636. node test\integration.js firewall
  637. node test\evidence.js
  638. npm run package:win
  639. node test\package-smoke.js dist\sandbox-mcp-win-x64-v1.2.0.zip
  640. ```
  641. The integration harness drives the actual MCP stdio server and CLI against the same fresh guest, verifies UIA,
  642. copies evidence back, and fails if its guest cannot be torn down. JSON results are saved beneath
  643. `$env:SANDBOX_MCP_HOME\integration`. The package smoke test extracts the ZIP, removes host Node from PATH, checks
  644. CLI/MCP initialization and command surfaces, and compares every shipped source, agent and skill file with the
  645. working tree. It does not boot a Sandbox and is not a substitute for the live tests.
  646. `node test\agent-setup.js --download` follows the stable-download checksum/doctor instructions in a temporary
  647. home, tests all three JSON client destinations on PowerShell 5.1/7, checks native `copilot mcp add` with isolated
  648. `COPILOT_HOME`, and requires an actual MCP `sandbox_status` response. It needs the installed Copilot CLI for
  649. the native-command check. Use `--portable=<extracted-path>` for an already downloaded package, or `--candidate`
  650. to exercise the explicitly optional developer-preview discovery instructions.
  651. For a live extracted-package check, run the integration harness with the extracted `node.exe` and set
  652. `SANDBOX_MCP_TEST_ROOT` to the extracted folder. `SANDBOX_MCP_TEST_SHA` records the source commit when Git is not on
  653. the isolated PATH. Set `SANDBOX_MCP_EXPECT_NO_HOST_NODE=1` to require both the bundled runtime and no `node` on PATH;
  654. keep Windows system directories and the WindowsApps `wsb.exe` alias on PATH.
  655. ## Related projects
  656. - [fmuecke/windows-sandbox-mcp](https://github.com/fmuecke/windows-sandbox-mcp) is another MCP server for Windows
  657. Sandbox, focused on running agent-generated code safely and with `Networking Disable` by default. Its ideas
  658. (true offline by default, stop on disconnect, an idle watchdog, an audit log, allowed folders) shaped this
  659. project. sandbox-mcp leans the other way: testing *your* app on a clean machine, with UI Automation, screenshots
  660. and one-shot reports.
  661. - [devvm.dev](https://devvm.dev/): disposable cloud dev machines for agents. The inspiration for "just give the agent a fresh box".
  662. ## License
  663. [MIT](LICENSE)
src/detonate.js · Bundled script · 337 lines · 1 finding marked
  1. // "What does this file actually do when I run it?" Boot a fresh sandbox (no network adapter by default), turn on
  2. // Windows' own auditing, run the file, watch it, then report every process it started (with command lines), the
  3. // names it looked up, the connections it tried, what it changed on disk and in the registry (autoruns, services,
  4. // scheduled tasks, dropped executables) and what was on screen. The sandbox, and anything the file did, is then deleted.
  5. import fs from 'node:fs';
  6. import path from 'node:path';
  7. import { createHash } from 'node:crypto';
  8. import * as sbx from './core.js';
  9. import { shot } from './run.js';
  10. import { installCommand } from './install.js';
  11. const GUEST_DIR = 'C:\\Users\\WDAGUtilityAccount\\Downloads';
  12. const WATCH = `${sbx.GUEST.agent}\\watch.ps1`;
  13. /** Built-in Windows programs that malware leans on ("living off the land"). Seeing them is a reason to look closer, not proof. */
  14. export const LOLBINS = new Set(['powershell.exe', 'pwsh.exe', 'cmd.exe', 'wscript.exe', 'cscript.exe', 'mshta.exe', 'rundll32.exe',
  15. 'regsvr32.exe', 'certutil.exe', 'bitsadmin.exe', 'schtasks.exe', 'reg.exe', 'wmic.exe', 'net.exe', 'net1.exe', 'sc.exe',
  16. 'vssadmin.exe', 'bcdedit.exe', 'wbadmin.exe', 'whoami.exe', 'nltest.exe', 'curl.exe', 'installutil.exe', 'msbuild.exe',
  17. 'regasm.exe', 'cmstp.exe', 'attrib.exe', 'icacls.exe', 'takeown.exe', 'netsh.exe', 'wevtutil.exe', 'fodhelper.exe',
  18. 'msiexec.exe', 'forfiles.exe', 'hh.exe', 'odbcconf.exe', 'msxsl.exe', 'tasklist.exe', 'systeminfo.exe', 'ipconfig.exe']);
  19. const exeName = (p) => String(p || '').split('\\').pop().toLowerCase();
  20. /** How to run a file the way a double-click would (installers silently, scripts with their default host). */
  21. export function detonateCommand(guestPath, args = '') {
  22. const ext = path.extname(guestPath).toLowerCase();
  23. if (['.js', '.jse', '.vbs', '.vbe', '.wsf'].includes(ext)) return { file: 'wscript.exe', args: `"${guestPath}" ${args}`.trim() };
  24. if (ext === '.hta') return { file: 'mshta.exe', args: `"${guestPath}"` };
  25. if (['.msi', '.ps1', '.cmd', '.bat', '.exe'].includes(ext)) return installCommand(guestPath, args);
  26. throw new Error(`Don't know how to run ${ext || 'this file'}: use an .exe, .msi, .ps1, .cmd, .bat, .js, .vbs, .wsf or .hta.`);
  27. }
  28. /**
  29. * Split audited process starts into the file's own process tree and everything else, dropping the agent's own helpers.
  30. * events: [{pid, ppid, path, commandLine, time}] from 4688. The root is the process the agent launched.
  31. */
  32. export function processTree(events, rootPid, agentPid) {
  33. const byParent = new Map();
  34. for (const e of events) byParent.set(e.ppid, [...(byParent.get(e.ppid) || []), e]);
  35. const walk = (starts) => {
  36. const seen = new Set(starts);
  37. const queue = [...starts];
  38. while (queue.length) for (const c of byParent.get(queue.shift()) || []) if (!seen.has(c.pid)) { seen.add(c.pid); queue.push(c.pid); }
  39. return seen;
  40. };
  41. const mine = walk([rootPid]);
  42. const noise = walk(events.filter((e) => e.ppid === agentPid && e.pid !== rootPid).map((e) => e.pid));
  43. const byTime = (a, b) => String(a.time).localeCompare(String(b.time));
  44. 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; };
  45. return {
  46. pids: mine,
  47. tree: events.filter((e) => mine.has(e.pid)).sort(byTime).map((e) => ({ ...e, depth: depth(e) })),
  48. others: events.filter((e) => !mine.has(e.pid) && !noise.has(e.pid)).sort(byTime),
  49. };
  50. }
  51. /** Plain-language findings, most serious first. level: high (persistence, tampering), medium (worth a look), info. */
  52. export function findings({ tree = [], lookups = [], connections = [], diff, windows = [], crashes = [] }) {
  53. const out = [];
  54. const add = (level, text) => out.push({ level, text });
  55. const children = tree.filter((p) => p.depth > 0);
  56. if (diff) {
  57. const autoruns = diff.values.filter((v) => v.change !== 'removed' && /\\(Run|RunOnce)\\|\\Winlogon\\|\\Image File Execution Options\\/i.test(v.name));
  58. for (const v of autoruns) add('high', `starts itself with Windows: ${v.change} \`${v.name}\` = \`${v.after}\``);
  59. 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'})`);
  60. const tasks = diff.files.added.filter((f) => /^C:\\Windows\\System32\\Tasks\\/i.test(f.path));
  61. for (const t of tasks) add('high', `created a scheduled task: \`${t.path.slice('C:\\Windows\\System32\\Tasks\\'.length)}\``);
  62. 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
  63. for (const p of [...new Set(startup)]) add('high', `put something in a Startup folder: \`${p}\``);
  64. if (diff.files.changed.some((p) => /\\drivers\\etc\\hosts$/i.test(p))) add('high', 'changed the hosts file (can redirect websites)');
  65. const policy = diff.registry.added.filter((k) => /\\Policies\\Microsoft\\(Windows Defender|WindowsFirewall)|\\SharedAccess\\Parameters\\FirewallPolicy/i.test(k.path));
  66. for (const k of policy) add('high', `changed security policy: \`${k.path}\``);
  67. const env = diff.values.filter((v) => /\\Environment\\/i.test(v.name));
  68. if (env.length) add('medium', `changed environment variables: ${env.map((v) => `\`${v.name.split('\\').pop()}\``).join(', ')}`);
  69. if (diff.files.executableCount) {
  70. const shown = diff.files.executables.slice(0, 5).map((p) => `\`${p}\``).join(', ');
  71. add('medium', `wrote ${diff.files.executableCount} runnable file(s): ${shown}${diff.files.executableCount > 5 ? ', …' : ''}`);
  72. }
  73. for (const p of diff.programsAdded) add('info', `installed ${p.displayName}${p.displayVersion ? ` ${p.displayVersion}` : ''}`);
  74. }
  75. const tools = [...new Set(children.map((p) => exeName(p.path)).filter((n) => LOLBINS.has(n)))];
  76. if (tools.length) add('medium', `ran built-in Windows tools that malware often uses: ${tools.join(', ')}`);
  77. if (lookups.length) add('medium', `looked up ${lookups.length} internet name(s): ${lookups.slice(0, 6).map((l) => l.name).join(', ')}${lookups.length > 6 ? ', …' : ''}`);
  78. if (connections.length) {
  79. const ends = connections.slice(0, 6).map((c) => `${c.address}:${c.port}`).join(', ');
  80. add('medium', `tried to connect to ${connections.length} address(es): ${ends}${connections.length > 6 ? ', …' : ''}`);
  81. }
  82. if (children.length) add('info', `started ${children.length} other process(es)`);
  83. if (windows.length) add('info', `opened ${windows.length} window(s): ${windows.map((w) => `"${w.title}"`).join(', ')}`);
  84. if (crashes.length) add('info', `${crashes.length} application error(s) in the event log`);
  85. const rank = { high: 0, medium: 1, info: 2 };
  86. return out.sort((a, b) => rank[a.level] - rank[b.level]);
  87. }
  88. /** Dedupe DNS events into one row per name (failed unless any attempt succeeded) and connections into one row per endpoint. */
  89. export function network(c, pids) {
  90. const names = new Map();
  91. for (const d of c.dns.filter((x) => pids.has(x.pid))) {
  92. const n = names.get(d.name.toLowerCase()) || { name: d.name, pid: d.pid, time: d.time, ok: false };
  93. if (d.status === '0') n.ok = true;
  94. names.set(d.name.toLowerCase(), n);
  95. }
  96. const ends = new Map();
  97. for (const x of c.connections.filter((y) => pids.has(y.pid))) {
  98. const k = `${x.address}|${x.port}|${x.protocol}`;
  99. const e = ends.get(k) || { ...x, count: 0 };
  100. e.count++; e.blocked = e.blocked && x.blocked;
  101. ends.set(k, e);
  102. }
  103. return { lookups: [...names.values()], connections: [...ends.values()] };
  104. }
  105. async function collect(since) {
  106. const r = await sbx.exec({ command: `& '${WATCH}' -Since '${since}'`, timeoutSec: 120 });
  107. if (r.exitCode !== 0) throw new Error(`collecting events failed: ${r.stderr || r.stdout}`);
  108. const c = JSON.parse(r.stdout.trim());
  109. for (const k of ['processes', 'connections', 'dns', 'alive']) c[k] = [].concat(c[k] ?? []);
  110. return c;
  111. }
  112. /**
  113. * file: host path. Options: args, durationSec (max watch time, default 60), full (always watch the whole time instead of
  114. * stopping once everything it started has exited), shotEverySec (default 15), exclude[], keep, plus startSandbox options
  115. * (network defaults to 'off').
  116. */
  117. export async function detonate(o) {
  118. const src = path.resolve(o.file);
  119. if (!fs.existsSync(src) || !fs.statSync(src).isFile()) throw new Error(`File not found: ${src}`);
  120. const name = path.basename(src);
  121. detonateCommand(name); // validate the extension before booting
  122. const net = o.network ?? (o.internet === true ? 'on' : 'off');
  123. const durationSec = o.durationSec ?? 60;
  124. const r = {
  125. file: name, hostPath: src, sha256: createHash('sha256').update(fs.readFileSync(src)).digest('hex'), args: o.args || '',
  126. startedAt: new Date().toISOString(), shots: [], windows: [], crashes: [],
  127. };
  128. const t0 = Date.now();
  129. let booted = false;
  130. try {
  131. const boot = await sbx.startSandbox({ ...o, network: net });
  132. booted = true;
  133. r.sandbox = { id: boot.id, epoch: boot.epoch, network: boot.network, bootSeconds: boot.bootSeconds };
  134. r.runDir = boot.runDir; r.outDir = boot.outDir;
  135. const guest = `${GUEST_DIR}\\${name}`;
  136. await sbx.copyIn(src, guest);
  137. const ag = await sbx.exec({ command: '(Get-CimInstance Win32_Process -Filter "ProcessId=$PID").ParentProcessId', timeoutSec: 60 });
  138. const agentPid = Number(ag.stdout.trim());
  139. sbx.log('turning on process, connection and DNS auditing');
  140. const armed = await sbx.exec({ command: `& '${WATCH}' -Arm`, timeoutSec: 60 });
  141. if (armed.exitCode !== 0) throw new Error(`could not turn on auditing: ${armed.stderr || armed.stdout}`);
  142. r.since = armed.stdout.trim();
  143. sbx.log('snapshot before');
  144. await sbx.snapshot('before', o.exclude);
  145. const windowsBefore = await sbx.windows();
  146. const cmd = detonateCommand(guest, o.args);
  147. sbx.log(`running ${name} and watching for up to ${durationSec}s`);
  148. const l = await sbx.launch({ path: cmd.file, args: cmd.args, cwd: GUEST_DIR, waitForWindowSec: 0 });
  149. r.command = `${cmd.file} ${cmd.args || ''}`.trim();
  150. r.rootPid = l.pid;
  151. const every = o.shotEverySec ?? 15;
  152. let nextShot = 5, quiet = 0, w0 = Date.now();
  153. for (;;) {
  154. await sbx.sleep(2500);
  155. const s = (Date.now() - w0) / 1000;
  156. if (s >= nextShot) { r.shots.push(await shot({ name: `t+${Math.round(s)}s` })); nextShot += every; }
  157. if (s >= durationSec) break;
  158. const p = await sbx.processInfo(l.pid);
  159. if (p.hasExited) {
  160. r.exitCode ??= p.exitCode;
  161. if (o.full) continue;
  162. const c = await collect(r.since);
  163. const t = processTree(c.processes, l.pid, agentPid);
  164. if (c.alive.some((pid) => t.pids.has(pid))) quiet = 0;
  165. else if (++quiet >= 3) { r.stoppedEarly = true; break; }
  166. }
  167. }
  168. r.watchedSeconds = (Date.now() - w0) / 1000;
  169. sbx.log('collecting what happened');
  170. r.shots.push(await shot({ name: 'end' }));
  171. const seen = new Set(windowsBefore.map((w) => `${w.pid}|${w.title}`));
  172. r.windows = (await sbx.windows()).filter((w) => !seen.has(`${w.pid}|${w.title}`));
  173. const c = await collect(r.since);
  174. const t = processTree(c.processes, l.pid, agentPid);
  175. // Measure from the file's own start, and leave out background activity from before it ran (the snapshot, boot tasks).
  176. r.launchedAt = t.tree[0]?.time ?? r.since;
  177. const after = (x) => ms(x.time) >= ms(r.launchedAt) - 1000;
  178. r.tree = t.tree; r.others = t.others.filter(after);
  179. r.stillRunning = t.tree.filter((p) => c.alive.includes(p.pid)).map((p) => p.pid);
  180. Object.assign(r, network(c, t.pids));
  181. const otherPids = new Set(r.others.map((p) => p.pid));
  182. r.otherLookups = [...new Set(c.dns.filter((d) => !t.pids.has(d.pid) && after(d)).map((d) => d.name.toLowerCase()))];
  183. r.otherConnections = network(c, otherPids).connections;
  184. r.crashes = await sbx.appErrors(r.since);
  185. sbx.log('snapshot after');
  186. await sbx.snapshot('after', o.exclude);
  187. r.diff = await sbx.diffSnapshots('before', 'after', o.max ?? 200);
  188. } catch (e) {
  189. r.error = e.message;
  190. r.errorStack = e.stack;
  191. } finally {
  192. if (booted && !o.keep) {
  193. sbx.log('destroying the sandbox');
  194. const st = await sbx.stopSandbox({ target: r.sandbox }).catch((e) => ({ error: e.message }));
  195. if (st.error) r.stopError = st.error;
  196. }
  197. r.kept = booted && !!o.keep;
  198. }
  199. r.seconds = (Date.now() - t0) / 1000;
  200. r.findings = r.error ? [] : findings(r);
  201. if (r.outDir) {
  202. fs.mkdirSync(r.outDir, { recursive: true });
  203. r.reportPath = path.join(r.outDir, 'report.md');
  204. fs.writeFileSync(r.reportPath, renderDetonateReport(r));
  205. fs.writeFileSync(path.join(r.outDir, 'report.json'), JSON.stringify({ ...r, shots: r.shots.map(({ previewBase64, ...s }) => s) }, null, 2));
  206. }
  207. return r;
  208. }
  209. const icon = { high: '🔴', medium: '🟠', info: '⚪' };
  210. const count = (r, level) => r.findings.filter((f) => f.level === level).length;
  211. const plain = (s) => s.replace(/`/g, '');
  212. export function headline(r) {
  213. if (r.error) return `ERROR ${r.file}: ${r.error.split('\n')[0]}`;
  214. const h = count(r, 'high'), m = count(r, 'medium');
  215. const verdict = h ? `${h} red flag(s)` : m ? `${m} thing(s) worth a look` : 'nothing notable';
  216. return `${r.file}: ${verdict} (watched ${r.watchedSeconds?.toFixed(0) ?? '?'}s, network ${r.sandbox?.network ?? '?'})`;
  217. }
  218. export function detonateSummary(r) {
  219. const lines = [headline(r)];
  220. const row = (k, v) => lines.push(` ${k.padEnd(10)} ${v}`);
  221. for (const [i, f] of r.findings.filter((x) => x.level !== 'info').entries()) row(i ? '' : 'findings', `${icon[f.level]} ${plain(f.text)}`);
  222. if (r.tree) row('processes', `${r.tree.length} (${r.tree.slice(0, 5).map((p) => exeName(p.path)).join(' → ')}${r.tree.length > 5 ? ' …' : ''})`);
  223. if (r.lookups) row('network', `${r.lookups.length} name lookup(s), ${r.connections.length} connection attempt(s)`);
  224. if (r.diff) {
  225. const d = r.diff;
  226. row('changed', `${d.files.addedCount} files added, ${d.files.changedCount} changed, ${d.registry.addedCount} registry keys, ` +
  227. `${d.values.length} autorun/env values, ${d.services.length} services`);
  228. }
  229. if (r.reportPath) row('report', r.reportPath);
  230. return lines.join('\n');
  231. }
  232. const fence = (s) => '```text\n' + (s || '').trimEnd().slice(-20_000) + '\n```';
  233. const md = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
  234. /** Guest ISO times have 7-digit fractions; trim to 3 for Date.parse. */
  235. const ms = (s) => Date.parse(String(s).replace(/(\.\d{3})\d+/, '$1'));
  236. /** Seconds since `since`, e.g. "+3.2s". */
  237. const at = (since, t) => {
  238. const d = (ms(t) - ms(since)) / 1000;
  239. return Number.isFinite(d) ? `${d < 0 ? '' : '+'}${d.toFixed(1)}s` : '';
  240. };
  241. export function renderDetonateReport(r) {
  242. const rel = (p) => path.relative(r.outDir, p).split(path.sep).join('/');
  243. const lines = [`# sbx detonate: ${r.file}`, '', `**${headline(r)}**`, '', '| | |', '|---|---|',
  244. `| File | \`${r.hostPath}\`${r.args ? ` \`${r.args}\`` : ''} |`,
  245. `| SHA-256 | \`${r.sha256}\` |`,
  246. `| Sandbox | fresh Windows Sandbox, network ${r.sandbox?.network ?? '?'}, booted in ${r.sandbox?.bootSeconds?.toFixed(1) ?? '?'}s |`,
  247. `| Ran | ${r.command ? `\`${md(r.command)}\`` : 'not run'} |`,
  248. `| Watched | ${r.watchedSeconds?.toFixed(0) ?? '?'}s${r.stoppedEarly ? ' (stopped early: everything it started had exited)' : ''}` +
  249. `${r.exitCode !== undefined && r.exitCode !== null ? `, exit code ${r.exitCode}` : ''}${r.stillRunning?.length ? `, ${r.stillRunning.length} process(es) still running at the end` : ''} |`,
  250. `| Total time | ${r.seconds.toFixed(1)}s |`, ''];
  251. if (r.findings.length) {
  252. lines.push('## Findings', '');
  253. for (const f of r.findings) lines.push(`- ${icon[f.level]} ${f.text}`);
  254. lines.push('', '_Heuristics, not a verdict: installers legitimately add autoruns and services. Read the details below._', '');
  255. }
  256. if (r.tree) {
  257. const events = [
  258. ...r.tree.map((p) => ({ time: p.time, text: `start ${exeName(p.path)} (pid ${p.pid}) ${p.commandLine || p.path}` })),
  259. ...(r.lookups || []).map((l) => ({ time: l.time, text: `lookup ${l.name} (${l.ok ? 'resolved' : 'failed'})` })),
  260. ...(r.connections || []).map((c) => ({ time: c.time, text: `connect ${c.address}:${c.port}/${c.protocol} ${c.blocked ? 'blocked' : 'allowed'} (${exeName(c.path)})` })),
  261. ].sort((a, b) => String(a.time).localeCompare(String(b.time)));
  262. lines.push('## Timeline', '', fence(events.slice(0, 200).map((e) => `${at(r.launchedAt || r.since, e.time).padStart(7)} ${e.text}`).join('\n')), '');
  263. lines.push('## Processes it started', '', '```text');
  264. 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}`);
  265. lines.push('```', '');
  266. }
  267. if (r.lookups?.length || r.connections?.length) {
  268. lines.push('## Network', '');
  269. if (r.lookups.length) {
  270. lines.push('| Name looked up | Result | By |', '|---|---|---|');
  271. for (const l of r.lookups) lines.push(`| \`${md(l.name)}\` | ${l.ok ? 'resolved' : 'failed'} | pid ${l.pid} |`);
  272. lines.push('');
  273. }
  274. if (r.connections.length) {
  275. lines.push('| Connection | Result | By |', '|---|---|---|');
  276. 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}) |`);
  277. lines.push('');
  278. }
  279. }
  280. if (r.sandbox?.network === 'off') {
  281. lines.push('_Network was off (no adapter): name lookups are still recorded, but connections to IP addresses never leave the process. ' +
  282. 'Use `--network firewall` to also see the addresses it tries to reach (blocked by the guest firewall)._', '');
  283. }
  284. if (r.diff) lines.push('## What it changed', '', sbx.formatDiff(r.diff, { title: 'before → after' }), '');
  285. if (r.diff?.files.executables.length) {
  286. lines.push('**Runnable files written**', '');
  287. for (const p of r.diff.files.executables) lines.push(`- \`${p}\``);
  288. if (r.diff.files.executableCount > r.diff.files.executables.length) lines.push(`- … and ${r.diff.files.executableCount - r.diff.files.executables.length} more`);
  289. lines.push('');
  290. }
  291. if (r.windows.length) {
  292. lines.push('## Windows it opened', '');
  293. for (const w of r.windows) lines.push(`- ${w.process} (pid ${w.pid}): "${w.title}"`);
  294. lines.push('');
  295. }
  296. if (r.crashes.length) {
  297. lines.push('## Application errors', '');
  298. for (const e of r.crashes.slice(0, 10)) lines.push(`- ${e.source} ${e.id}: ${md(String(e.message).slice(0, 300))}`);
  299. lines.push('');
  300. }
  301. if (r.others?.length || r.otherLookups?.length) {
  302. lines.push('## Everything else that happened', '', 'Usually Windows itself, but a file can also act through services, WMI or scheduled tasks.', '');
  303. if (r.others.length) {
  304. lines.push('```text');
  305. 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}`);
  306. if (r.others.length > 40) lines.push(`… and ${r.others.length - 40} more`);
  307. lines.push('```', '');
  308. }
  309. if (r.otherLookups?.length) lines.push(`Other name lookups: ${r.otherLookups.slice(0, 30).map((n) => `\`${n}\``).join(', ')}`, '');
  310. if (r.otherConnections?.length) lines.push(`Other connections: ${r.otherConnections.slice(0, 20).map((c) => `${c.address}:${c.port} (${exeName(c.path)})`).join(', ')}`, '');
  311. }
  312. if (r.shots.length) {
  313. lines.push('## Screenshots', '');
  314. for (const s of r.shots) lines.push(`**${s.name}**`, '', `![${s.name}](${rel(s.path)})`, '');
  315. }
  316. if (r.error) lines.push('## Error', '', fence(r.errorStack || r.error), '');
  317. lines.push('---', 'Files in this folder were written by the sandbox: treat them as untrusted. ' +
  318. `Audit log: \`${path.join(r.runDir || '', 'audit.jsonl')}\`${r.kept ? ' · sandbox left running (--keep)' : ''}`);
  319. return lines.join('\n') + '\n';
  320. }
src/provision.js · Bundled script · 222 lines · 2 findings marked
  1. // Explicit opt-in only: verified downloads happen on the host, never on the network-isolated guest.
  2. import fs from 'node:fs';
  3. import path from 'node:path';
  4. import { createHash, randomUUID } from 'node:crypto';
  5. import { execFile } from 'node:child_process';
  6. import { Readable } from 'node:stream';
  7. import { pipeline } from 'node:stream/promises';
  8. import * as sbx from './core.js';
  9. import { scanDependencies } from './deps.js';
  10. import { atomicJson, readJson, withStateLock } from './coordination.js';
  11. const q = (s) => `'${String(s).replace(/'/g, "''")}'`;
  12. const FRAMEWORKS = {
  13. 'Microsoft.NETCore.App': 'runtime',
  14. 'Microsoft.WindowsDesktop.App': 'windowsdesktop',
  15. 'Microsoft.AspNetCore.App': 'aspnetcore-runtime',
  16. };
  17. const arches = new Set(['x86', 'x64', 'arm64']);
  18. const official = (url) => {
  19. const u = new URL(url);
  20. if (u.protocol !== 'https:' || !['aka.ms', 'download.visualstudio.microsoft.com', 'download.microsoft.com',
  21. 'builds.dotnet.microsoft.com', 'dotnetcli.azureedge.net', 'dotnetcli.blob.core.windows.net',
  22. 'ci.dot.net'].includes(u.hostname)) throw new Error(`Not an approved Microsoft download URL: ${url}`);
  23. return u;
  24. };
  25. async function downloadResponse(url) {
  26. for (let i = 0; i < 10; i++) {
  27. official(url);
  28. const r = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(120_000) });
  29. if ([301, 302, 303, 307, 308].includes(r.status)) {
  30. await r.body?.cancel();
  31. const location = r.headers.get('location');
  32. if (!location) throw new Error(`Microsoft download redirect has no Location: ${url}`);
  33. url = new URL(location, url).href;
  34. continue;
  35. }
  36. if (!r.ok) { await r.body?.cancel(); throw new Error(`Microsoft download failed: HTTP ${r.status} (${url})`); }
  37. return r;
  38. }
  39. throw new Error('Too many Microsoft download redirects');
  40. }
  41. export function planProvision(scan, requested) {
  42. if (typeof requested !== 'string' || !requested.trim()) throw new Error('Provisioning requires auto or a comma-separated component list');
  43. let items;
  44. if (requested === 'auto') {
  45. items = [];
  46. for (const r of scan.requirements) {
  47. if (r.status === 'missing') {
  48. if (!FRAMEWORKS[r.component] && r.component !== 'VC++ redistributable') {
  49. throw new Error(`Cannot auto-provision ${r.component}. ${r.remediation}`);
  50. }
  51. items.push({ component: r.component, version: r.version, architecture: r.architecture, rollForward: r.rollForward, applyPatches: r.applyPatches });
  52. } else {
  53. const war = /^Microsoft\.WindowsAppRuntime\.(\d+\.\d+)$/.exec(r.component);
  54. if (war) items.push({ component: 'Windows App Runtime', version: war[1], architecture: r.architecture || 'unknown' });
  55. else if (r.component === 'Windows App Runtime' && r.status !== 'app-local') {
  56. throw new Error('Windows App Runtime version cannot be inferred. Pass --provision windows-app-runtime:<major.minor>:<architecture> explicitly.');
  57. } else if (r.status === 'unknown') {
  58. throw new Error(`Cannot auto-provision an unknown requirement: ${r.component}. ${r.remediation}`);
  59. }
  60. }
  61. }
  62. } else {
  63. items = requested.split(',').map((token) => {
  64. const [name, version, architecture, extra] = token.trim().split(':');
  65. const component = ({ vcredist: 'VC++ redistributable', dotnet: 'Microsoft.NETCore.App',
  66. desktop: 'Microsoft.WindowsDesktop.App', aspnetcore: 'Microsoft.AspNetCore.App', 'windows-app-runtime': 'Windows App Runtime' })[name];
  67. if (!component || extra) throw new Error(`Unknown provision component: ${token}`);
  68. if (name === 'vcredist') {
  69. if (architecture) throw new Error('Use vcredist:<architecture>');
  70. return { component, architecture: version || 'x64' };
  71. }
  72. if (!/^\d+\.\d+(?:\.\d+)?$/.test(version || '')) throw new Error(`Use ${name}:<version>:<architecture> (for example desktop:10.0:x64)`);
  73. return { component, version, architecture: architecture || 'x64', rollForward: 'LatestPatch' };
  74. });
  75. }
  76. for (const item of items) {
  77. if (!arches.has(item.architecture)) throw new Error(`Cannot provision ${item.component} for unknown architecture; supply an explicit component list.`);
  78. if (FRAMEWORKS[item.component] && !/^\d+\.\d+(?:\.\d+)?$/.test(item.version || '')) throw new Error(`Cannot resolve runtime version ${item.version}`);
  79. }
  80. const exact = (r) => r.rollForward === 'Disable' || r.applyPatches === false;
  81. const unique = [];
  82. for (const item of items) {
  83. const previous = unique.find((x) => x.component === item.component && x.version === item.version && x.architecture === item.architecture);
  84. if (!previous) unique.push({ ...item });
  85. else if (exact(item)) { previous.rollForward = 'Disable'; previous.applyPatches = false; }
  86. }
  87. if (requested === 'auto') {
  88. for (const item of unique.filter((r) => FRAMEWORKS[r.component])) {
  89. const channel = item.version.split('.').slice(0, 2).join('.');
  90. const other = unique.find((r) => FRAMEWORKS[r.component] && r.architecture === item.architecture &&
  91. r.version.split('.').slice(0, 2).join('.') === channel && r !== item &&
  92. (r.component === item.component || [r.component, item.component].every((c) => ['Microsoft.NETCore.App', 'Microsoft.WindowsDesktop.App'].includes(c))) &&
  93. (exact(item) || exact(r)) && (r.version !== item.version || exact(item) !== exact(r)));
  94. 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.`);
  95. }
  96. }
  97. // The desktop runtime bundle also installs the same-channel core runtime.
  98. return unique.filter((r) => !(r.component === 'Microsoft.NETCore.App' &&
  99. unique.some((x) => x.component === 'Microsoft.WindowsDesktop.App' && x.version === r.version && x.architecture === r.architecture)));
  100. }
  101. export function selectDotnetFile(metadata, item) {
  102. const key = FRAMEWORKS[item.component], channel = item.version.split('.').slice(0, 2).join('.');
  103. const minimum = item.version.split('.').map(Number);
  104. const acceptable = (v) => {
  105. if (!/^\d+\.\d+\.\d+$/.test(v || '')) return false;
  106. const parts = v.split('.').map(Number);
  107. if (parts.slice(0, 2).join('.') !== channel) return false;
  108. if (item.rollForward === 'Disable' || item.applyPatches === false) return v === item.version;
  109. return parts[2] >= (minimum[2] || 0);
  110. };
  111. const candidates = (metadata.releases || []).map((r) => r[key]).filter((r) => r && acceptable(r.version))
  112. .sort((a, b) => Number(b.version.split('.')[2]) - Number(a.version.split('.')[2]));
  113. for (const release of candidates) {
  114. const file = release.files?.find((f) => f.rid === `win-${item.architecture}` && /\.exe$/i.test(f.name));
  115. if (file) {
  116. official(file.url);
  117. if (!/^[a-f0-9]{128}$/i.test(file.hash || '')) throw new Error('Official .NET metadata has no valid SHA-512 hash');
  118. return { ...item, version: release.version, url: file.url, sha512: file.hash.toLowerCase(), args: '/install /quiet /norestart' };
  119. }
  120. }
  121. throw new Error(`No compatible official ${item.component} installer for ${item.version} ${item.architecture} (rollForward ${item.rollForward || 'Minor'}).`);
  122. }
  123. async function resolveInstaller(item) {
  124. if (FRAMEWORKS[item.component]) {
  125. const channel = item.version.split('.').slice(0, 2).join('.');
  126. const response = await downloadResponse(`https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/${channel}/releases.json`);
  127. return selectDotnetFile(await response.json(), item);
  128. }
  129. if (item.component === 'VC++ redistributable') return { ...item,
  130. 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
  131. if (item.component === 'Windows App Runtime') {
  132. if (!/^\d+\.\d+$/.test(item.version)) throw new Error('Windows App Runtime requires a major.minor release channel');
  133. 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
  134. }
  135. throw new Error(`Unsupported redistributable: ${item.component}`);
  136. }
  137. async function verify(file, expected) {
  138. const hash = createHash(expected ? 'sha512' : 'sha256');
  139. for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
  140. const digest = hash.digest('hex');
  141. if (expected && digest !== expected.toLowerCase()) throw new Error(`SHA-512 mismatch for ${file}`);
  142. 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`;
  143. const signature = await new Promise((resolve, reject) => execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script],
  144. { timeout: 120_000, windowsHide: true }, (err, stdout, stderr) => err ? reject(new Error(`Installer signature verification failed: ${stderr || err.message}`)) : resolve(stdout.trim())));
  145. return { algorithm: expected ? 'sha512' : 'sha256', hash: digest, ...JSON.parse(signature) };
  146. }
  147. export async function prepareProvision(scan, requested) {
  148. const prepared = [];
  149. for (const item of planProvision(scan, requested)) {
  150. const installer = await resolveInstaller(item);
  151. const cache = path.join(sbx.HOME, 'cache', 'redistributables');
  152. fs.mkdirSync(cache, { recursive: true });
  153. const name = createHash('sha256').update(installer.url + (installer.sha512 || '')).digest('hex') + '.exe';
  154. const file = path.join(cache, name);
  155. if (!fs.existsSync(file)) {
  156. const partial = `${file}.${randomUUID()}.partial`;
  157. try {
  158. sbx.log(`downloading ${installer.component} ${installer.version || ''} ${installer.architecture} on the host`);
  159. const response = await downloadResponse(installer.url);
  160. await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(partial, { flags: 'wx' }));
  161. const verification = await verify(partial, installer.sha512);
  162. fs.renameSync(partial, file);
  163. prepared.push({ ...installer, file, verification });
  164. } finally {
  165. if (fs.existsSync(partial)) fs.unlinkSync(partial);
  166. }
  167. } else prepared.push({ ...installer, file, verification: await verify(file, installer.sha512) });
  168. }
  169. return prepared;
  170. }
  171. export function recordProvisioning(runDir, requested, provisioned) {
  172. const file = path.join(runDir, 'provisioning.json');
  173. withStateLock(runDir, () => {
  174. const previous = readJson(file);
  175. const records = new Map((previous?.provisioned || []).map((record) => [JSON.stringify(record), record]));
  176. for (const record of provisioned) records.set(JSON.stringify(record), record);
  177. atomicJson(file, { cleanMachine: false, requested, provisioned: [...records.values()], updatedAt: new Date().toISOString() });
  178. });
  179. }
  180. export async function installProvision(prepared, onInstalled = () => {}, target) {
  181. const installed = [];
  182. if (prepared.length && !target) target = await sbx.current();
  183. if (prepared.length && !target) throw new Error('Start a sandbox before provisioning into it.');
  184. for (const item of prepared) {
  185. const copied = await sbx.copyIn(item.file, `C:\\sbx-provision\\${path.basename(item.file)}`, target);
  186. const command = `$ErrorActionPreference='Stop'; $p=Start-Process -FilePath ${q(copied.path)} -ArgumentList ${q(item.args)} -Wait -PassThru; exit $p.ExitCode`;
  187. const result = await sbx.exec({ command, timeoutSec: 600 }, target);
  188. // 3010 is a successful install requiring reboot, not proof the current guest is usable.
  189. 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 || ''}`);
  190. const record = { component: item.component, version: item.version, architecture: item.architecture,
  191. source: item.url, verification: item.verification, exitCode: result.exitCode };
  192. installed.push(record);
  193. onInstalled(record);
  194. }
  195. return installed;
  196. }
  197. /** Provision an already-started sandbox; never starts or adopts one. */
  198. export async function provisionSandbox(app, requested) {
  199. const state = await sbx.current();
  200. if (!state) throw new Error('Start a sandbox before provisioning into it.');
  201. const dependencies = scanDependencies(app);
  202. const prepared = await prepareProvision(dependencies, requested);
  203. const current = await sbx.status();
  204. if (!current.running || current.id !== state.id || current.epoch !== state.epoch) throw new Error('Sandbox changed while preparing dependencies; nothing installed.');
  205. const provisioned = current.provisioning?.provisioned || [];
  206. recordProvisioning(current.runDir, requested, provisioned);
  207. const installed = await installProvision(prepared, (record) => {
  208. provisioned.push(record);
  209. recordProvisioning(current.runDir, requested, provisioned);
  210. }, state);
  211. return { cleanMachine: false, dependencies, provisioned: installed, provenancePath: path.join(current.runDir, 'provisioning.json') };
  212. }

Version history

  • v1.2.011/7/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.