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

```powershell
# 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

```powershell
# 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

```powershell
# 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

```powershell
# 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

```powershell
# 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

```yaml
#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

```powershell
# 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)

```powershell
# 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](https://docs.microsoft.com/en-us/windows-hardware/get-started/adk-install)

## Usage

### Create Sandbox

```powershell
# 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

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

# Via Hyper-V console
vmconnect localhost <vmname>
```

### Manage Sandbox

```powershell
# 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