Move windows-sandbox and redirect

This commit is contained in:
Vinay Pamnani
2023-05-25 12:08:39 -04:00
parent 86291f2294
commit 2afdf6caef
10 changed files with 643 additions and 628 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 53 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

View File

@ -0,0 +1,59 @@
---
title: Windows Sandbox architecture
description: Windows Sandbox architecture
ms.prod: windows-client
author: vinaypamnani-msft
ms.author: vinpa
manager: aaroncz
ms.topic: article
ms.date: 6/30/2022
ms.technology: itpro-security
---
# Windows Sandbox architecture
Windows Sandbox benefits from new container technology in Windows to achieve a combination of security, density, and performance that isn't available in traditional VMs.
## Dynamically generated image
Rather than requiring a separate copy of Windows to boot the sandbox, Dynamic Base Image technology uses the copy of Windows already installed on the host.
Most OS files are immutable and can be freely shared with Windows Sandbox. A small subset of operating system files are mutable and can't be shared, so the sandbox base image contains pristine copies of them. A complete Windows image can be constructed from a combination of the sharable immutable files on the host and the pristine copies of the mutable files. With the help of this scheme, Windows Sandbox has a full Windows installation to boot from without needing to download or store an extra copy of Windows.
Before Windows Sandbox is installed, the dynamic base image package is stored as a compressed 30-MB package. Once it's installed, the dynamic base image occupies about 500 MB of disk space.
![A chart compares scale of dynamic image of files and links with the host file system.](images/1-dynamic-host.png)
## Memory management
Traditional VMs apportion statically sized allocations of host memory. When resource needs change, classic VMs have limited mechanisms for adjusting their resource needs. On the other hand, containers collaborate with the host to dynamically determine how host resources are allocated. This method is similar to how processes normally compete for memory on the host. If the host is under memory pressure, it can reclaim memory from the container much like it would with a process.
![A chart compares memory sharing in Windows Sandbox versus a traditional VM.](images/2-dynamic-working.png)
## Memory sharing
Because Windows Sandbox runs the same operating system image as the host, it has been enhanced to use the same physical memory pages as the host for operating system binaries via a technology referred to as "direct map." For example, when *ntdll.dll* is loaded into memory in the sandbox, it uses the same physical pages as those pages of the binary when loaded on the host. Memory sharing between the host and the sandbox results in a smaller memory footprint when compared to traditional VMs, without compromising valuable host secrets.
![A chart compares the memory footprint in Windows Sandbox versus a traditional VM.](images/3-memory-sharing.png)
## Integrated kernel scheduler
With ordinary virtual machines, the Microsoft hypervisor controls the scheduling of the virtual processors running in the VMs. Windows Sandbox uses a new technology called "integrated scheduling," which allows the host scheduler to decide when the sandbox gets CPU cycles.
![A chart compares the scheduling in Windows Sandbox versus a traditional VM.](images/4-integrated-kernal.png)
Windows Sandbox employs a unique policy that allows the virtual processors of the Sandbox to be scheduled like host threads. Under this scheme, high-priority tasks on the host can preempt less important work in the Sandbox. This preemption means that the most important work will be prioritized, whether it's on the host or in the container.
## WDDM GPU virtualization
Hardware accelerated rendering is key to a smooth and responsive user experience, especially for graphics-intensive use cases. Microsoft works with its graphics ecosystem partners to integrate modern graphics virtualization capabilities directly into DirectX and Windows Display Driver Model (WDDM), the driver model used by Windows.
This feature allows programs running inside the sandbox to compete for GPU resources with applications that are running on the host.
![A chart illustrates graphics kernel use in Sandbox managed alongside apps on the host.](images/5-wddm-gpu-virtualization.png)
To take advantage of these benefits, a system with a compatible GPU and graphics drivers (WDDM 2.5 or newer) is required. Incompatible systems will render apps in Windows Sandbox with Microsoft's CPU-based rendering technology, Windows Advanced Rasterization Platform (WARP).
## Battery pass-through
Windows Sandbox is also aware of the host's battery state, which allows it to optimize its power consumption. This functionality is critical for technology that is used on laptops, where battery life is often critical.

