Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jdhitsolutions/windowssandboxtools
:camel: My PowerShell scripts and tools for setting up and configuring the Windows Sandbox
https://github.com/jdhitsolutions/windowssandboxtools
powershell windows-sandbox
Last synced: about 2 months ago
JSON representation
:camel: My PowerShell scripts and tools for setting up and configuring the Windows Sandbox
- Host: GitHub
- URL: https://github.com/jdhitsolutions/windowssandboxtools
- Owner: jdhitsolutions
- License: other
- Created: 2020-08-27T17:07:39.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-06-21T14:37:09.000Z (over 1 year ago)
- Last Synced: 2024-10-12T21:06:46.068Z (2 months ago)
- Topics: powershell, windows-sandbox
- Language: PowerShell
- Homepage:
- Size: 11.3 MB
- Stars: 67
- Watchers: 5
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: License.txt
Awesome Lists containing this project
README
# Windows Sandbox Tools
[](https://www.powershellgallery.com/packages/WindowsSandboxTools/) [](https://www.powershellgallery.com/packages/WindowsSandboxTools/)
This repository is a collection of PowerShell tools and scripts that I use to run and configure the Windows Sandbox feature that was introduced in Windows 10 2004. Many of the commands in this repository were first demonstrated on my [blog](https://jdhitsolutions.com/blog/powershell/7621/doing-more-with-windows-sandbox/). I strongly recommend you read the blog post before trying any of the code. As I mention in the blog post, most of the code here will __reduce the security__ of the Windows Sandbox application. This is a trade-off I am willing to make for the sake of functionality that meets *my* requirements. You have to decide how much of the code you would like to use.
__*All code is offered as-is with no guarantees. Nothing in this repository should be considered production-ready or used in critical environments without your extensive testing and validation.*__
## Installing the Windows Sandbox
You need to have the 2004 version of Windows 10 or later. The Windows Sandbox will run a containerized version of your operating system. I don't know off-hand if it is supported on Windows 10 Home or Education editions. Otherwise, you should be able to run these PowerShell commands to get started:
```powershell
Get-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM
Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM
```
## The WindowsSandBoxTools Module
I have created a PowerShell module called `WindowsSandBoxTools`. In this module are functions designed to make it easier to view a `wsb` configuration, create a new configuration, and export a configuration to a file. The module functions use several PowerShell class definitions.
You can read the Microsoft documentation on creating a Windows Sandbox configuration at [https://docs.microsoft.com/windows/security/threat-protection/windows-sandbox/windows-sandbox-configure-using-wsb-file](https://docs.microsoft.com/windows/security/threat-protection/windows-sandbox/windows-sandbox-configure-using-wsb-file). The module commands are designed to abstract the process of creating the XML configuration files which have a `.wsb` extension.
Install the module from the PowerShell Gallery.
```powershell
Install-Module WindowsSandboxTools
```
The module should work in Windows PowerShell and PowerShell 7 on Windows platforms.
### [Start-WindowsSandbox](docs/Start-WindowsSandbox.md)
The [`Start-WindowsSandbox`](docs/Start-WindowsSandbox.mx) function is my primary tool. It has an alias of `wsb`. You can specify the path to the wsb file.
If you use the `NoSetup` parameter, it will launch the default Windows Sandbox. In either usage, you can specify display dimensions for the sandbox. The `WindowSize` parameter expects an array of width and height, like 1024,768. My default is 1920,1080. You may have to drag the window slightly to force the sandbox to redraw the screen and remove the horizontal scrollbar. Setting the display is tricky, and I don't know if what I am using will work for everyone, so if you don't get the results you expect, please post an issue.
The sandbox will start and then minimize while any configurations you may have are executed.
### [Get-WsbConfiguration](docs/Get-WsbConfiguration.md)
If you have created custom configurations, or intend to use the samples from this module, `Get-WsbConfiguration` will display information about the configuration.
```text
PS C:\> Get-WsbConfiguration d:\wsb\simple.wsb
WARNING: No value detected for LogonCommand. This may be intentional on your part.
Name: Simple
vGPU : Enable
MemoryInMB : 8192
AudioInput : Default
VideoInput : Default
ClipboardRedirection : Default
PrinterRedirection : Default
Networking : Default
ProtectedClient : Default
LogonCommand :
MappedFolders : C:\scripts -> C:\scripts [RO:False]
```
The command uses a custom format file to display the configuration. I have also found a way to insert metadata into the wsb file which (so far) doesn't appear to interfere with the Windows Sandbox application.
```text
PS C:\> Get-WsbConfiguration d:\wsb\simple.wsb -MetadataOnly
Author Name Description Updated
------ ---- ----------- -------
Jeff Hicks Simple a simple configuration with mapping to C:\Scripts 12/10/2021 8:50:03 AM
```
### [New-WsbConfiguration](docs/New-WsbConfiguration.md)
This is how you can create a new Windows Sandbox configuration.
```powershell
$params = @{
Networking = "Default"
LogonCommand = "c:\data\demo.cmd"
MemoryInMB = 2048
PrinterRedirection = "Disable"
MappedFolder = (New-WsbMappedFolder -HostFolder d:\data -SandboxFolder c:\data -ReadOnly)
Name = "MyDemo"
Description = "A demo WSB configuration"
}
$new = New-WsbConfiguration @params
```
The `LogonCommand` value is relative to the WindowsSandbox. This code will create a `wsbConfiguration` object.
```text
Name: MyDemo
vGPU : Default
MemoryInMB : 2048
AudioInput : Default
VideoInput : Default
ClipboardRedirection : Default
PrinterRedirection : Disable
Networking : Default
ProtectedClient : Default
LogonCommand : c:\data\demo.cmd
MappedFolders : d:\data -> c:\data [RO:True]
```
You could modify this object as necessary.
```powershell
$new.vGPU = "Enable"
$new.Metadata.Updated = Get-Date
```
The last step is to export the configuration to a `wsb` file.
```powershell
$new | Export-WsbConfiguration -Path d:\wsb\demo.wsb
```
Which will create this file:
```xml
MyDemo
Jeff
A demo WSB configuration
07/10/2022 15:40:54
Enable
2048
Default
Default
Default
Disable
Default
Default
c:\data\demo.cmd
d:\data
c:\data
True
```
I can easily launch this configuration.
```powershell
Start-WindowsSandbox -Configuration D:\wsb\demo.wsb
```
### [New-WsbMappedFolder](docs/New-WsbMappedFolder.md)
Use this command to create a mapped folder object.
```powershell
$map = New-WsbMappedFolder -HostFolder c:\work -SandboxFolder c:\work
```
Once created, you can use this in a new configuration.
```powershell
New-WsbConfiguration -Name work -MappedFolder $map -Description "Work sandbox"
```
### [Export-WSBConfiguration](docs/Export-WsbConfiguration.md)
After you have created a new configuration, you will want to save it to a file.
```powershell
New-WsbConfiguration -Name work -LogonCommand "$wsbScripts\basic.cmd" -MemoryInMB (4096*2) -MappedFolder (New-WsbMappedFolder -HostFolder d:\work -SandboxFolder c:\work) -Description "My work WSB configuration" | Export-WsbConfiguration -Path "$wsbConfigPath\work.wsb"
```
The exported file must have a `.wsb` file extension. Save the file to your `$wsbConfigPath` location.
You should get a file like this:
```xml
work
Jeff
My work WSB configuration
07/18/2022 15:43:24
Default
8192
Default
Default
Default
Default
Default
Default
C:\scripts\windowssandboxtools\wsbScripts\basic.cmd
c:\work
c:\work
False
```
## My Configuration Scripts
My default [configuration script](wsbScripts/demo-config.ps1) takes about 4 minutes to complete. I use the [BurntToast](https://github.com/Windos/BurntToast) module to show a Windows Action Center notification when it is complete.
When you import the module, it will define two global variables. `$wsbConfigPath` points to the location of your wsb files. `$wsbScripts` points to the location of your supporting scripts. By default, these variables will point to directories in the module root. You will most like want to update these variables to point to your location. I set this in my PowerShell profile script.
__You need to verify and update path references if you use any of the configurations or scripts in this module.__
## RoadMap
This is a list of items I'd like to address or handle more efficiently:
+ Look for a way to organize script components used for `LogonCommand` settings.
+ Use a default shared folder that can be a bit more generic.
+ Add a better way to provide or integrate toast notifications.
+ Create a graphical interface for creating configurations.
Feel free to post enhancment suggestions in Issues.