Windows Sandbox - Config Files

Since the initial announcement of Windows Sandbox, we have received overwhelmingly positive feedback. Thank you for your support! We are glad that this feature resonates with the Windows community. 

 

One of the most requested features from our customers is the ability to automatically launch an app or script in the sandbox. Coincidentally, this also aligned with our feature roadmap and is now available in Windows Insider builds. 

 

Windows Sandbox now has support for simple configuration files (.wsb file extension), which provide minimal scripting support. You can use this feature in the latest Windows Insider build 18342.  

 

As always, we rely on your feedback to build features allowing our users to achieve more. 

 

NOTE: Please note that this functionality is still in development and subject to change.  

 

Overview

Sandbox configuration files are formatted as XML, and are associated with Windows Sandbox via the .wsb file extension. A configuration file allows the user to control the following aspects of Windows Sandbox:

 

1. vGPU (virtualized GPU)
   • Enable or Disable the virtualized GPU. If vGPU is disabled, Sandbox will use WARP (software rasterizer).
2. Networking
   • Enable or Disable network access to the Sandbox.
3. Shared folders
   • Share folders from the host with read or write permissions. Note that exposing host directories may allow malicious software to affect your system or steal data.
4. Startup script
   • Logon action for the sandbox.

 

 

As demonstrated in the examples below, configuration files can be used to granularly control Windows Sandbox for enhanced isolation.

 

Double click a config file to open it in Windows Sandbox, or invoke it via the command line as shown:

 

C:\Temp> MyConfigFile.wsb

 

Keywords, values and limits

 

VGpu

Enables or disables GPU sharing.

 

<VGpu>value</VGpu> 

 

Supported values:

• Disable – disables vGPU support in the sandbox. If this value is set Windows Sandbox will use software rendering, which can be slower than virtualized GPU.
• Default – this is the default value for vGPU support; currently this means vGPU is enabled.

Note: Enabling virtualized GPU can potentially increase the attack surface of the sandbox.

 

Networking

Enables or disables networking in the sandbox. Disabling network access can be used to decrease the attack surface exposed by the Sandbox.

 

<Networking>value</Networking>

 

Supported values:

• Disable – disables networking in the sandbox.
• Default – this is the default value for networking support. This enables networking by creating a virtual switch on the host, and connects the sandbox to it via a virtual NIC.

 Note: Enabling networking can expose untrusted applications to your internal network.

 

MappedFolders

Wraps a list of MappedFolder objects.

 

<MappedFolders>
list of MappedFolder objects
</MappedFolders>

 

Note: Files and folders mapped in from the host can be compromised by apps in the Sandbox or potentially affect the host. 

 

MappedFolder 

Specifies a single folder on the host machine which will be shared on the container desktop. Apps in the Sandbox are run under the user account “WDAGUtilityAccount”. Hence, all folders are mapped under the following path: C:\Users\WDAGUtilityAccount\Desktop.

 

E.g. “C:\Test” will be mapped as “C:\users\WDAGUtilityAccount\Desktop\Test”.

 

<MappedFolder>
    <HostFolder>path to the host folder</HostFolder>
    <ReadOnly>value</ReadOnly>
</MappedFolder>

 

HostFolder: Specifies the folder on the host machine to share to the sandbox. Note that the folder must already exist the host or the container will fail to start if the folder is not found.

 

ReadOnly: If true, enforces read-only access to the shared folder from within the container. Supported values: true/false.

 

Note: Files and folders mapped in from the host can be compromised by apps in the Sandbox or potentially affect the host.

 

LogonCommand

Specifies a single Command which will be invoked automatically after the container logs on.

 

<LogonCommand>
   <Command>command to be invoked</Command>
</LogonCommand>

 

Command: A path to an executable or script inside of the container that will be executed after login.

 

Note: Although very simple commands will work (launching an executable or script), more complicated scenarios involving multiple steps should be placed into a script file. This script file may be mapped into the container via a shared folder, and then executed via the LogonCommand directive.

 

Example 1:

The following config file can be used to easily test downloaded files inside of the sandbox. To achieve this, the script disables networking and vGPU, and restricts the shared downloads folder to read-only access in the container. For convenience, the logon command opens the downloads folder inside of the container when it is started.

 

Downloads.wsb

<Configuration>
<VGpu>Disable</VGpu>
<Networking>Disable</Networking>
<MappedFolders>
   <MappedFolder>
     <HostFolder>C:\Users\Public\Downloads</HostFolder>
     <ReadOnly>true</ReadOnly>
   </MappedFolder>
</MappedFolders>
<LogonCommand>
   <Command>explorer.exe C:\users\WDAGUtilityAccount\Desktop\Downloads</Command>
</LogonCommand>
</Configuration>

 

Example 2

The following config file installs Visual Studio Code in the container, which requires a slightly more complicated LogonCommand setup.

 

Two folders are mapped into the container; the first (SandboxScripts) contains VSCodeInstall.cmd, which will install and run VSCode. The second folder (CodingProjects) is assumed to contain project files that the developer wants to modify using VSCode.

 

With the VSCode installer script already mapped into the container, the LogonCommand can reference it.

 

VSCodeInstall.cmd

REM Download VSCode
curl -L "https://update.code.visualstudio.com/latest/win32-x64-user/stable" --output C:\users\WDAGUtilityAccount\Desktop\vscode.exe
 
REM Install and run VSCode
C:\users\WDAGUtilityAccount\Desktop\vscode.exe /verysilent /suppressmsgboxes

 

VSCode.wsb

<Configuration>
<MappedFolders>
   <MappedFolder>
     <HostFolder>C:\SandboxScripts</HostFolder>
     <ReadOnly>true</ReadOnly>
   </MappedFolder>
   <MappedFolder>
     <HostFolder>C:\CodingProjects</HostFolder>
     <ReadOnly>false</ReadOnly>
   </MappedFolder>
</MappedFolders>
<LogonCommand>
   <Command>C:\users\wdagutilityaccount\desktop\SandboxScripts\VSCodeInstall.cmd</Command>
</LogonCommand>
</Configuration>

 

Conclusion

We look forward to your feedback.

 

Cheers,

Margarit Chenchev, Erick Smith, Paul Bozzay, Deepti Bhardwaj & Hari Pulapaka

(Windows Sandbox team)