Vm Lab

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.