VM Lab - cross-OS debugging on any free hypervisor

Disposable local VMs - real macOS, Windows, and Linux, isolated from this host - for cross-OS repro, live process/network/file/memory triage, code-signing checks, and dynamic instrumentation. Works on Parallels, VirtualBox, or VMware with no paid tooling.

The core idea

SSH is the universal substrate. The hypervisor only ever does four things - list, get-ip, power, snapshot - and each of the three has a free way to do all four (providers/*.sh). Everything valuable (the debug toolkit) runs over SSH and is hypervisor-agnostic; it only varies by guest OS and CPU arch. So this skill is a thin swappable provider layer + a big OS/arch-specific debugging core.

On every invocation - ask first, then route

This skill serves three OSes and three providers. Before doing anything, establish:

1. Which guest - macOS, Windows, or Linux? (drives toolkits/<os>.md + SSH gotchas)
2. Which provider - Parallels / VirtualBox / VMware? (drives providers/<name>.sh)
3. Set up fresh, or use an existing guest?
   • Existing → confirm it's in config.local.env, ./ctl.sh <tag> up, ./verify.sh <tag>, go.
   • Fresh → bootstrap/ (Path A one-liner, or Path B unattended), then add to config, verify, snapshot.

If a config.local.env already defines the guest the task needs, skip the questions and use it. Ask only what's genuinely unresolved.

Config & connect

All mutable details live in config.local.env (copy from config.example.env; it's gitignored so your IPs/keys never get shared). Then:

source lib.sh                 # loads config + helpers (rc, rc_sudo, ssh_cmd, prov, ctl)
rc mac 'uname -a'             # run on the macOS guest
rc win 'whoami'              # Windows: auto-wrapped as base64 PowerShell
rc lin 'uname -a'            # Linux
rc_sudo mac 'fs_usage -w'    # sudo on mac/linux (echoes the guest pw via -S)
./verify.sh                   # every guest: tools present + callable, with hints
./ctl.sh doctor               # host preflight: which providers/tools are present here
./ctl.sh win up               # boot + WAIT for sshd; then down|ip|ssh|snaps|vms
push mac ./tool /tmp/tool     # copy to guest (scp); pull mac /tmp/x.pcap ./  to fetch
tun  mac -L 8080:127.0.0.1:8080   # port-forward (MITM/reach a guest service)
./ctl.sh mac reset            # restore the clean snapshot (RESET_SNAPSHOT) - the disposable loop

Guests are tags (mac/win/lin, your choice) with {PROVIDER, OS, ARCH, VMNAME, IP, USER, AUTH, KEY/PW}. Leave IP blank to auto-discover (provider → mDNS → ARP).

Quoting caveat: rc <tag> 'cmd' single-quotes the command, so an embedded ' breaks it. For anything non-trivial (or with quotes) use rcs <tag> <script> [args]

• it pushes a local script, runs it (bash for mac/linux, powershell -File for windows), and cleans up. Or the heredoc form rc mac 'bash -s' <<'EOF' … EOF. run_win (base64) is quote-safe for Windows one-liners.

Inspecting an app (installed or running)

./inspect-app.sh <tag> <app> - one-command triage of any app on a guest: identity, code signing / notarization, hardened-runtime + injectability verdict (tells you whether the Frida path will even work), entitlements, URL schemes, process tree, loaded modules, bundled runtimes. It auto-detects Electron and chains tools/electron-triage.sh, which maps the renderer↔main attack surface - exposeInMainWorld bridges, .handle("…") IPC channels, webPreferences security flags (contextIsolation/sandbox/nodeIntegration), and privileged custom protocols - all without node (a pure-python tools/asar.py extracts the asar on the guest).

./inspect-app.sh mac Claude        # macOS: codesign/entitlements/schemes + electron map
./inspect-app.sh lin firefox       # linux: dpkg/rpm/flatpak + systemd + maps
./inspect-app.sh win Claude        # windows: uninstall-registry + signature + modules

Per-OS logic is in tools/inspect-<os>.{sh,ps1}; asar.py is a reusable standalone Electron extractor (python3 tools/asar.py app.asar --list).

Fresh guest → SSH (bootstrap)

A pristine guest has no sshd/key, and only VirtualBox can type into the console headlessly. Two paths (Path B detailed in bootstrap/unattended.md):

• Path A - one-line paste: paste bootstrap/<os>.{sh,ps1} into the guest console once (a human is most reliable here; some GUI consoles mangle synthetic input), then everything is over SSH.
• Path B - unattended/seed (best for VirtualBox/VMware): bake sshd+key in at install via cloud-init / autounattend.xml (bootstrap/unattended.md). After it connects: pin/blank the IP in config, ./verify.sh <tag>, then snapshot so you never bootstrap again. You supply ISOs; bootstrap/unattended.md lists official sources and can seed them.

Run commands reliably over SSH - per OS

• macOS (toolkits/macos.md): no timeout; bound live captures with background+sleep+kill -INT (never -9); eslogger needs a pty (script) or it shows 0 events.
• Windows (toolkits/windows.md): run_win sends PowerShell as UTF-16LE base64 and strips CLIXML noise; structured output → write-to-file-then-read; cmd one-liners are reliable.
• Linux (toolkits/linux.md): the easy one - one shell, real timeout, real signals; rc_sudo for root.

Toolkits (task → tool matrix + install recipes)

Each toolkits/<os>.md has the full matrix and arch-forked install steps:

• macOS/arm64 - built-ins first (ps, eslogger, lsof, nettop, tcpdump, vmmap, codesign, sample, log); CLT for otool/nm; optional Frida. VM caveat: powermetrics needs --samplers tasks; dtruss SIP-blocked.
• Windows/arm64|x64 - native cmdlets first; add only autorunsc/handle/ sigcheck/procdump/Procmon; optional cdb. VM caveat: wpr fails (0x80070032) → use logman/Procmon. Pick ARM64 vs x64 downloads by ARCH.
• Linux/x64|arm64 - apt/dnf/pacman install everything: strace, bpftrace, perf, gdb, ss, lsof, tcpdump, auditd. VM caveat: perf hardware counters usually unavailable → software events only.

Maintainable & self-remembering

When you learn a new environment quirk, install recipe, or gotcha, append it to LEARNINGS.md (dated, tagged by OS/arch/provider) - that file travels with the repo, so the knowledge compounds across sessions and users instead of living in one machine's memory. Re-run ./verify.sh anytime to re-prove every tool is callable.

Notes

• Safety - the default SSH_OPTS disable host-key checking (right for disposable, re-snapshotted VMs; removes MITM protection). Never point this at a machine you care about; override SSH_OPTS in config for anything non-throwaway. config.local.env is sourced as shell - only use configs you trust.
• Disposable - installing tools, killing processes, editing config, rebooting are all fair game; a snapshot restore recovers anything. Take a clean snapshot right after bootstrap.
• No paid CLIs: Parallels needs only free prlctl list; VirtualBox's VBoxManage is fully free; VMware Fusion/Workstation are free for personal use. The provider layer degrades to SSH-based fallbacks when a native verb is gated.