secure_agent_envs/WINDOWS_PLAN.md

Windows Hyper-V Implementation Plan

This document describes the plan for implementing secure, isolated development sandboxes on Windows using Hyper-V instead of WSL2.

Why Hyper-V Over WSL2

WSL2 Security Limitations

Issue	Impact
Shared kernel	All WSL2 instances share Microsoft's Linux kernel
Host filesystem access	/mnt/c mounted by default, can access Windows files
Bidirectional execution	Linux can launch Windows executables
Firewall bypass	WSL2 outbound traffic bypasses Windows firewall rules
Process visibility	Windows has limited visibility into WSL2 processes
Credential exposure	Linux processes can potentially access Windows credentials

CVE History

• CVE-2024-20681: Local privilege escalation to SYSTEM via WSL
• CVE-2025-9074: Container escape via WSL2 filesystem sharing
• CVE-2025-53788: Undisclosed flaw in WSL/host communication

Hyper-V Isolation Model

Feature	Benefit
Separate kernel	Each VM runs its own Linux kernel
Complete filesystem isolation	No access to Windows files by default
Own network stack	Separate IP, no firewall bypass
No Windows integration	Cannot launch Windows programs
Snapshot support	Can checkpoint and restore VM state
Hardware isolation	Uses VT-x/AMD-V virtualization

Implementation Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Windows Host                                │
│                                                                  │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐ │
│  │ setup_env_windows.ps1│    │        Hyper-V Manager          │ │
│  │                     │    │                                  │ │
│  │ • Check prereqs     │───▶│  ┌──────────────────────────┐  │ │
│  │ • Download image    │    │  │      Ubuntu VM           │  │ │
│  │ • Create cloud-init │    │  │                          │  │ │
│  │ • Provision VM      │    │  │  • Isolated filesystem   │  │ │
│  │ • Configure network │    │  │  • Own network (NAT)     │  │ │
│  └─────────────────────┘    │  │  • Claude Code + tools   │  │ │
│                              │  │  • No Windows access     │  │ │
│                              │  └──────────────────────────┘  │ │
│                              └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Script Workflow

Phase 1: Prerequisites Check

# Verify environment
1. Check Administrator privileges
2. Check Windows edition (Pro/Enterprise/Education required)
3. Check Hyper-V enabled
4. Check for existing VM (handle -Force flag)
5. Find suitable network switch

Phase 2: Configuration

# Collect credentials
1. Load config.env if exists (git name/email)
2. Prompt for missing values
3. Prompt for VM password (not stored)
4. Generate SSH key pair for VM access

Phase 3: Image Preparation

# Prepare Ubuntu cloud image
1. Download Ubuntu cloud image (VHDX format)
2. Cache in $env:ProgramData\HyperV-DevSandbox\Images
3. Copy and resize for new VM
4. Generate cloud-init ISO with:
   - User account configuration
   - SSH key injection
   - Package installation
   - Setup script embedding

Phase 4: VM Creation

# Create Hyper-V VM
1. Create Generation 2 VM (UEFI)
2. Configure resources (CPU, RAM, disk)
3. Disable Secure Boot (for Ubuntu)
4. Attach cloud-init ISO
5. Disable integration services for isolation
6. Enable nested virtualization (for Docker)

Phase 5: Provisioning

# Start and provision
1. Start VM
2. Wait for IP assignment
3. Add to hosts file (<vmname>.local)
4. Cloud-init runs setup_env.sh internally
5. Display connection instructions

Cloud-Init Configuration

#cloud-config
hostname: <vmname>
users:
  - name: dev
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - <generated-public-key>
packages:
  - openssh-server
  - curl
  - git
write_files:
  - path: /tmp/setup_env.sh
    content: <base64-encoded-script>
runcmd:
  - bash /tmp/setup_env.sh --non-interactive --yes

Security Hardening

VM Configuration

# Disable integration services for maximum isolation
Disable-VMIntegrationService -Name "Guest Service Interface"
Disable-VMIntegrationService -Name "Heartbeat"
# Keep Time Synchronization and Shutdown for usability

Network Isolation Options

1. NAT (Default): VM can access internet, isolated from LAN
2. Internal Only: VM can only communicate with host
3. Private: Completely isolated network

Firewall Rules (Optional)

# Allow SSH access only
New-NetFirewallRule -Name "HyperV-SSH-$VMName" `
    -Direction Inbound -LocalPort 22 -Protocol TCP `
    -RemoteAddress <VM-IP> -Action Allow

Requirements

Windows Edition

• Windows 10/11 Pro
• Windows 10/11 Enterprise
• Windows 10/11 Education
• Windows Server 2016+

Not supported: Windows 10/11 Home (no Hyper-V)

Hardware

• 64-bit processor with SLAT (Second Level Address Translation)
• VM Monitor Mode extensions (VT-x on Intel, AMD-V on AMD)
• Minimum 4 GB RAM (8+ GB recommended)
• BIOS/UEFI virtualization enabled

Software

• Hyper-V enabled: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
• Windows ADK (for cloud-init ISO creation): Download

Usage

Create Sandbox

# Basic usage (run as Administrator)
.\setup_env_windows.ps1 -VMName my-project

# With custom resources
.\setup_env_windows.ps1 -VMName my-project -MemoryGB 16 -DiskGB 100 -CPUs 8

# Replace existing VM
.\setup_env_windows.ps1 -VMName my-project -Force

Connect to Sandbox

# Via SSH (recommended)
ssh -i $env:USERPROFILE\.ssh\id_ed25519_<vmname> dev@<vmname>.local

# Via Hyper-V console
vmconnect localhost <vmname>

Manage Sandbox

# Stop VM
Stop-VM -Name <vmname>

# Start VM
Start-VM -Name <vmname>

# Get VM IP
(Get-VM -Name <vmname> | Get-VMNetworkAdapter).IPAddresses

# Delete VM completely
Stop-VM -Name <vmname> -Force
Remove-VM -Name <vmname> -Force
Remove-Item -Path "$env:ProgramData\HyperV-DevSandbox\VMs\<vmname>" -Recurse -Force

Comparison: OrbStack vs Hyper-V

Feature	OrbStack (macOS)	Hyper-V (Windows)
Host OS	macOS only	Windows only
Setup complexity	Low	Medium
Isolation	Full VM	Full VM
DNS	*.orb.local auto	Manual hosts file
SSH	Automatic	Key-based
Filesystem sharing	Configurable	Disabled by default
Performance	Near-native	Near-native
Nested virtualization	Yes	Yes

Known Limitations

1. Windows ADK Required: Cloud-init ISO creation requires oscdimg from Windows ADK
2. Manual DNS: No automatic DNS like OrbStack's *.orb.local
3. Key Management: SSH keys generated per-VM, stored in user's .ssh folder
4. No Clipboard Sharing: Disabled for security (can be enabled if needed)
5. Generation 2 Only: Uses UEFI, no legacy BIOS support

Future Improvements

• Add option for WSL2 (for users who prefer convenience over security)
• Implement automatic DNS via Windows hosts file or local DNS server
• Add PowerShell ISO creation without Windows ADK dependency
• Support for VM templates/checkpoints
• Integration with Windows Terminal for easy access
• Optional WinRM configuration for PowerShell remoting