diff --git a/CHANGELOG.md b/CHANGELOG.md index 49855e7..074d5f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.12.0] - 2025-01-25 + +### Added +- Python runtime management via mise (alongside Node.js, Erlang, Elixir) +- `WINDOWS_PLAN.md` documenting Hyper-V implementation strategy and security rationale + +### Fixed +- Tidewave CLI download URL (now uses correct `tidewave_app` repo with musl binaries) + +### Changed +- Python is now a selectable component managed by mise instead of system apt + ## [0.11.0] - 2025-01-25 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 0715c21..bba7495 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,6 +31,7 @@ This repository provides scripts for creating isolated development sandboxes for ``` setup_env.sh - macOS script (OrbStack host mode + Linux VM provisioning) setup_env_windows.ps1 - Windows script (Hyper-V with cloud-init) +WINDOWS_PLAN.md - Windows implementation plan and security rationale config.env.example - Example credentials file config.env - User credentials (gitignored, created on first run) .gitignore - Ignores config.env diff --git a/WINDOWS_PLAN.md b/WINDOWS_PLAN.md new file mode 100644 index 0000000..66975e4 --- /dev/null +++ b/WINDOWS_PLAN.md @@ -0,0 +1,257 @@ +# 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 (.local) +4. Cloud-init runs setup_env.sh internally +5. Display connection instructions +``` + +## Cloud-Init Configuration + +```yaml +#cloud-config +hostname: +users: + - name: dev + sudo: ALL=(ALL) NOPASSWD:ALL + ssh_authorized_keys: + - +packages: + - openssh-server + - curl + - git +write_files: + - path: /tmp/setup_env.sh + content: +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 -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_ dev@.local + +# Via Hyper-V console +vmconnect localhost +``` + +### Manage Sandbox + +```powershell +# Stop VM +Stop-VM -Name + +# Start VM +Start-VM -Name + +# Get VM IP +(Get-VM -Name | Get-VMNetworkAdapter).IPAddresses + +# Delete VM completely +Stop-VM -Name -Force +Remove-VM -Name -Force +Remove-Item -Path "$env:ProgramData\HyperV-DevSandbox\VMs\" -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