View File

@ -0,0 +1,310 @@
---
title: Windows Sandbox configuration
description: Windows Sandbox configuration
ms.prod: windows-client
author: vinaypamnani-msft
ms.author: vinpa
manager: aaroncz
ms.collection:
- highpri
- tier2
ms.topic: article
ms.date: 6/30/2022
ms.technology: itpro-security
---
# Windows Sandbox configuration
Windows Sandbox supports simple configuration files, which provide a minimal set of customization parameters for Sandbox. This feature can be used with Windows 10 build 18342 or Windows 11. Windows Sandbox configuration files are formatted as XML and are associated with Sandbox via the `.wsb` file extension.
A configuration file enables the user to control the following aspects of Windows Sandbox:
- **vGPU (virtualized GPU)**: Enable or disable the virtualized GPU. If vGPU is disabled, the sandbox will use Windows Advanced Rasterization Platform (WARP).
- **Networking**: Enable or disable network access within the sandbox.
- **Mapped folders**: Share folders from the host with *read* or *write* permissions. Exposing host directories may allow malicious software to affect the system or steal data.
- **Logon command**: A command that's executed when Windows Sandbox starts.
- **Audio input**: Shares the host's microphone input into the sandbox.
- **Video input**: Shares the host's webcam input into the sandbox.
- **Protected client**: Places increased security settings on the RDP session to the sandbox.
- **Printer redirection**: Shares printers from the host into the sandbox.
- **Clipboard redirection**: Shares the host clipboard with the sandbox so that text and files can be pasted back and forth.
- **Memory in MB**: The amount of memory, in megabytes, to assign to the sandbox.
> [!NOTE]
> The size of the sandbox window currently isn't configurable. <!-- windows-itpro-docs #10689 -->
## Creating a configuration file
To create a configuration file:
1. Open a plain text editor or source code editor (for example, Notepad, Visual Studio Code, etc.)
2. Insert the following lines:
```XML
<Configuration>
</Configuration>
```
3. Add appropriate configuration text between the two lines. For details, see the correct syntax and the examples below.
4. Save the file with the desired name, but make sure its filename extension is `.wsb`. In Notepad, you should enclose the filename and the extension inside double quotation marks, for example, `"My config file.wsb"`.
## Using a configuration file
To use a configuration file, double-click it to start Windows Sandbox according to its settings. You can also invoke it via the command line as shown here:
```batch
C:\Temp> MyConfigFile.wsb
```
## Keywords, values, and limits
### vGPU
Enables or disables GPU sharing.
`<vGPU>value</vGPU>`
Supported values:
- *Enable*: Enables vGPU support in the sandbox.
- *Disable*: Disables vGPU support in the sandbox. If this value is set, the sandbox will use software rendering, which may be slower than virtualized GPU.
- *Default* This value is the default value for vGPU support. Currently, this default value denotes that vGPU is disabled.
> [!NOTE]
> Enabling virtualized GPU can potentially increase the attack surface of the sandbox.
### Networking
Enables or disables networking in the sandbox. You can disable network access to decrease the attack surface exposed by the sandbox.
`<Networking>value</Networking>`
Supported values:
- *Enable*: Enables networking in the sandbox.
- *Disable*: Disables networking in the sandbox.
- *Default*: This value is the default value for networking support. This value 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 the internal network.
### Mapped folders
An array of folders, each representing a location on the host machine that will be shared into the sandbox at the specified path. At this time, relative paths aren't supported. If no path is specified, the folder will be mapped to the container user's desktop.
```xml
<MappedFolders>
<MappedFolder>
<HostFolder>absolute path to the host folder</HostFolder>
<SandboxFolder>absolute path to the sandbox folder</SandboxFolder>
<ReadOnly>value</ReadOnly>
</MappedFolder>
<MappedFolder>
...
</MappedFolder>
</MappedFolders>
```
*HostFolder*: Specifies the folder on the host machine to share into the sandbox. The folder must already exist on the host, or the container will fail to start.
*SandboxFolder*: Specifies the destination in the sandbox to map the folder to. If the folder doesn't exist, it will be created. If no sandbox folder is specified, the folder will be mapped to the container desktop.
*ReadOnly*: If *true*, enforces read-only access to the shared folder from within the container. Supported values: *true*/*false*. Defaults to *false*.
> [!NOTE]
> Files and folders mapped in from the host can be compromised by apps in the sandbox or potentially affect the host.
### Logon command
Specifies a single command that will be invoked automatically after the sandbox logs on. Apps in the sandbox are run under the container user account. The container user account should be an administrator account.
```xml
<LogonCommand>
<Command>command to be invoked</Command>
</LogonCommand>
```
*Command*: A path to an executable or script inside the container that will be executed after signing in.
> [!NOTE]
> Although very simple commands will work (such as 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.
### Audio input
Enables or disables audio input to the sandbox.
`<AudioInput>value</AudioInput>`
Supported values:
- *Enable*: Enables audio input in the sandbox. If this value is set, the sandbox will be able to receive audio input from the user. Applications that use a microphone may require this capability.
- *Disable*: Disables audio input in the sandbox. If this value is set, the sandbox can't receive audio input from the user. Applications that use a microphone may not function properly with this setting.
- *Default*: This value is the default value for audio input support. Currently, this default value denotes that audio input is enabled.
> [!NOTE]
> There may be security implications of exposing host audio input to the container.
### Video input
Enables or disables video input to the sandbox.
`<VideoInput>value</VideoInput>`
Supported values:
- *Enable*: Enables video input in the sandbox.
- *Disable*: Disables video input in the sandbox. Applications that use video input may not function properly in the sandbox.
- *Default*: This value is the default value for video input support. Currently, this default value denotes that video input is disabled. Applications that use video input may not function properly in the sandbox.
> [!NOTE]
> There may be security implications of exposing host video input to the container.
### Protected client
Applies more security settings to the sandbox Remote Desktop client, decreasing its attack surface.
`<ProtectedClient>value</ProtectedClient>`
Supported values:
- *Enable*: Runs Windows sandbox in Protected Client mode. If this value is set, the sandbox runs with extra security mitigations enabled.
- *Disable*: Runs the sandbox in standard mode without extra security mitigations.
- *Default*: This value is the default value for Protected Client mode. Currently, this default value denotes that the sandbox doesn't run in Protected Client mode.
> [!NOTE]
> This setting may restrict the user's ability to copy/paste files in and out of the sandbox.
### Printer redirection
Enables or disables printer sharing from the host into the sandbox.
`<PrinterRedirection>value</PrinterRedirection>`
Supported values:
- *Enable*: Enables sharing of host printers into the sandbox.
- *Disable*: Disables printer redirection in the sandbox. If this value is set, the sandbox can't view printers from the host.
- *Default*: This value is the default value for printer redirection support. Currently, this default value denotes that printer redirection is disabled.
### Clipboard redirection
Enables or disables sharing of the host clipboard with the sandbox.
`<ClipboardRedirection>value</ClipboardRedirection>`
Supported values:
- *Enable*: Enables sharing of the host clipboard with the sandbox.
- *Disable*: Disables clipboard redirection in the sandbox. If this value is set, copy/paste in and out of the sandbox will be restricted.
- *Default*: This value is the default value for clipboard redirection. Currently, copy/paste between the host and sandbox are permitted under *Default*.
### Memory in MB
Specifies the amount of memory that the sandbox can use in megabytes (MB).
`<MemoryInMB>value</MemoryInMB>`
If the memory value specified is insufficient to boot a sandbox, it will be automatically increased to the required minimum amount.
## Example 1
The following config file can be used to easily test the downloaded files inside the sandbox. To achieve this testing, networking and vGPU are disabled, and the sandbox is allowed read-only access to the shared downloads folder. For convenience, the logon command opens the downloads folder inside the sandbox when it's started.
### Downloads.wsb
```xml
<Configuration>
<VGpu>Disable</VGpu>
<Networking>Disable</Networking>
<MappedFolders>
<MappedFolder>
<HostFolder>C:\Users\Public\Downloads</HostFolder>
<SandboxFolder>C:\Users\WDAGUtilityAccount\Downloads</SandboxFolder>
<ReadOnly>true</ReadOnly>
</MappedFolder>
</MappedFolders>
<LogonCommand>
<Command>explorer.exe C:\users\WDAGUtilityAccount\Downloads</Command>
</LogonCommand>
</Configuration>
```
## Example 2
The following config file installs Visual Studio Code in the sandbox, which requires a slightly more complicated LogonCommand setup.
Two folders are mapped into the sandbox; the first (SandboxScripts) contains VSCodeInstall.cmd, which will install and run Visual Studio Code. The second folder (CodingProjects) is assumed to contain project files that the developer wants to modify using Visual Studio Code.
With the Visual Studio Code installer script already mapped into the sandbox, the LogonCommand can reference it.
### VSCodeInstall.cmd
Download vscode to `downloads` folder and run from `downloads` folder.
```batch
REM Download Visual Studio Code
curl -L "https://update.code.visualstudio.com/latest/win32-x64-user/stable" --output C:\users\WDAGUtilityAccount\Downloads\vscode.exe
REM Install and run Visual Studio Code
C:\users\WDAGUtilityAccount\Downloads\vscode.exe /verysilent /suppressmsgboxes
```
### VSCode.wsb
```xml
<Configuration>
<MappedFolders>
<MappedFolder>
<HostFolder>C:\SandboxScripts</HostFolder>
<SandboxFolder>C:\Users\WDAGUtilityAccount\Downloads\sandbox</SandboxFolder>
<ReadOnly>true</ReadOnly>
</MappedFolder>
<MappedFolder>
<HostFolder>C:\CodingProjects</HostFolder>
<SandboxFolder>C:\Users\WDAGUtilityAccount\Documents\Projects</SandboxFolder>
<ReadOnly>false</ReadOnly>
</MappedFolder>
</MappedFolders>
<LogonCommand>
<Command>C:\Users\WDAGUtilityAccount\Downloads\sandbox\VSCodeInstall.cmd</Command>
</LogonCommand>
</Configuration>
```
## Example 3
The following config file runs a PowerShell script as a logon command to swap the primary mouse button for left-handed users.
`C:\sandbox` folder on the host is mapped to the `C:\sandbox` folder in the sandbox, so the `SwapMouse.ps1` script can be referenced in the sandbox configuration file.
### SwapMouse.ps1
Create a powershell script using the following code, and save it in the `C:\sandbox` directory as `SwapMouse.ps1`.
```powershell
[Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") | Out-Null
$SwapButtons = Add-Type -MemberDefinition @'
[DllImport("user32.dll")]
public static extern bool SwapMouseButton(bool swap);
'@ -Name "NativeMethods" -Namespace "PInvoke" -PassThru
$SwapButtons::SwapMouseButton(!([System.Windows.Forms.SystemInformation]::MouseButtonsSwapped))
```
### SwapMouse.wsb
```xml
<Configuration>
<MappedFolders>
<MappedFolder>
<HostFolder>C:\sandbox</HostFolder>
<SandboxFolder>C:\sandbox</SandboxFolder>
<ReadOnly>True</ReadOnly>
</MappedFolder>
</MappedFolders>
<LogonCommand>
<Command>powershell.exe -ExecutionPolicy Bypass -File C:\sandbox\SwapMouse.ps1</Command>
</LogonCommand>
</Configuration>
```

View File

@ -0,0 +1,85 @@
---
title: Windows Sandbox
description: Windows Sandbox overview
ms.prod: windows-client
author: vinaypamnani-msft
ms.author: vinpa
manager: aaroncz
ms.collection:
- highpri
- tier2
ms.topic: article
ms.date: 6/30/2022
ms.technology: itpro-security
---
# Windows Sandbox
Windows Sandbox provides a lightweight desktop environment to safely run applications in isolation. Software installed inside the Windows Sandbox environment remains "sandboxed" and runs separately from the host machine.
A sandbox is temporary. When it's closed, all the software and files and the state are deleted. You get a brand-new instance of the sandbox every time you open the application. Note, however, that as of [Windows 11 Build 22509](https://blogs.windows.com/windows-insider/2021/12/01/announcing-windows-11-insider-preview-build-22509/), your data will persist through a restart initiated from inside the virtualized environment—useful for installing applications that require the OS to reboot.
Software and applications installed on the host aren't directly available in the sandbox. If you need specific applications available inside the Windows Sandbox environment, they must be explicitly installed within the environment.
Windows Sandbox has the following properties:
- **Part of Windows**: Everything required for this feature is included in Windows 10 Pro and Enterprise. There's no need to download a VHD.
- **Pristine**: Every time Windows Sandbox runs, it's as clean as a brand-new installation of Windows.
- **Disposable**: Nothing persists on the device. Everything is discarded when the user closes the application.
- **Secure**: Uses hardware-based virtualization for kernel isolation. It relies on the Microsoft hypervisor to run a separate kernel that isolates Windows Sandbox from the host.
- **Efficient:** Uses the integrated kernel scheduler, smart memory management, and virtual GPU.
> [!IMPORTANT]
> Windows Sandbox enables network connection by default. It can be disabled using the [Windows Sandbox configuration file](/windows/security/threat-protection/windows-sandbox/windows-sandbox-configure-using-wsb-file#networking).
[!INCLUDE [windows-sandbox](../../../../includes/licensing/windows-sandbox.md)]
## Prerequisites
- ARM64 (for Windows 11, version 22H2 and later) or AMD64 architecture
- Virtualization capabilities enabled in BIOS
- At least 4 GB of RAM (8 GB recommended)
- At least 1 GB of free disk space (SSD recommended)
- At least two CPU cores (four cores with hyper-threading recommended)
> [!NOTE]
> Windows Sandbox is currently not supported on Windows Home edition
## Installation
1. Ensure that your machine is using Windows 10 Pro or Enterprise, build version 18305 or Windows 11.
2. Enable virtualization on the machine.
- If you're using a physical machine, make sure virtualization capabilities are enabled in the BIOS.
- If you're using a virtual machine, run the following PowerShell command to enable nested virtualization:
```powershell
Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true
```
3. Use the search bar on the task bar and type **Turn Windows Features on or off** to access the Windows Optional Features tool. Select **Windows Sandbox** and then **OK**. Restart the computer if you're prompted.
If the **Windows Sandbox** option is unavailable, your computer doesn't meet the requirements to run Windows Sandbox. If you think this analysis is incorrect, review the prerequisite list and steps 1 and 2.
> [!NOTE]
> To enable Sandbox using PowerShell, open PowerShell as Administrator and run the following command:
>
> ```powershell
> Enable-WindowsOptionalFeature -FeatureName "Containers-DisposableClientVM" -All -Online
> ```
4. Locate and select **Windows Sandbox** on the Start menu to run it for the first time.
> [!NOTE]
> Windows Sandbox does not adhere to the mouse settings of the host system, so if the host system is set to use a left-handed mouse, you must apply these settings in Windows Sandbox manually when Windows Sandbox starts. Alternatively, you can use a sandbox configuration file to run a logon command to swap the mouse setting. For an example, see [Example 3](windows-sandbox-configure-using-wsb-file.md#example-3).
## Usage
1. Copy an executable file (and any other files needed to run the application) from the host and paste them into the **Windows Sandbox** window.
2. Run the executable file or installer inside the sandbox.
3. When you're finished experimenting, close the sandbox. A dialog box will state that all sandbox content will be discarded and permanently deleted. Select **Ok**.
4. Confirm that your host machine doesn't exhibit any of the modifications that you made in Windows Sandbox.