From 2fb83ada347049bafd7f62028d3bd806c34a9d0f Mon Sep 17 00:00:00 2001 From: guessthepw Date: Sun, 25 Jan 2026 13:35:49 -0500 Subject: [PATCH] Updates documentation for Windows security features README.md: - Add skip parameters example (-SkipVNC, -SkipOllama) - Document VNC password prompt and minimum length - Update requirements to show ISO creation fallbacks CLAUDE.md: - Add Windows script editing section - Add Windows security patterns section - Add Windows testing instructions - Update VNC password minimum from 6 to 8 chars - Document checksum verification for Windows Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 7 +++++++ CLAUDE.md | 37 +++++++++++++++++++++++++++++++++---- README.md | 8 ++++++-- 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 004e5cc..bfb1ac2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ 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.14.1] - 2025-01-25 + +### Changed +- Updated README.md with Windows skip parameters and VNC password info +- Updated CLAUDE.md with Windows script documentation and security patterns +- Fixed VNC password minimum documentation (6 → 8 chars) + ## [0.14.0] - 2025-01-25 ### Security diff --git a/CLAUDE.md b/CLAUDE.md index bba7495..1cf318b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,7 +86,7 @@ This means `./setup_env.sh my-vm` on macOS does everything end-to-end. - `--yes`/`-y` accepts all components without prompting but still allows interactive credential entry - `MISE_GLOBAL_CONFIG_FILE` and `MISE_CONFIG_DIR` are set to prevent OrbStack host-mount config pollution -### Security Patterns +### Security Patterns (macOS/Linux) - **Input validation**: Use `validate_vm_name()`, `validate_vnc_password()`, `validate_safe_input()` for all user inputs - **Safe config loading**: Use `load_config_safely()` which parses key=value pairs without shell execution (never `source`) @@ -96,9 +96,30 @@ This means `./setup_env.sh my-vm` on macOS does everything end-to-end. - **Symlinks**: Check with `[ ! -e path ]` (not `[ ! -L path ]`) to avoid overwriting existing files - **Architecture detection**: Use `detect_architecture()` for portable binary downloads +### Editing setup_env_windows.ps1 + +- PowerShell script for Windows Hyper-V VM creation +- Uses Ubuntu cloud images with cloud-init for automated provisioning +- Supports ARM64 architecture detection for Windows on ARM +- Skip parameters: `-SkipVNC`, `-SkipPostgreSQL`, `-SkipOllama`, `-SkipPlaywright` +- ISO creation fallback chain: oscdimg → WSL genisoimage → IMAPI2 COM +- Log file created at `$env:TEMP\setup_env_windows_.log` + +### Security Patterns (Windows) + +- **Input validation**: Use `Test-GitName`, `Test-GitEmail`, `Test-VMPassword`, `Test-VNCPassword` for all user inputs +- **Config file security**: ACL set to owner-only before writing content (no race condition) +- **Config validation**: Loaded config.env values are re-validated to detect tampering +- **Checksum verification**: Ubuntu image verified against SHA256 checksums from Canonical +- **Cleanup on failure**: `Invoke-Cleanup` removes partial VM, disk, and ISO on errors +- **Hosts file backup**: Created before modification, removed on success, kept on failure +- **Cloud-init ISO**: Contains passwords in plaintext; user reminded to remove after first boot + ### Testing There are no automated tests. To test changes: + +**macOS:** 1. Remove an existing test VM: `orb delete test-sandbox` 2. Run: `./setup_env.sh test-sandbox` 3. Verify provisioning completes @@ -106,13 +127,21 @@ There are no automated tests. To test changes: 5. Test VNC: `ssh test-sandbox@orb -- vnc-start`, then `open vnc://test-sandbox.orb.local:5901` 6. Clean up: `orb delete test-sandbox` +**Windows:** +1. Remove existing test VM: `Stop-VM -Name test-sandbox -Force; Remove-VM -Name test-sandbox -Force` +2. Run: `.\setup_env_windows.ps1 -VMName test-sandbox` +3. Verify provisioning completes (check `/var/log/provision.log` in VM) +4. Test SSH: `ssh -i $env:USERPROFILE\.ssh\id_ed25519_test-sandbox dev@test-sandbox.local` +5. Clean up: `Stop-VM -Name test-sandbox -Force; Remove-VM -Name test-sandbox -Force` + ### Security Considerations -- `config.env` is chmod 600 and gitignored (stores git name/email only, never VNC password) +- `config.env` is chmod 600 / owner-only ACL and gitignored (stores git name/email only, never passwords) - PostgreSQL uses scram-sha-256 for all TCP connections (peer auth for local socket) - The script refuses to run as root inside the VM -- VNC password is required (min 6 chars), validated to block shell metacharacters, never stored -- VNC binds to all interfaces (`-localhost no`) to allow connections from the macOS host — this is intentional for the OrbStack use case and documented in the vnc-start script +- VNC password is required (min 8 chars), validated to block shell metacharacters, never stored +- VNC binds to all interfaces (`-localhost no`) to allow connections from the host — this is intentional and documented - All user inputs are validated before use to prevent command injection - External scripts (mise, ollama) are downloaded to temp files and validated before execution - Host filesystem access is disabled inside the VM for isolation +- Windows: Ubuntu image downloads are verified against SHA256 checksums diff --git a/README.md b/README.md index 7f65a1e..6b8a4c6 100644 --- a/README.md +++ b/README.md @@ -86,18 +86,22 @@ If anything goes wrong: `Remove-VM -Name my-project -Force` then run the script # Customize resources .\setup_env_windows.ps1 -VMName my-sandbox -MemoryGB 16 -DiskGB 100 -CPUs 8 + +# Skip optional components +.\setup_env_windows.ps1 -VMName my-sandbox -SkipVNC -SkipOllama ``` On first run, you'll be prompted for: - Git commit author name and email (saved to `config.env`) -- VM user password (not stored, used for initial setup) +- VM user password (min 8 chars, not stored) +- VNC password if VNC is enabled (min 8 chars, not stored) ### Windows Requirements - Windows 10/11 Pro, Enterprise, or Education (Hyper-V not available on Home) - 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) - Administrator privileges +- One of: Windows ADK, WSL with genisoimage, or Windows 10+ (IMAPI2 fallback) ### Why Hyper-V (not WSL2)?