DOCSEARCHbyAlgolia
Submit Docs

PyWinSandbox

repository·master·Indexed 41 days ago

https://github.com/karkason/pywinsandbox

A Python library for programmatically creating and controlling Windows Sandbox instances. It features an RPyC interface for executing commands within the sandbox, a CLI (wsb/winsandbox) for interactive sessions and configuration, and a Windows shell extension for running executables via the right-click context menu.

Tokens
1.4K
Snippets
7
Records
8
Agent score
2%

What's inside PyWinSandbox

  1. Create and control a Windows Sandbox with Python

    master

    Use the winsandbox library to programmatically create Windows Sandbox instances. Once created, you can control the sandbox using an rpyc interface, which allows you to execute commands within the sandbox environment as if they were local Python modules.

    Basic Usage

    import winsandbox

sandbox = winsandbox.new_sandbox()
sandbox.rpyc.modules.subprocess.run('explorer .')

    Advanced Configuration

    Map a local directory to the Sandbox Desktop

    Directories provided via folder_mappers are mapped under the sandbox's Desktop.

    sandbox = winsandbox.new_sandbox(folder_mappers=[winsandbox.FolderMapper(r'C:\users\public')])
# The folder is now accessible at %userprofile%\Desktop\public

    Create an offline sandbox with a logon script

    Disable networking and specify a command to run immediately upon logon.

    sandbox = winsandbox.new_sandbox(networking=False, logon_script="explorer .")

    Configure RAM allocation

    Specify the amount of memory in MB.

    sandbox = winsandbox.new_sandbox(memory_mb=8192)
    import winsandbox

sandbox = winsandbox.new_sandbox()
sandbox.rpyc.modules.subprocess.run('explorer .')

  2. Install PyWinSandbox

    master

    You can install PyWinSandbox using pip. Ensure that Windows Sandbox is enabled in your Windows system settings before proceeding.

    To install the latest stable version:

    pip3 install -U pywinsandbox

    To install directly from the GitHub repository:

    pip3 install -U git+git://github.com/karkason/pywinsandbox.git

  3. Interactive mode with IPython

    master

    When running with the --interactive flag, the CLI embeds an IPython shell. Inside this shell, a sandbox object is automatically available, allowing you to programmatically control the sandbox instance using the winsandbox API.

    # After running 'winsandbox --interactive', you can use the sandbox object in the shell:
sandbox.some_method()

  4. Use the `wsb` / `winsandbox` CLI

    master

    The wsb and winsandbox commands are aliases for the command-line interface.

    Interactive Session

    Spawns an interactive sandbox session with an IPython shell:

    wsb -i

    Spawn Offline Sandbox with Command

    Spawns an "offline" Windows Sandbox instance and executes a specific command:

    wsb -s "explorer C:\windows\system32"
    # Create an interactive sandbox session. Spawns an IPython shell.
wsb -i

# Spawn an "offline" Windows Sandbox instance, with a command line.
wsb -s "explorer C:\windows\system32"

  5. Manage the Windows Shell Extension

    master

    A shell extension is available to allow sandboxing executables via the Windows right-click context menu. Note: These commands must be run with Administrator privileges.

    To register the shell extension:

    wsb -r

    To unregister the shell extension:

    wsb -u
    # Register the shell extension
wsb -r

# Unregister the shell extension
wsb -u

  6. Reference: winsandbox CLI flags

    master

    The following flags are available when using the winsandbox / wsb command:

    FlagLong FormDescription
    -i--interactiveEnables interactive mode. Spawns an IPython shell where a sandbox object is available for control.
    --no-vgpu--no-vgpuDisables the virtual GPU.
    -s--logon-scriptPath to a logon script for non-interactive (ipy) sandboxes.
    -f--folderSpecifies a folder to map into the sandbox. This flag can be used multiple times to map multiple folders.
    -r--registerRegisters Windows Shell extensions to allow opening/running executables in the sandbox via the right-click menu.
    -u--unregisterUnregisters the Windows Shell extensions.

  7. Register or Unregister Windows Shell extensions

    master

    You can add context menu options to Windows executable files (.exe) to run them directly inside a sandbox. This requires running the command with Administrator privileges.

    • Registering: Adds 'Open Sandboxed' and 'Run Sandboxed' (with --run flag) to the shell context menu.
    • Unregistering: Removes these entries from the registry.
    # Register shell extensions (requires Admin)
winsandbox --register

# Unregister shell extensions (requires Admin)
winsandbox --unregister

  8. Use the winsandbox CLI to launch a sandbox

    master

    The winsandbox (or wsb) command-line interface allows you to spawn Windows Sandbox instances with specific configurations such as folder mapping, logon scripts, and interactive modes.

    Note: Some operations, specifically registering shell extensions, require Administrator privileges.

    # Example: Launch a sandbox with a specific folder mapped and a logon script
sandbox --folder C:\Users\Me\Documents --logon-script setup.ps1

# Example: Launch in interactive mode with an embedded IPython shell
sandbox --interactive

# Example: Launch without a virtual GPU
sandbox --no-vgpu