Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(lume): automate SIP changes through macOS Recovery (#2165)

Francesco Bonaccia56193f93e87
diff --git a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx
index 51ad10ac6b..29507d286a 100644
--- a/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx
+++ b/docs/content/docs/concepts/how-lume-unattended-setup-works.mdx
@@ -29,6 +29,13 @@ particular macOS release exposes. Disk setup writes the desired guest state
directly and keeps the verification step small: Lume checks that the guest
boots and accepts SSH.
+## Boot policy changes use Recovery
+
+Offline setup can change guest files, but it cannot sign Apple silicon boot
+policy. SIP changes therefore use the VM's paired Recovery environment and a
+normal boot verification. Read [How SIP works in Lume
+VMs](/concepts/how-sip-works-in-lume-vms) for the policy model.
+
## Presets and images
The `tahoe` and `sequoia` presets use the same offline patcher. Tahoe is the
@@ -44,4 +51,5 @@ required for unattended setup.
- [Create your first local macOS VM](/tutorials/create-your-first-lume-vm)
- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm)
+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)
- [Lume CLI reference](/reference/lume/cli-reference)
diff --git a/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx
new file mode 100644
index 0000000000..28615c19e3
--- /dev/null
+++ b/docs/content/docs/concepts/how-sip-works-in-lume-vms.mdx
@@ -0,0 +1,80 @@
+---
+title: How SIP works in Lume VMs
+description: Understand signed LocalPolicy state, paired Recovery, and why Lume verifies SIP after reboot.
+---
+
+System Integrity Protection (SIP) on an Apple silicon VM is part of a signed
+boot policy. Changing files on the macOS Data volume cannot change that policy.
+
+## SIP state is a signed LocalPolicy
+
+Apple silicon stores SIP configuration in a LocalPolicy signed by the Secure
+Enclave. Virtualization.framework provides the corresponding security service
+for a macOS VM.
+
+The policy belongs to a larger paired state:
+
+- `disk.img` contains macOS, personalized boot files, and Recovery;
+- `nvram.bin` contains auxiliary security and anti-replay state; and
+- the VM configuration identifies the virtual hardware that boots them.
+
+Copying or editing one part does not mint a valid policy for another VM.
+
+## Offline setup and SIP use different paths
+
+Lume's unattended setup mounts the Data volume and writes account, SSH,
+autologin, and power settings. Those settings are ordinary guest files, so an
+offline patcher can prepare them without driving Setup Assistant.
+
+SIP is different because the policy must be signed from the VM's paired
+Recovery environment. Editing `disk.img` or patching bytes in `nvram.bin`
+cannot produce a valid signature.
+
+## Why `lume sip` uses Recovery
+
+`lume sip` coordinates three VM sessions:
+
+1. A normal boot checks that the requested administrator account works over
+ SSH.
+2. A Recovery boot opens Terminal over a temporary VNC session and runs
+ `csrutil enable` or `csrutil disable`.
+3. A final normal boot runs `csrutil status` over SSH.
+
+During Recovery, Lume checks the named account prompt and reads the terminal
+result with OCR before it stops the VM. Tahoe Recovery does not always halt
+after its shutdown command, so Lume can stop that exact `lume run` process
+after a grace period. It waits for the VM to report `stopped` before the final
+boot.
+
+## Verification happens after reboot
+
+The Recovery message confirms that `csrutil` accepted the policy change. The
+normal boot proves that the VM can use the new policy.
+
+Lume accepts only the canonical top-level status:
+
+```text
+System Integrity Protection status: enabled.
+```
+
+or:
+
+```text
+System Integrity Protection status: disabled.
+```
+
+A customized policy can list enabled and disabled components at the same time.
+Lume rejects that output instead of inferring a state from one component line.
+
+## Clones keep paired files together
+
+`lume clone` copies the VM disk and auxiliary storage as a pair. This is the
+supported way to reproduce a prepared seed. Copying only `disk.img` loses the
+matching security state; copying only `nvram.bin` loses the matching boot
+files.
+
+## Related pages
+
+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)
+- [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works)
+- [Lume limits](/reference/lume/limits#sip-automation)
diff --git a/docs/content/docs/concepts/index.mdx b/docs/content/docs/concepts/index.mdx
index 44cf494eff..4f317ee608 100644
--- a/docs/content/docs/concepts/index.mdx
+++ b/docs/content/docs/concepts/index.mdx
@@ -5,4 +5,4 @@ description: "Understand the design ideas behind Cua and how its main pieces fit
Use these pages when you want the model behind Cua rather than a step-by-step guide or API table. They explain what computer use means in Cua, how Cua Driver keeps the desktop usable while it acts, and how Cua Sandbox gives an agent a disposable computer.
-Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) when you need the local VM setup model.
+Start with [What is computer use?](/concepts/what-is-computer-use) for the basic model. Read [Best-effort background](/concepts/the-no-foreground-contract) to understand Cua Driver's default behavior on a shared machine, then [Capture and delivery modalities](/concepts/capture-and-delivery-modalities) for the action axes. Read [How sandboxes work](/concepts/how-sandboxes-work) when you need the model for disposable computers. Read [How Lume prepares vanilla macOS VMs](/concepts/how-lume-unattended-setup-works) for the local VM setup model, and [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms) for signed boot-policy changes.
diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.json
index f4113c0ce2..55e4f5d72f 100644
--- a/docs/content/docs/concepts/meta.json
+++ b/docs/content/docs/concepts/meta.json
@@ -1 +1 @@
-{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work", "how-lume-unattended-setup-works"] }
+{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-sandboxes-work", "how-lume-unattended-setup-works", "how-sip-works-in-lume-vms"] }
diff --git a/docs/content/docs/how-to-guides/lume/change-sip.mdx b/docs/content/docs/how-to-guides/lume/change-sip.mdx
new file mode 100644
index 0000000000..615ea0791b
--- /dev/null
+++ b/docs/content/docs/how-to-guides/lume/change-sip.mdx
@@ -0,0 +1,111 @@
+---
+title: Change SIP on a macOS VM
+description: Disable or enable System Integrity Protection from paired macOS Recovery and verify the result.
+---
+
+Use `lume sip` to change System Integrity Protection (SIP) on a stopped macOS
+VM. Lume runs `csrutil` in the VM's paired Recovery environment and verifies
+the result after a normal boot.
+
+For the policy model behind this workflow, read [How SIP works in Lume
+VMs](/concepts/how-sip-works-in-lume-vms).
+
+## Before you start
+
+The VM must:
+
+- run macOS;
+- be stopped;
+- have a working administrator account; and
+- have Remote Login enabled.
+
+VMs created with Lume's unattended setup meet these requirements. Their
+initial username and password are both `lume`.
+
+Install the optional Recovery VNC driver:
+
+```bash
+python3 -m pip install --user vncdotool
+```
+
+Recovery input currently supports administrator passwords made from lowercase
+ASCII letters, digits, and hyphens. The Recovery password prompt must name the
+account passed with `--admin-user`.
+
+## Disable SIP
+
+With the default `lume` account, run:
+
+```bash
+lume sip off macos-tahoe
+```
+
+Confirm the change when prompted. Lume validates the account, changes the
+policy in Recovery, boots normally to run `csrutil status`, and leaves the VM
+stopped. A successful run ends with:
+
+```text
+System Integrity Protection status: disabled.
+SIP is disabled.
+```
+
+For another administrator account, enter its password without exposing it in
+the process arguments:
+
+```bash
+lume sip off macos-tahoe \
+ --admin-user admin \
+ --admin-password-stdin
+```
+
+For non-interactive use, provide confirmation with `--yes` so the password is
+the only line read from standard input:
+
+```bash
+printf '%s\n' "$LUME_ADMIN_PASSWORD" | \
+ lume sip off macos-tahoe \
+ --admin-user admin \
+ --admin-password-stdin \
+ --yes
+```
+
+## Enable SIP
+
+Run the same command with `on`:
+
+```bash
+lume sip on macos-tahoe \
+ --admin-user admin \
+ --admin-password-stdin
+```
+
+A successful run ends with the canonical enabled status and leaves the VM
+stopped.
+
+## Prepare a reusable SIP-disabled VM
+
+Change SIP on a stopped seed, then clone it:
+
+```bash
+lume sip off macos-tahoe-seed --yes
+lume clone macos-tahoe-seed macos-tahoe-worker-001
+```
+
+Lume copies `disk.img` and `nvram.bin` together. Do not replace either file
+independently because the signed policy, personalized boot files, and
+anti-replay state belong to one paired VM state.
+
+Boot a worker and inspect its policy when you need an extra check:
+
+```bash
+lume run --no-display macos-tahoe-worker-001
+lume ssh macos-tahoe-worker-001 'csrutil status'
+lume stop macos-tahoe-worker-001
+```
+
+## Related pages
+
+- [How SIP works in Lume VMs](/concepts/how-sip-works-in-lume-vms)
+- [Manage local Lume VMs](/how-to-guides/lume/manage-vms)
+- [Lume limits](/reference/lume/limits#sip-automation)
+- [Lume CLI reference](/reference/lume/cli-reference#lume-sip)
diff --git a/docs/content/docs/how-to-guides/lume/install-lume.mdx b/docs/content/docs/how-to-guides/lume/install-lume.mdx
index a56d41269f..400baecb53 100644
--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx
+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx
@@ -52,6 +52,7 @@ You can also download the `lume.pkg.tar.gz` archive from the [latest release](ht
- [Create your first local VM](/tutorials/create-your-first-lume-vm): follow the Tahoe happy path from IPSW to SSH.
- [Create a vanilla Tahoe VM](/how-to-guides/lume/create-vanilla-vm): create, run, inspect, and remove a local VM.
- [Manage local VMs](/how-to-guides/lume/manage-vms): share files, use storage locations, and clone disks.
+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip): change the signed policy from paired Recovery.
- [Serve the Lume API](/how-to-guides/lume/serve-api): run the local HTTP API for tools and scripts.
- [Use Lume with MCP](/how-to-guides/lume/use-mcp-server): connect an AI client to local VM tools.
- [Lume CLI reference](/reference/lume/cli-reference): inspect every command and option.
diff --git a/docs/content/docs/how-to-guides/lume/manage-vms.mdx b/docs/content/docs/how-to-guides/lume/manage-vms.mdx
index ed0e860686..637b742fc5 100644
--- a/docs/content/docs/how-to-guides/lume/manage-vms.mdx
+++ b/docs/content/docs/how-to-guides/lume/manage-vms.mdx
@@ -102,3 +102,6 @@ lume delete macos-tahoe-backup
macOS VM disks can be sparse. The configured capacity and the host space used
by the disk can therefore differ.
+
+To disable or enable System Integrity Protection, follow [Change SIP on a
+macOS VM](/how-to-guides/lume/change-sip).
diff --git a/docs/content/docs/how-to-guides/lume/meta.json b/docs/content/docs/how-to-guides/lume/meta.json
index f5fd69296b..a59cb1648b 100644
--- a/docs/content/docs/how-to-guides/lume/meta.json
+++ b/docs/content/docs/how-to-guides/lume/meta.json
@@ -1 +1 @@
-{ "title": "Lume", "pages": ["install-lume", "create-vanilla-vm", "manage-vms", "serve-api", "use-mcp-server"] }
+{ "title": "Lume", "pages": ["install-lume", "create-vanilla-vm", "manage-vms", "change-sip", "serve-api", "use-mcp-server"] }
diff --git a/docs/content/docs/reference/lume/cli-reference.mdx b/docs/content/docs/reference/lume/cli-reference.mdx
index 7dc759e7ec..f29ec49041 100644
--- a/docs/content/docs/reference/lume/cli-reference.mdx
+++ b/docs/content/docs/reference/lume/cli-reference.mdx
@@ -50,24 +50,6 @@ Create a new virtual machine
| `--debug` | false | Compatibility flag; ignored by offline setup. |
| `--no-display` | false | Compatibility flag; offline setup verifies headlessly. |
-### lume clone
-
-Clone an existing virtual machine
-
-**Arguments:**
-
-| Name | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `<name>` | String | Yes | Name of the source VM |
-| `<new-name>` | String | Yes | Name for the cloned VM |
-
-**Options:**
-
-| Name | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| `--source-storage` | String | - | Source VM storage location |
-| `--dest-storage` | String | - | Destination VM storage location |
-
### lume run
Run a virtual machine
@@ -135,8 +117,37 @@ Delete a virtual machine
| ---- | ------- | ----------- |
| `--force` | false | Force deletion without confirmation |
+### lume clone
+
+Clone an existing virtual machine
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<name>` | String | Yes | Name of the source VM |
+| `<new-name>` | String | Yes | Name for the cloned VM |
+
+**Options:**
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--source-storage` | String | - | Source VM storage location |
+| `--dest-storage` | String | - | Destination VM storage location |
+
## VM Information and Configuration
+### lume ls
+
+List virtual machines
+
+**Options:**
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `-f, --format` | String | text | Output format (json or text) |
+| `--storage` | String | - | Filter by storage location name |
+
### lume get
Get detailed information about a virtual machine
@@ -174,18 +185,17 @@ Set new values for CPU, memory, and disk size of a virtual machine
| `--display` | String | - | New display resolution |
| `--storage` | String | - | VM storage location to use |
-### lume ls
+## Image Management
-List virtual machines
+### lume images
+
+List available macOS images from local cache
**Options:**
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
-| `-f, --format` | String | text | Output format (json or text) |
-| `--storage` | String | - | Filter by storage location name |
-
-## Image Management
+| `--organization` | String | trycua | Organization to list images for |
### lume pull
@@ -235,15 +245,32 @@ Push a macOS VM to an OCI-compatible registry
| `--dry-run` | false | Prepare files without uploading |
| `--reassemble` | true | Verify integrity by reassembling chunks |
-### lume images
+### lume convert
-List available macOS images from local cache
+Convert a legacy Lume image to OCI-compliant format
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<source-image>` | String | Yes | Source image to convert (legacy format, for example macos-tahoe:latest) |
+| `<target-image>` | String | Yes | Target image to push in OCI format (name:tag) |
**Options:**
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
-| `--organization` | String | trycua | Organization to list images for |
+| `--additional-tags` | [String] | - | Additional tags for the OCI image |
+| `--registry` | String | ghcr.io | Registry to pull from and push to |
+| `--organization` | String | trycua | Registry organization |
+
+**Flags:**
+
+| Name | Default | Description |
+| ---- | ------- | ----------- |
+| `--verbose` | false | Enable verbose logging |
+| `--dry-run` | false | Prepare files without uploading |
+| `--single-layer` | false | Push one kubelet-compatible disk layer |
### lume ipsw
@@ -253,7 +280,7 @@ Get macOS restore image IPSW URL
Remove cached images
-## Guest Access and Setup
+## Guest Access and Security
### lume ssh
@@ -301,17 +328,36 @@ Prepare unattended macOS setup
| `--no-display` | false | Compatibility flag; offline setup verifies headlessly |
| `--debug` | false | Compatibility flag; ignored by offline setup |
-## Configuration and Server
+### lume sip
-### lume serve
+Enable or disable System Integrity Protection on a macOS VM
-Start the VM management server
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<state>` | String | Yes | Desired SIP state: on or off |
+| `<name>` | String | Yes | Name of the virtual machine |
**Options:**
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
-| `--port` | Int | 7777 | Port to listen on |
+| `--admin-user` | String | lume | Administrator username in the guest |
+| `--admin-password` | String | - | Administrator password in the guest; prefer --admin-password-stdin |
+| `--screenshot-dir` | String | - | Directory for Recovery framebuffer screenshots |
+| `--vnc-port` | Int | 5999 | Port for the temporary Recovery VNC server |
+| `--storage` | String | - | VM storage location |
+| `--timeout` | Int | 900 | Overall timeout in seconds |
+
+**Flags:**
+
+| Name | Default | Description |
+| ---- | ------- | ----------- |
+| `-y, --yes` | false | Skip the interactive confirmation prompt |
+| `--admin-password-stdin` | false | Read one administrator-password line from standard input without echo |
+
+## Configuration and Server
### lume config
@@ -331,6 +377,16 @@ Get or set lume configuration
- `lume config cache enable` - Enable image caching
- `lume config cache disable` - Disable image caching
+### lume serve
+
+Start the VM management server
+
+**Options:**
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--port` | Int | 7777 | Port to listen on |
+
### lume logs
View lume serve logs
@@ -366,6 +422,24 @@ Check for a Lume update and optionally apply it
| `--apply` | false | Apply the update by re-running the official installer |
| `--json` | false | Emit the structured update-state payload as JSON |
+## Developer Tools
+
+### lume dump-docs
+
+Output CLI and API documentation as JSON for tooling and integrations
+
+**Options:**
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--type` | String | cli | Documentation type: cli, api, or all |
+
+**Flags:**
+
+| Name | Default | Description |
+| ---- | ------- | ----------- |
+| `--pretty` | false | Pretty-print JSON output |
+
## Global Options
These options are available for all commands:
diff --git a/docs/content/docs/reference/lume/limits.mdx b/docs/content/docs/reference/lume/limits.mdx
index d7bcc59b12..8e56435c02 100644
--- a/docs/content/docs/reference/lume/limits.mdx
+++ b/docs/content/docs/reference/lume/limits.mdx
@@ -61,6 +61,21 @@ lume get macos-tahoe
lume ssh macos-tahoe 'id -un'
```
+## SIP automation
+
+- `lume sip` supports stopped macOS VMs only.
+- The VM must have a working administrator account and Remote Login enabled.
+- The optional `vncdotool` package provides Recovery VNC input.
+- Recovery input accepts administrator passwords made from lowercase ASCII
+ letters, digits, and hyphens.
+- The account named by `--admin-user` must match the Recovery password prompt.
+- Tahoe is the currently verified Recovery workflow.
+- The command leaves the VM stopped after a successful policy change.
+- If Recovery does not halt during its grace period, Lume stops that exact run
+ process and requires a normal-boot `csrutil status` verification.
+- Customized SIP policies are rejected because they do not have one canonical
+ enabled or disabled state.
+
## Disk allocation
macOS VM disks use sparse files. The configured disk capacity describes the
diff --git a/libs/lume/README.md b/libs/lume/README.md
index 61dfb00b8b..5c56bc3633 100644
--- a/libs/lume/README.md
+++ b/libs/lume/README.md
@@ -25,3 +25,14 @@ tracked in [#2155](https://github.com/trycua/cua/issues/2155).
To use the other built-in preset, replace `tahoe` with `sequoia` in the
`--unattended` option and choose a matching VM name.
+
+## Optional dependencies
+
+The `lume sip` command uses `vncdotool` to control macOS Recovery over VNC.
+Install it only if you need to enable or disable SIP:
+
+```bash
+pip3 install vncdotool
+```
+
+Other Lume commands do not require this package.
diff --git a/libs/lume/src/Commands/Convert.swift b/libs/lume/src/Commands/Convert.swift
index a232feada3..38aaca7032 100644
--- a/libs/lume/src/Commands/Convert.swift
+++ b/libs/lume/src/Commands/Convert.swift
@@ -9,11 +9,11 @@ struct Convert: AsyncParsableCommand {
under a new name/tag, then removes the temporary local VM.
Example:
- lume convert macos-sequoia:latest trycua/macos-sequoia:latest-oci
+ lume convert macos-tahoe:latest trycua/macos-tahoe:latest-oci
"""
)
- @Argument(help: "Source image to convert (legacy format, e.g. macos-sequoia:latest)")
+ @Argument(help: "Source image to convert (legacy format, e.g. macos-tahoe:latest)")
var sourceImage: String
@Argument(help: "Target image to push in OCI format (format: name:tag)")
diff --git a/libs/lume/src/Commands/Sip.swift b/libs/lume/src/Commands/Sip.swift
new file mode 100644
index 0000000000..bd28dc6dc6
--- /dev/null
+++ b/libs/lume/src/Commands/Sip.swift
@@ -0,0 +1,629 @@
+import ArgumentParser
+import Darwin
+import Foundation
+
+/// `lume sip <on|off> <vm>`
+///
+/// Changes SIP from paired recoveryOS, where Apple permits LocalPolicy
+/// downgrades. Recovery has no supported command channel, so the workflow
+/// drives its Terminal over the VM's transient VNC server and then verifies
+/// the result over SSH after a normal boot.
+struct Sip: AsyncParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "sip", abstract: "Enable or disable System Integrity Protection on a macOS VM",
+ discussion: """
+ Boots a stopped VM normally to validate the admin credentials, then
+ boots paired recoveryOS and runs `csrutil disable` (or `enable`) in
+ Terminal over VNC. After confirming the signed policy result, Lume
+ stops Recovery and boots normally once more to verify the result.
+
+ The VM must already have an admin account and Remote Login enabled.
+ VMs created with unattended setup use lume/lume by default.
+
+ Prefer --admin-password-stdin so the guest password does not appear
+ in the Lume process arguments. --admin-password remains available
+ for interactive convenience but can be observed by other processes.
+
+ Prerequisite: vncdotool (pip3 install vncdotool).
+
+ Examples:
+ lume sip off my-vm --yes
+ printf 'secret\\n' | lume sip on my-vm --yes \\
+ --admin-user alice --admin-password-stdin
+ """)
+
+ enum State: String, ExpressibleByArgument, Sendable { case on, off }
+
+ @Argument(help: "Desired SIP state: on or off") var state: State
+
+ @Argument(help: "Name of the virtual machine", completion: .custom(completeVMName)) var name: String
+
+ @Flag(name: [.short, .long], help: "Skip the interactive confirmation prompt") var yes: Bool = false
+
+ @Option(name: .customLong("admin-user"), help: "Admin username in the guest") var adminUser: String = "lume"
+
+ @Option(
+ name: .customLong("admin-password"),
+ help: "Admin password in the guest. Prefer --admin-password-stdin; defaults to lume") var adminPassword: String?
+
+ @Flag(
+ name: .customLong("admin-password-stdin"), help: "Read one admin-password line from standard input without echo"
+ ) var adminPasswordStdin: Bool = false
+
+ @Option(name: .customLong("screenshot-dir"), help: "Save step-by-step framebuffer PNGs here for debugging")
+ var screenshotDir: String?
+
+ @Option(name: .customLong("vnc-port"), help: "TCP port for the transient recovery VNC server")
+ var vncPort: Int = 5999
+
+ @Option(name: .customLong("storage"), help: "VM storage location") var storage: String?
+
+ @Option(help: "Overall timeout in seconds") var timeout: Int = 900
+
+ @MainActor func run() async throws {
+ TelemetryClient.shared.record(event: "lume_sip")
+ guard timeout > 0 else { throw SipError.invalidTimeout(timeout) }
+
+ let controller = LumeController()
+ let details = try loadInitialDetails(controller: controller)
+ try Self.validateInitialState(details, expectedName: name)
+
+ if !yes { try confirmChange() }
+
+ let password = try resolvedAdminPassword()
+ try Self.validateVNCPasswordCharacters(password)
+ let vncdo = try Self.requireVNCExecutable(VNCDriver.locateVncdo())
+ Logger.info("Using vncdotool", metadata: ["path": vncdo])
+
+ let selfExecutable = resolvedSelfExecutable()
+ let deadline = SipDeadline(seconds: timeout)
+
+ try await preflightCredentials(
+ controller: controller, executable: selfExecutable, password: password, deadline: deadline)
+ try await changePolicyInRecovery(
+ controller: controller, executable: selfExecutable, vncdo: vncdo, password: password, deadline: deadline)
+ try await verifyPolicy(
+ controller: controller, executable: selfExecutable, password: password, deadline: deadline)
+ }
+
+ @MainActor private func preflightCredentials(
+ controller: LumeController, executable: String, password: String, deadline: SipDeadline
+ ) async throws {
+ Logger.info("Booting normally to validate admin credentials", metadata: ["vm": name])
+ let child = try SipChildProcess(
+ executable: executable, arguments: runArguments(recovery: false), label: "credential-preflight")
+
+ do {
+ try child.start()
+ let details = try await waitForSSHReady(
+ controller: controller, child: child, context: "credential preflight", deadline: deadline,
+ maxSeconds: 300)
+ guard let ip = details.ipAddress else {
+ throw SipError.credentialPreflightFailed("VM did not report an IP address")
+ }
+
+ let ssh = SSHClient(host: ip, port: 22, user: adminUser, password: password)
+ do {
+ let result = try await ssh.execute(
+ command: "true", timeout: try deadline.remaining(upTo: 30, operation: "credential preflight"))
+ guard result.exitCode == 0 else {
+ throw SipError.credentialPreflightFailed("SSH command exited with status \(result.exitCode)")
+ }
+ } catch let error as SipError { throw error } catch {
+ throw SipError.credentialPreflightFailed(
+ "SSH authentication failed for '\(adminUser)': \(error.localizedDescription)")
+ }
+
+ Logger.info("Admin credential preflight passed", metadata: ["vm": name])
+ try await stopNormalBoot(
+ child: child, controller: controller, deadline: deadline, operation: "credential preflight")
+ child.cleanup()
+ } catch {
+ await child.terminateAndWait()
+ child.cleanup()
+ throw error
+ }
+ }
+
+ @MainActor private func changePolicyInRecovery(
+ controller: LumeController, executable: String, vncdo: String, password: String, deadline: SipDeadline
+ ) async throws {
+ let vncPassword = Self.makeVNCPassword()
+ Logger.info("Booting recovery", metadata: ["vm": name, "vnc_port": "\(vncPort)"])
+ let child = try SipChildProcess(
+ executable: executable, arguments: runArguments(recovery: true, vncPassword: vncPassword), label: "recovery"
+ )
+
+ do {
+ try child.start()
+ let driver = VNCDriver(
+ vncdo: vncdo, host: "127.0.0.1", port: vncPort, password: vncPassword, screenshotDir: screenshotDir)
+ let heartbeat = { try child.ensureRunning(context: "recovery boot", redacting: [vncPassword]) }
+ let automator = SipRecoveryAutomator()
+ try await automator.perform(
+ driver: driver, state: state, adminUser: adminUser, adminPassword: password, heartbeat: heartbeat,
+ timeout: { limit, operation in try deadline.remaining(upTo: limit, operation: operation) })
+
+ Logger.info("Waiting for recovery to shut down")
+ do {
+ try await waitForProcessExit(
+ child, deadline: deadline, maxSeconds: 60,
+ context: "recovery shutdown; SIP state may not have been committed", redacting: [vncPassword])
+ } catch SipError.childProcessTimedOut {
+ Logger.info(
+ "Recovery did not halt after committing the policy; stopping its run process",
+ metadata: ["vm": name])
+ await child.terminateAndWait()
+ guard !child.isRunning else {
+ throw SipError.childProcessTimedOut(
+ context: "recovery shutdown fallback", output: child.outputTail(redacting: [vncPassword]))
+ }
+ }
+ try await waitForStoppedState(controller: controller, deadline: deadline, operation: "recovery shutdown")
+ child.cleanup()
+ } catch {
+ await child.terminateAndWait()
+ child.cleanup()
+ throw error
+ }
+ }
+
+ @MainActor private func verifyPolicy(
+ controller: LumeController, executable: String, password: String, deadline: SipDeadline
+ ) async throws {
+ Logger.info("Booting normally to verify SIP state")
+ let child = try SipChildProcess(
+ executable: executable, arguments: runArguments(recovery: false), label: "verification")
+
+ do {
+ try child.start()
+ let details = try await waitForSSHReady(
+ controller: controller, child: child, context: "verification boot", deadline: deadline, maxSeconds: 300)
+ guard let ip = details.ipAddress else {
+ throw SipError.verificationFailed("VM did not report an IP address")
+ }
+
+ let ssh = SSHClient(host: ip, port: 22, user: adminUser, password: password)
+ let result = try await ssh.execute(
+ command: "csrutil status", timeout: try deadline.remaining(upTo: 30, operation: "SIP verification"))
+ let statusOutput = result.output.trimmingCharacters(in: .whitespacesAndNewlines)
+ let matches = result.exitCode == 0 && Self.statusMatches(statusOutput, expected: state)
+ print(statusOutput)
+
+ try await stopNormalBoot(
+ child: child, controller: controller, deadline: deadline, operation: "verification")
+
+ guard result.exitCode == 0 else {
+ throw SipError.verificationFailed("csrutil status exited with status \(result.exitCode): \(statusOutput)")
+ }
+ guard matches else {
+ throw SipError.verificationFailed("Unexpected csrutil status after \(state.rawValue): \(statusOutput)")
+ }
+ print("SIP is \(state == .off ? "disabled" : "enabled").")
+ child.cleanup()
+ } catch {
+ await child.terminateAndWait()
+ child.cleanup()
+ throw error
+ }
+ }
+
+ @MainActor private func waitForSSHReady(
+ controller: LumeController, child: SipChildProcess, context: String, deadline: SipDeadline, maxSeconds: Double
+ ) async throws -> VMDetails {
+ let allowed = try deadline.remaining(upTo: maxSeconds, operation: context)
+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))
+ while ContinuousClock.now < localDeadline {
+ try child.ensureRunning(context: context, redacting: [])
+ if let details = try? controller.getDetails(name: name, storage: storage), details.status == "running",
+ details.sshAvailable == true, let ip = details.ipAddress, !ip.isEmpty
+ {
+ return details
+ }
+ try await sleep(seconds: min(5, try deadline.remaining(upTo: 5, operation: context)))
+ }
+ throw SipError.verificationFailed(
+ "VM never reached SSH-ready state during \(context). " + "Ensure Remote Login is enabled.")
+ }
+
+ @MainActor private func stopNormalBoot(
+ child: SipChildProcess, controller: LumeController, deadline: SipDeadline, operation: String
+ ) async throws {
+ Logger.info("Stopping normal boot", metadata: ["operation": operation, "vm": name])
+ await child.terminateAndWait()
+ guard !child.isRunning else {
+ throw SipError.childProcessTimedOut(
+ context: "\(operation) stop", output: child.outputTail(redacting: []))
+ }
+ try await waitForStoppedState(controller: controller, deadline: deadline, operation: "\(operation) stop")
+ }
+
+ @MainActor private func waitForProcessExit(
+ _ child: SipChildProcess, deadline: SipDeadline, maxSeconds: Double, context: String,
+ redacting secrets: [String]
+ ) async throws {
+ let allowed = try deadline.remaining(upTo: maxSeconds, operation: context)
+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))
+ while child.isRunning && ContinuousClock.now < localDeadline { try await sleep(seconds: 1) }
+ guard !child.isRunning else {
+ throw SipError.childProcessTimedOut(context: context, output: child.outputTail(redacting: secrets))
+ }
+ guard child.terminationStatus == 0 else {
+ throw SipError.childProcessExited(
+ context: context, status: child.terminationStatus, output: child.outputTail(redacting: secrets))
+ }
+ }
+
+ @MainActor private func waitForStoppedState(controller: LumeController, deadline: SipDeadline, operation: String)
+ async throws
+ {
+ let allowed = try deadline.remaining(upTo: 30, operation: operation)
+ let localDeadline = ContinuousClock.now.advanced(by: .seconds(allowed))
+ while ContinuousClock.now < localDeadline {
+ if let details = try? controller.getDetails(name: name, storage: storage), details.status == "stopped" {
+ return
+ }
+ try await sleep(seconds: 1)
+ }
+ throw SipError.vmDidNotStop(name, operation: operation)
+ }
+
+ @MainActor private func loadInitialDetails(controller: LumeController) throws -> VMDetails {
+ do { return try controller.getDetails(name: name, storage: storage) } catch { throw SipError.vmNotFound(name) }
+ }
+
+ private func confirmChange() throws {
+ let verb = state == .off ? "DISABLE" : "ENABLE"
+ print("This will \(verb) System Integrity Protection on '\(name)'.")
+ print("The VM will boot normally for credential validation, then into recovery.")
+ print("Continue? [y/N]: ", terminator: "")
+ let answer = readLine()?.trimmingCharacters(in: .whitespaces).lowercased() ?? ""
+ guard answer == "y" || answer == "yes" else {
+ print("Aborted.")
+ throw ExitCode(1)
+ }
+ }
+
+ private func resolvedAdminPassword() throws -> String {
+ if adminPassword != nil && adminPasswordStdin { throw SipError.conflictingPasswordSources }
+ let password: String
+ if adminPasswordStdin {
+ password = try readSecretLineFromStandardInput()
+ } else {
+ password = adminPassword ?? "lume"
+ }
+ guard !password.isEmpty else { throw SipError.emptyPassword }
+ return password
+ }
+
+ private func readSecretLineFromStandardInput() throws -> String {
+ let fd = STDIN_FILENO
+ var original = termios()
+ let isTerminal = isatty(fd) == 1
+ var echoDisabled = false
+
+ if isTerminal {
+ guard tcgetattr(fd, &original) == 0 else {
+ throw SipError.passwordTerminalConfigurationFailed
+ }
+ var noEcho = original
+ noEcho.c_lflag &= ~tcflag_t(ECHO)
+ guard tcsetattr(fd, TCSAFLUSH, &noEcho) == 0 else {
+ throw SipError.passwordTerminalConfigurationFailed
+ }
+ echoDisabled = true
+ FileHandle.standardError.write(Data("Admin password: ".utf8))
+ }
+ defer {
+ if echoDisabled {
+ var restored = original
+ tcsetattr(fd, TCSAFLUSH, &restored)
+ FileHandle.standardError.write(Data("\n".utf8))
+ }
+ }
+
+ guard let password = readLine(strippingNewline: true) else { throw SipError.passwordStdinUnavailable }
+ return password
+ }
+
+ private func resolvedSelfExecutable() -> String {
+ let selfPath = ProcessInfo.processInfo.arguments[0]
+ if selfPath.hasPrefix("/") { return selfPath }
+ return which(selfPath) ?? selfPath
+ }
+
+ private func runArguments(recovery: Bool, vncPassword: String? = nil) -> [String] {
+ var args = ["run", name, "--no-display"]
+ if recovery { args.append(contentsOf: ["--recovery-mode", "true"]) }
+ if let vncPassword { args.append(contentsOf: ["--vnc-port", "\(vncPort)", "--vnc-password", vncPassword]) }
+ if let storage { args.append(contentsOf: ["--storage", storage]) }
+ return args
+ }
+
+ private func sleep(seconds: Double) async throws { try await Task.sleep(for: .seconds(seconds)) }
+
+ private func which(_ name: String) -> String? {
+ let process = Process()
+ process.executableURL = URL(fileURLWithPath: "/usr/bin/which")
+ process.arguments = [name]
+ let output = Pipe()
+ process.standardOutput = output
+ process.standardError = FileHandle.nullDevice
+ try? process.run()
+ process.waitUntilExit()
+ guard process.terminationStatus == 0, let data = try? output.fileHandleForReading.readToEnd(),
+ let path = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines),
+ !path.isEmpty
+ else { return nil }
+ return path
+ }
+
+ static func validateInitialState(_ details: VMDetails, expectedName: String) throws {
+ guard details.name == expectedName else { throw SipError.vmNotFound(expectedName) }
+ guard details.os.lowercased() == "macos" else { throw SipError.unsupportedOS(details.os) }
+ guard details.status == "stopped" else { throw SipError.vmNotStopped(expectedName, actual: details.status) }
+ }
+
+ static func requireVNCExecutable(_ path: String?) throws -> String {
+ guard let path else { throw SipError.vncdoNotFound }
+ return path
+ }
+
+ static func makeVNCPassword() -> String {
+ // Classic VNC authentication uses only the first eight password bytes.
+ let characters = Array("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
+ var generator = SystemRandomNumberGenerator()
+ return String((0..<8).map { _ in
+ characters[Int.random(in: characters.indices, using: &generator)]
+ })
+ }
+
+ static func statusMatches(_ output: String, expected state: State) -> Bool {
+ let prefix = "system integrity protection status:"
+ guard let statusLine = output.split(whereSeparator: \.isNewline).map({
+ $0.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+ }).first(where: { $0.hasPrefix(prefix) }) else {
+ return false
+ }
+ let value = statusLine.dropFirst(prefix.count).trimmingCharacters(in: .whitespaces)
+ switch state {
+ case .off: return value == "disabled" || value == "disabled."
+ case .on: return value == "enabled" || value == "enabled."
+ }
+ }
+
+ static func validateVNCPasswordCharacters(_ password: String) throws {
+ let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789-")
+ guard password.unicodeScalars.allSatisfy(allowed.contains) else { throw SipError.unsupportedPasswordCharacters }
+ }
+}
+
+@MainActor struct SipRecoveryAutomator {
+ typealias Sleeper = (Double) async throws -> Void
+ typealias Timeout = (Double, String) throws -> Double
+
+ private let sleeper: Sleeper
+
+ init(sleeper: @escaping Sleeper = { seconds in try await Task.sleep(for: .seconds(seconds)) }) {
+ self.sleeper = sleeper
+ }
+
+ func perform(
+ driver: any RecoveryVNCDriving, state: Sip.State, adminUser: String, adminPassword: String,
+ heartbeat: () throws -> Void,
+ timeout: Timeout
+ ) async throws {
+ try await driver.waitForListening(deadlineSeconds: try timeout(60, "VNC startup"), heartbeat: heartbeat)
+ try await driver.waitForFramebuffer(
+ minSize: 15_000, deadlineSeconds: try timeout(90, "recovery picker"), label: "picker", heartbeat: heartbeat)
+
+ try driver.key("right")
+ try await pause(seconds: 1, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)
+ try driver.key("right")
+ try await pause(seconds: 1, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)
+ try driver.snapshot("01-options-focused")
+ try driver.key("enter")
+ try await pause(seconds: 3, operation: "recovery picker", heartbeat: heartbeat, timeout: timeout)
+
+ try await driver.waitForFramebuffer(
+ minSize: 60_000, deadlineSeconds: try timeout(180, "recovery language selector"), label: "language",
+ heartbeat: heartbeat)
+ try driver.key("enter")
+ try await pause(
+ seconds: 45, operation: "recoveryOS main-menu transition", heartbeat: heartbeat, timeout: timeout)
+ try driver.snapshot("02-recoveryOS-menu")
+
+ try driver.click(x: 243, y: 14)
+ try await pause(seconds: 1, operation: "Utilities menu", heartbeat: heartbeat, timeout: timeout)
+ for _ in 0..<3 {
+ try driver.key("down")
+ try await pause(seconds: 0.2, operation: "Utilities menu", heartbeat: heartbeat, timeout: timeout)
+ }
+ try driver.snapshot("03-terminal-highlighted")
+ try driver.key("enter")
+ try await pause(seconds: 4, operation: "Terminal launch", heartbeat: heartbeat, timeout: timeout)
+ try driver.snapshot("04-terminal-opened")
+
+ try driver.type(state == .off ? "csrutil disable" : "csrutil enable")
+ try driver.key("enter")
+ try await pause(seconds: 3, operation: "csrutil prompt", heartbeat: heartbeat, timeout: timeout)
+ try driver.snapshot("05-csrutil-prompt")
+
+ let accountPrompt = "enter password for user \(adminUser):"
+ let promptText = try await driver.waitForText(
+ containing: ["[y/n]", accountPrompt],
+ rejecting: ["no administrator was found", "failed to authenticate", "authentication failure"],
+ deadlineSeconds: try timeout(15, "csrutil prompt"), label: "csrutil prompt", heartbeat: heartbeat)
+
+ if !promptText.lowercased().contains(accountPrompt.lowercased()) {
+ try driver.key("y")
+ try driver.key("enter")
+ try await pause(seconds: 3, operation: "csrutil password prompt", heartbeat: heartbeat, timeout: timeout)
+ _ = try await driver.waitForText(
+ containing: [accountPrompt],
+ rejecting: ["no administrator was found", "failed to authenticate", "authentication failure"],
+ deadlineSeconds: try timeout(15, "csrutil account prompt"), label: "csrutil account prompt",
+ heartbeat: heartbeat)
+ }
+ try driver.snapshot("06-password-prompt")
+
+ try driver.typeSensitive(adminPassword)
+ try driver.key("enter")
+ let expected = state == .off ? "system integrity protection is off." : "system integrity protection is on."
+ _ = try await driver.waitForText(
+ containing: [expected],
+ rejecting: ["incorrect password", "authentication failed", "failed to modify", "try again"],
+ deadlineSeconds: try timeout(20, "csrutil result"), label: "csrutil result", heartbeat: heartbeat)
+ try driver.snapshot("07-after-password")
+
+ try driver.type("sync; shutdown -h now")
+ try driver.key("enter")
+ try driver.snapshot("08-shutdown-sent")
+ }
+
+ private func pause(seconds: Double, operation: String, heartbeat: () throws -> Void, timeout: Timeout) async throws
+ {
+ var remaining = seconds
+ while remaining > 0 {
+ try heartbeat()
+ let interval = min(1, remaining)
+ let allowed = try timeout(interval, operation)
+ try await sleeper(min(interval, allowed))
+ remaining -= interval
+ }
+ try heartbeat()
+ }
+}
+
+struct SipDeadline: Sendable {
+ private let clock = ContinuousClock()
+ private let end: ContinuousClock.Instant
+
+ init(seconds: Int) { end = clock.now.advanced(by: .seconds(seconds)) }
+
+ func remaining(upTo limit: Double, operation: String) throws -> Double {
+ let duration = clock.now.duration(to: end).components
+ let seconds = Double(duration.seconds) + Double(duration.attoseconds) / 1e18
+ guard seconds > 0 else { throw SipError.timedOut(operation) }
+ return min(limit, seconds)
+ }
+}
+
+@MainActor final class SipChildProcess {
+ private static let maximumTailBytes = 16 * 1024
+
+ let process = Process()
+ private let logURL: URL
+ private let logHandle: FileHandle
+
+ init(executable: String, arguments: [String], label: String) throws {
+ let safeLabel = label.replacingOccurrences(of: " ", with: "-")
+ logURL = FileManager.default.temporaryDirectory.appendingPathComponent(
+ "lume-sip-\(safeLabel)-\(UUID().uuidString).log")
+ guard FileManager.default.createFile(atPath: logURL.path, contents: nil, attributes: [.posixPermissions: 0o600])
+ else { throw SipError.processSetupFailed("Could not create child-process log") }
+ logHandle = try FileHandle(forWritingTo: logURL)
+ process.executableURL = URL(fileURLWithPath: executable)
+ process.arguments = arguments
+ process.standardOutput = logHandle
+ process.standardError = logHandle
+ }
+
+ var isRunning: Bool { process.isRunning }
+
+ var terminationStatus: Int32 { process.isRunning ? -1 : process.terminationStatus }
+
+ func start() throws { try process.run() }
+
+ func ensureRunning(context: String, redacting secrets: [String]) throws {
+ guard process.isRunning else {
+ throw SipError.childProcessExited(
+ context: context, status: terminationStatus, output: outputTail(redacting: secrets))
+ }
+ }
+
+ func outputTail(redacting secrets: [String]) -> String {
+ try? logHandle.synchronize()
+ guard let data = try? Data(contentsOf: logURL) else { return "" }
+ let tail = data.suffix(Self.maximumTailBytes)
+ var output = String(decoding: tail, as: UTF8.self)
+ for secret in secrets where !secret.isEmpty {
+ output = output.replacingOccurrences(of: secret, with: "<redacted>")
+ }
+ return output.trimmingCharacters(in: .whitespacesAndNewlines)
+ }
+
+ func terminateAndWait() async {
+ guard process.isRunning else { return }
+ process.interrupt()
+ await waitForTermination(seconds: 5)
+ if process.isRunning {
+ process.terminate()
+ await waitForTermination(seconds: 5)
+ }
+ if process.isRunning {
+ Darwin.kill(process.processIdentifier, SIGKILL)
+ await waitForTermination(seconds: 2)
+ }
+ }
+
+ func cleanup() {
+ try? logHandle.close()
+ try? FileManager.default.removeItem(at: logURL)
+ }
+
+ private func waitForTermination(seconds: Double) async {
+ let deadline = ContinuousClock.now.advanced(by: .seconds(seconds))
+ while process.isRunning && ContinuousClock.now < deadline { try? await Task.sleep(for: .milliseconds(100)) }
+ }
+}
+
+enum SipError: Error, CustomStringConvertible {
+ case vmNotFound(String)
+ case vmNotStopped(String, actual: String)
+ case vmDidNotStop(String, operation: String)
+ case unsupportedOS(String)
+ case vncdoNotFound
+ case conflictingPasswordSources
+ case passwordStdinUnavailable
+ case passwordTerminalConfigurationFailed
+ case emptyPassword
+ case unsupportedPasswordCharacters
+ case invalidTimeout(Int)
+ case credentialPreflightFailed(String)
+ case childProcessExited(context: String, status: Int32, output: String)
+ case childProcessTimedOut(context: String, output: String)
+ case processSetupFailed(String)
+ case timedOut(String)
+ case verificationFailed(String)
+
+ var description: String {
+ switch self {
+ case .vmNotFound(let name): return "VM '\(name)' not found."
+ case .vmNotStopped(let name, let actual): return "VM '\(name)' must be stopped (current status: \(actual))."
+ case .vmDidNotStop(let name, let operation):
+ return "VM '\(name)' did not reach stopped state after \(operation)."
+ case .unsupportedOS(let os): return "The sip command supports macOS VMs only (found: \(os))."
+ case .vncdoNotFound: return "vncdotool not found on PATH. Install with: pip3 install vncdotool"
+ case .conflictingPasswordSources: return "Use either --admin-password or --admin-password-stdin, not both."
+ case .passwordStdinUnavailable: return "Could not read the admin password from standard input."
+ case .passwordTerminalConfigurationFailed:
+ return "Could not disable terminal echo while reading the admin password."
+ case .emptyPassword: return "The admin password cannot be empty."
+ case .unsupportedPasswordCharacters:
+ return "Recovery VNC currently supports admin passwords containing only "
+ + "lowercase ASCII letters, digits, and hyphens."
+ case .invalidTimeout(let timeout): return "Timeout must be greater than zero (received: \(timeout))."
+ case .credentialPreflightFailed(let message): return "Admin credential preflight failed: \(message)"
+ case .childProcessExited(let context, let status, let output):
+ let suffix = output.isEmpty ? "" : "\n\(output)"
+ return "The lume run child exited during \(context) with status \(status).\(suffix)"
+ case .childProcessTimedOut(let context, let output):
+ let suffix = output.isEmpty ? "" : "\n\(output)"
+ return "Timed out waiting for the lume run child during \(context).\(suffix)"
+ case .processSetupFailed(let message): return "Could not prepare the lume run child: \(message)"
+ case .timedOut(let operation): return "The overall sip timeout expired during \(operation)."
+ case .verificationFailed(let message): return "SIP verification failed: \(message)"
+ }
+ }
+}
diff --git a/libs/lume/src/FileSystem/Home.swift b/libs/lume/src/FileSystem/Home.swift
index 8fd741e752..298f9ef65a 100644
--- a/libs/lume/src/FileSystem/Home.swift
+++ b/libs/lume/src/FileSystem/Home.swift
@@ -222,7 +222,9 @@ final class Home {
}
}
- /// Clones a VM directory using APFS clonefile for disk.img and regular copy for small files
+ /// Clones a complete VM state using APFS clonefile for disk.img and regular copies for
+ /// auxiliary files. macOS disk and auxiliary storage must remain paired because boot
+ /// policy state spans both files.
/// - Parameters:
/// - sourceName: Name of the source VM
/// - destName: Name for the destination VM
diff --git a/libs/lume/src/SSH/SSHClient.swift b/libs/lume/src/SSH/SSHClient.swift
index 46137e72b1..cb6b4b9daf 100644
--- a/libs/lume/src/SSH/SSHClient.swift
+++ b/libs/lume/src/SSH/SSHClient.swift
@@ -46,6 +46,7 @@ public actor SSHClient {
// Create a promise for the result
let resultPromise = channel.eventLoop.makePromise(of: SSHResult.self)
+ let resultState = CommandResultState(promise: resultPromise)
// Create the SSH child channel for command execution.
// We keep handler access + createChannel on the event loop to avoid
@@ -58,7 +59,10 @@ public actor SSHClient {
}
return childChannel.eventLoop.makeCompletedFuture {
- let execHandler = CommandExecHandler(command: command, resultPromise: resultPromise)
+ let execHandler = CommandExecHandler(
+ command: command,
+ resultState: resultState
+ )
try childChannel.pipeline.syncOperations.addHandler(execHandler)
}
}
@@ -70,24 +74,26 @@ public actor SSHClient {
// Set up timeout if specified
if timeout > 0 {
let timeoutTask = channel.eventLoop.scheduleTask(in: .seconds(Int64(timeout))) {
- resultPromise.fail(SSHError.timeout)
+ resultState.fail(SSHError.timeout)
childChannel.close(promise: nil)
}
// Cancel timeout when result is received
- resultPromise.futureResult.whenComplete { _ in
+ resultState.futureResult.whenComplete { _ in
timeoutTask.cancel()
}
}
- // Wait for command completion
- let result = try await resultPromise.futureResult.get()
-
- // Clean up
- try? await childChannel.closeFuture.get()
- try? await channel.close().get()
-
- return result
+ do {
+ let result = try await resultState.futureResult.get()
+ try? await childChannel.closeFuture.get()
+ try? await channel.close().get()
+ return result
+ } catch {
+ try? await childChannel.close().get()
+ try? await channel.close().get()
+ throw error
+ }
}
/// Start an interactive SSH session
@@ -222,6 +228,35 @@ private final class PasswordAuthDelegate: NIOSSHClientUserAuthenticationDelegate
// MARK: - Command Execution Handler
+private final class CommandResultState: @unchecked Sendable {
+ private let promise: EventLoopPromise<SSHResult>
+ private let completed = NIOLockedValueBox(false)
+
+ init(promise: EventLoopPromise<SSHResult>) {
+ self.promise = promise
+ }
+
+ var futureResult: EventLoopFuture<SSHResult> { promise.futureResult }
+
+ func succeed(_ result: SSHResult) {
+ guard claimCompletion() else { return }
+ promise.succeed(result)
+ }
+
+ func fail(_ error: Error) {
+ guard claimCompletion() else { return }
+ promise.fail(error)
+ }
+
+ private func claimCompletion() -> Bool {
+ completed.withLockedValue { completed in
+ guard !completed else { return false }
+ completed = true
+ return true
+ }
+ }
+}
+
/// Handles command execution on an SSH channel
/// Note: @unchecked Sendable is safe because this handler is only used on a single event loop
private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendable {
@@ -231,14 +266,14 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendabl
typealias OutboundOut = SSHChannelData
private let command: String
- private var resultPromise: EventLoopPromise<SSHResult>?
+ private let resultState: CommandResultState
private var outputBuffer: ByteBuffer
private var exitStatus: Int32?
private var channelClosed = false
- init(command: String, resultPromise: EventLoopPromise<SSHResult>) {
+ init(command: String, resultState: CommandResultState) {
self.command = command
- self.resultPromise = resultPromise
+ self.resultState = resultState
self.outputBuffer = ByteBuffer()
}
@@ -291,7 +326,11 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendabl
func channelInactive(context: ChannelHandlerContext) {
channelClosed = true
- checkCompletion(context: context)
+ if exitStatus == nil {
+ failForMissingExitStatus()
+ } else {
+ checkCompletion(context: context)
+ }
}
func errorCaught(context: ChannelHandlerContext, error: Error) {
@@ -299,35 +338,34 @@ private final class CommandExecHandler: ChannelDuplexHandler, @unchecked Sendabl
}
func handlerRemoved(context: ChannelHandlerContext) {
- // If we haven't completed yet, complete with what we have
- checkCompletion(context: context)
+ if exitStatus == nil {
+ failForMissingExitStatus()
+ } else {
+ checkCompletion(context: context)
+ }
}
private func checkCompletion(context: ChannelHandlerContext) {
- // Only complete if we have both exit status and channel is closed (or we have exit status)
- guard let promise = resultPromise else { return }
-
- // Complete when we have exit status (some servers close channel before sending exit status)
- if let status = exitStatus {
- resultPromise = nil
- let output = outputBuffer.readString(length: outputBuffer.readableBytes) ?? ""
- promise.succeed(SSHResult(exitCode: status, output: output))
- } else if channelClosed {
- // Channel closed without exit status - assume success with exit code 0
- resultPromise = nil
+ if let status = exitStatus, channelClosed {
let output = outputBuffer.readString(length: outputBuffer.readableBytes) ?? ""
- promise.succeed(SSHResult(exitCode: 0, output: output))
+ resultState.succeed(SSHResult(exitCode: status, output: output))
}
}
+ private func failForMissingExitStatus() {
+ resultState.fail(
+ SSHError.commandFailed(
+ exitCode: -1,
+ message: "SSH channel closed without an exit status"
+ )
+ )
+ }
+
private func failWithError(_ error: Error, context: ChannelHandlerContext) {
- if let promise = resultPromise {
- resultPromise = nil
- if let sshError = error as? SSHError {
- promise.fail(sshError)
- } else {
- promise.fail(SSHError.commandFailed(exitCode: -1, message: error.localizedDescription))
- }
+ if let sshError = error as? SSHError {
+ resultState.fail(sshError)
+ } else {
+ resultState.fail(SSHError.commandFailed(exitCode: -1, message: String(describing: error)))
}
context.close(promise: nil)
}
diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swift
index 164446fe8c..bfda9a518d 100644
--- a/libs/lume/src/Utils/CommandDocExtractor.swift
+++ b/libs/lume/src/Utils/CommandDocExtractor.swift
@@ -56,6 +56,11 @@ struct CLIDocumentation: Codable {
enum CommandDocExtractor {
/// Extract documentation from all registered commands
static func extractAll() -> CLIDocumentation {
+ let coverage = documentationCoverage
+ precondition(
+ coverage.missing.isEmpty && coverage.extra.isEmpty,
+ "CLI documentation coverage mismatch. Missing: \(coverage.missing); extra: \(coverage.extra)"
+ )
return CLIDocumentation(
name: "lume",
version: Lume.Version.current,
@@ -73,6 +78,7 @@ enum CommandDocExtractor {
createDoc,
pullDoc,
pushDoc,
+ convertDoc,
imagesDoc,
cloneDoc,
getDoc,
@@ -81,6 +87,7 @@ enum CommandDocExtractor {
runDoc,
stopDoc,
sshDoc,
+ sipDoc,
ipswDoc,
serveDoc,
deleteDoc,
@@ -90,9 +97,23 @@ enum CommandDocExtractor {
checkUpdateDoc,
updateDoc,
setupDoc,
+ dumpDocsDoc,
]
}
+ static var documentationCoverage: (missing: [String], extra: [String]) {
+ let registered = Swift.Set(CommandRegistry.allCommands.map(commandName))
+ let documented = Swift.Set(allCommandDocs.map(\.name))
+ return (
+ missing: registered.subtracting(documented).sorted(),
+ extra: documented.subtracting(registered).sorted()
+ )
+ }
+
+ private static func commandName(_ command: ParsableCommand.Type) -> String {
+ command.configuration.commandName ?? String(describing: command).lowercased()
+ }
+
// MARK: - Create
private static var createDoc: CommandDoc {
@@ -171,6 +192,41 @@ enum CommandDocExtractor {
)
}
+ // MARK: - Convert
+
+ private static var convertDoc: CommandDoc {
+ CommandDoc(
+ name: "convert",
+ abstract: "Convert a legacy Lume image to OCI-compliant format",
+ discussion: nil,
+ arguments: [
+ ArgumentDoc(
+ name: "source-image",
+ help: "Source image to convert (legacy format, for example macos-tahoe:latest)",
+ type: "String",
+ isOptional: false
+ ),
+ ArgumentDoc(
+ name: "target-image",
+ help: "Target image to push in OCI format (name:tag)",
+ type: "String",
+ isOptional: false
+ ),
+ ],
+ options: [
+ OptionDoc(name: "additional-tags", shortName: nil, help: "Additional tags for the OCI image", type: "[String]", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "registry", shortName: nil, help: "Registry to pull from and push to", type: "String", defaultValue: "ghcr.io", isOptional: false),
+ OptionDoc(name: "organization", shortName: nil, help: "Registry organization", type: "String", defaultValue: "trycua", isOptional: false),
+ ],
+ flags: [
+ FlagDoc(name: "verbose", shortName: nil, help: "Enable verbose logging", defaultValue: false),
+ FlagDoc(name: "dry-run", shortName: nil, help: "Prepare files without uploading", defaultValue: false),
+ FlagDoc(name: "single-layer", shortName: nil, help: "Push one kubelet-compatible disk layer", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
// MARK: - Images
private static var imagesDoc: CommandDoc {
@@ -332,6 +388,33 @@ enum CommandDocExtractor {
)
}
+ // MARK: - SIP
+
+ private static var sipDoc: CommandDoc {
+ CommandDoc(
+ name: "sip",
+ abstract: "Enable or disable System Integrity Protection on a macOS VM",
+ discussion: "Validates the administrator account, changes SIP from paired Recovery over VNC, and verifies the canonical csrutil status after a normal boot.",
+ arguments: [
+ ArgumentDoc(name: "state", help: "Desired SIP state: on or off", type: "String", isOptional: false),
+ ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
+ ],
+ options: [
+ OptionDoc(name: "admin-user", shortName: nil, help: "Administrator username in the guest", type: "String", defaultValue: "lume", isOptional: false),
+ OptionDoc(name: "admin-password", shortName: nil, help: "Administrator password in the guest; prefer --admin-password-stdin", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "screenshot-dir", shortName: nil, help: "Directory for Recovery framebuffer screenshots", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "vnc-port", shortName: nil, help: "Port for the temporary Recovery VNC server", type: "Int", defaultValue: "5999", isOptional: false),
+ OptionDoc(name: "storage", shortName: nil, help: "VM storage location", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "timeout", shortName: nil, help: "Overall timeout in seconds", type: "Int", defaultValue: "900", isOptional: false),
+ ],
+ flags: [
+ FlagDoc(name: "yes", shortName: "y", help: "Skip the interactive confirmation prompt", defaultValue: false),
+ FlagDoc(name: "admin-password-stdin", shortName: nil, help: "Read one administrator-password line from standard input without echo", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
// MARK: - IPSW
private static var ipswDoc: CommandDoc {
@@ -566,4 +649,22 @@ enum CommandDocExtractor {
subcommands: []
)
}
+
+ // MARK: - Dump Docs
+
+ private static var dumpDocsDoc: CommandDoc {
+ CommandDoc(
+ name: "dump-docs",
+ abstract: "Output CLI and API documentation as JSON for tooling and integrations",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "type", shortName: nil, help: "Documentation type: cli, api, or all", type: "String", defaultValue: "cli", isOptional: false),
+ ],
+ flags: [
+ FlagDoc(name: "pretty", shortName: nil, help: "Pretty-print JSON output", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
}
diff --git a/libs/lume/src/Utils/CommandRegistry.swift b/libs/lume/src/Utils/CommandRegistry.swift
index 4752567640..a9b77b1e28 100644
--- a/libs/lume/src/Utils/CommandRegistry.swift
+++ b/libs/lume/src/Utils/CommandRegistry.swift
@@ -15,6 +15,7 @@ enum CommandRegistry {
Run.self,
Stop.self,
SSH.self,
+ Sip.self,
IPSW.self,
Serve.self,
Delete.self,
diff --git a/libs/lume/src/Utils/VNCDriver.swift b/libs/lume/src/Utils/VNCDriver.swift
new file mode 100644
index 0000000000..48349abc53
--- /dev/null
+++ b/libs/lume/src/Utils/VNCDriver.swift
@@ -0,0 +1,309 @@
+import Darwin
+import Foundation
+import Vision
+
+@MainActor protocol RecoveryVNCDriving {
+ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void) async throws
+ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void)
+ async throws
+ func waitForText(
+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,
+ label: String, heartbeat: () throws -> Void
+ ) async throws -> String
+ func type(_ text: String) throws
+ func typeSensitive(_ text: String) throws
+ func key(_ name: String) throws
+ func click(x: Int, y: Int) throws
+ func snapshot(_ tag: String) throws
+}
+
+/// Thin wrapper around the `vncdotool` CLI (`pip3 install vncdotool`).
+///
+/// Used only by `lume sip` to drive the recoveryOS UI. The tool is invoked
+/// per action via `Process`, and all args go through argv (never a shell).
+///
+/// Known limitations of vncdotool against macOS VNC servers:
+/// - `type` doesn't shift correctly: uppercase, `_`, `&`, etc. get
+/// corrupted. Only send unshifted characters through `type`.
+/// - Cmd-key chords (⇧⌘T etc.) do NOT reliably route through VZ's VNC
+/// server. Use menu-bar clicks + arrow-key navigation instead.
+///
+/// A future commit can swap this for a native Swift RFB client without
+/// changing call sites. The in-tree `VNCClient` actor is a candidate, but
+/// has an outstanding NWConnection stall when invoked from certain
+/// `@MainActor` call chains that needs investigation before use here.
+@MainActor struct VNCDriver: RecoveryVNCDriving {
+ let vncdo: String
+ let host: String
+ let port: Int
+ let password: String
+ let screenshotDir: String?
+
+ private var target: String { "\(host)::\(port)" }
+
+ /// Find `vncdo` (or `vncdotool`) on PATH. Also checks the pip3
+ /// user-scripts directory (`~/Library/Python/<ver>/bin`) since
+ /// `pip3 install --user vncdotool` puts it there and that's often not
+ /// on PATH by default.
+ static func locateVncdo() -> String? {
+ for name in ["vncdo", "vncdotool"] { if let hit = whichPath(name) { return hit } }
+ let home = NSHomeDirectory()
+ let pythonBase = "\(home)/Library/Python"
+ if let dirs = try? FileManager.default.contentsOfDirectory(atPath: pythonBase) {
+ for dir in dirs {
+ for name in ["vncdo", "vncdotool"] {
+ let candidate = "\(pythonBase)/\(dir)/bin/\(name)"
+ if FileManager.default.isExecutableFile(atPath: candidate) { return candidate }
+ }
+ }
+ }
+ return nil
+ }
+
+ private static func whichPath(_ name: String) -> String? {
+ let p = Process()
+ p.executableURL = URL(fileURLWithPath: "/usr/bin/which")
+ p.arguments = [name]
+ let out = Pipe()
+ p.standardOutput = out
+ p.standardError = Pipe()
+ try? p.run()
+ p.waitUntilExit()
+ guard p.terminationStatus == 0, let data = try? out.fileHandleForReading.readToEnd(),
+ let str = String(data: data, encoding: .utf8)
+ else { return nil }
+ let trimmed = str.trimmingCharacters(in: .whitespacesAndNewlines)
+ return trimmed.isEmpty ? nil : trimmed
+ }
+
+ // MARK: - Public API
+
+ /// Wait until the VNC server is accepting TCP connections.
+ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void = {}) async throws {
+ let deadline = Date().addingTimeInterval(deadlineSeconds)
+ while Date() < deadline {
+ try heartbeat()
+ if canConnect() { return }
+ try await sleep(seconds: 1)
+ }
+ throw VNCDriverError.timeout("VNC server never became reachable on \(target)")
+ }
+
+ /// Poll `capture` until the returned PNG exceeds `minSize` bytes — a
+ /// heuristic that reliably distinguishes "framebuffer still black / boot
+ /// splash" from "actual UI rendered."
+ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void = {})
+ async throws
+ {
+ let deadline = Date().addingTimeInterval(deadlineSeconds)
+ let tempPath = "/tmp/lume-sip-fb-\(UUID().uuidString.prefix(8)).png"
+ defer { try? FileManager.default.removeItem(atPath: tempPath) }
+ var lastSize = 0
+ var lastError: Error?
+ while Date() < deadline {
+ try heartbeat()
+ do {
+ try run(["capture", tempPath])
+ lastError = nil
+ } catch { lastError = error }
+ let attrs = try? FileManager.default.attributesOfItem(atPath: tempPath)
+ let size = (attrs?[.size] as? NSNumber)?.intValue ?? 0
+ lastSize = size
+ if size >= minSize {
+ Logger.info("Framebuffer ready", metadata: ["label": label, "png_bytes": "\(size)"])
+ return
+ }
+ try await sleep(seconds: 4)
+ }
+ let errorSuffix = lastError.map { "; last capture error: \($0)" } ?? ""
+ throw VNCDriverError.timeout(
+ "Framebuffer for '\(label)' never reached \(minSize) bytes " + "(last: \(lastSize))\(errorSuffix)")
+ }
+
+ /// Poll screenshots until OCR finds an expected terminal result. Failure
+ /// phrases abort immediately so a bad password is reported before the
+ /// workflow accidentally types the shutdown command into another prompt.
+ func waitForText(
+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,
+ label: String, heartbeat: () throws -> Void = {}
+ ) async throws -> String {
+ let deadline = Date().addingTimeInterval(deadlineSeconds)
+ let tempPath = "/tmp/lume-sip-ocr-\(UUID().uuidString.prefix(8)).png"
+ defer { try? FileManager.default.removeItem(atPath: tempPath) }
+ let expected = expectedPhrases.map(Self.normalizeText)
+ let failures = failurePhrases.map(Self.normalizeText)
+ var lastText = ""
+ var lastError: Error?
+
+ while Date() < deadline {
+ try heartbeat()
+ do {
+ try run(["capture", tempPath])
+ lastText = try Self.recognizeText(at: tempPath)
+ lastError = nil
+ let normalized = Self.normalizeText(lastText)
+
+ if let phrase = failures.first(where: normalized.contains) {
+ throw VNCDriverError.unexpectedText("Framebuffer for '\(label)' contained failure text '\(phrase)'")
+ }
+ if expected.contains(where: normalized.contains) { return lastText }
+ } catch let error as VNCDriverError {
+ if case .unexpectedText = error { throw error }
+ lastError = error
+ } catch { lastError = error }
+ try await sleep(seconds: 2)
+ }
+
+ let recognized = Self.normalizeText(lastText)
+ let textSuffix = recognized.isEmpty ? "" : "; last OCR text: \(recognized)"
+ let errorSuffix = lastError.map { "; last OCR error: \($0)" } ?? ""
+ throw VNCDriverError.timeout(
+ "Framebuffer for '\(label)' did not contain expected text" + "\(textSuffix)\(errorSuffix)")
+ }
+
+ /// Type a plain string. Unshifted characters only — see the type doc.
+ func type(_ text: String) throws { try run(["type", text]) }
+
+ /// Type a secret without putting it in the vncdotool process arguments.
+ /// `typefile -` reads the value from the child process's standard input.
+ func typeSensitive(_ text: String) throws {
+ guard let data = text.data(using: .utf8) else { throw VNCDriverError.invalidSensitiveText }
+ try run(["typefile", "-"], standardInput: data)
+ }
+
+ /// Send a single named key (e.g. `enter`, `right`, `y`).
+ func key(_ name: String) throws { try run(["key", name]) }
+
+ /// Send a keyboard chord. `modifiers` come from vncdotool's named-key
+ /// vocabulary (`shift`, `ctrl`, `alt`, `super`/`cmd`).
+ /// NOTE: VZ's VNC server does not reliably route Cmd chords; prefer
+ /// menu-bar clicks + arrow navigation for menu shortcuts.
+ func chord(modifiers: [String], key: String) throws {
+ let chord = (modifiers + [key]).joined(separator: "-")
+ try run(["key", chord])
+ }
+
+ /// Move the pointer to (x, y) and left-click.
+ func click(x: Int, y: Int) throws { try run(["move", "\(x)", "\(y)", "click", "1"]) }
+
+ /// Snapshot the current framebuffer to the screenshot dir if configured.
+ /// Silent no-op when the dir isn't set.
+ func snapshot(_ tag: String) throws {
+ guard let dir = screenshotDir else { return }
+ try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
+ let path = "\(dir)/\(tag).png"
+ try run(["capture", path])
+ }
+
+ // MARK: - Internals
+
+ private func canConnect() -> Bool {
+ let host = CFHostCreateWithName(nil, self.host as CFString).takeRetainedValue()
+ var readStream: Unmanaged<CFReadStream>?
+ var writeStream: Unmanaged<CFWriteStream>?
+ CFStreamCreatePairWithSocketToCFHost(nil, host, Int32(port), &readStream, &writeStream)
+ defer {
+ readStream?.release()
+ writeStream?.release()
+ }
+ guard let r = readStream?.takeUnretainedValue() else { return false }
+ let ok = CFReadStreamOpen(r)
+ if ok { CFReadStreamClose(r) }
+ return ok
+ }
+
+ private func run(_ args: [String], standardInput: Data? = nil) throws {
+ let outputURL = FileManager.default.temporaryDirectory.appendingPathComponent(
+ "lume-vncdo-\(UUID().uuidString).log"
+ )
+ guard FileManager.default.createFile(
+ atPath: outputURL.path,
+ contents: nil,
+ attributes: [.posixPermissions: 0o600]
+ ) else {
+ throw VNCDriverError.outputCaptureFailed
+ }
+ let outputHandle: FileHandle
+ do {
+ outputHandle = try FileHandle(forWritingTo: outputURL)
+ } catch {
+ try? FileManager.default.removeItem(at: outputURL)
+ throw VNCDriverError.outputCaptureFailed
+ }
+ defer {
+ try? outputHandle.close()
+ try? FileManager.default.removeItem(at: outputURL)
+ }
+
+ let p = Process()
+ p.executableURL = URL(fileURLWithPath: vncdo)
+ p.arguments = ["-s", target, "-p", password, "-t", "30"] + args
+ p.standardOutput = outputHandle
+ p.standardError = outputHandle
+ let input = standardInput.map { _ in Pipe() }
+ p.standardInput = input
+ try p.run()
+ if let standardInput, let input {
+ input.fileHandleForWriting.write(standardInput)
+ try? input.fileHandleForWriting.close()
+ }
+
+ let deadline = Date().addingTimeInterval(35)
+ while p.isRunning && Date() < deadline {
+ Thread.sleep(forTimeInterval: 0.05)
+ }
+ if p.isRunning {
+ p.terminate()
+ Thread.sleep(forTimeInterval: 0.2)
+ if p.isRunning {
+ Darwin.kill(p.processIdentifier, SIGKILL)
+ }
+ p.waitUntilExit()
+ throw VNCDriverError.timeout("vncdotool command exceeded 35 seconds")
+ }
+
+ try? outputHandle.synchronize()
+ let outputData = (try? Data(contentsOf: outputURL)) ?? Data()
+ let outputText =
+ String(data: outputData, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+ if p.terminationStatus != 0 { throw VNCDriverError.commandFailed(args, p.terminationStatus, outputText) }
+ }
+
+ private static func recognizeText(at path: String) throws -> String {
+ let request = VNRecognizeTextRequest()
+ request.recognitionLevel = .accurate
+ request.usesLanguageCorrection = false
+ request.recognitionLanguages = ["en-US"]
+ let handler = VNImageRequestHandler(url: URL(fileURLWithPath: path))
+ try handler.perform([request])
+ return (request.results ?? []).compactMap { $0.topCandidates(1).first?.string }.joined(separator: "\n")
+ }
+
+ private static func normalizeText(_ text: String) -> String {
+ text.lowercased().split(whereSeparator: { $0.isWhitespace }).joined(separator: " ")
+ }
+
+ private func sleep(seconds: Double) async throws {
+ try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+ }
+}
+
+enum VNCDriverError: Error, CustomStringConvertible {
+ case timeout(String)
+ case commandFailed([String], Int32, String)
+ case unexpectedText(String)
+ case invalidSensitiveText
+ case outputCaptureFailed
+
+ var description: String {
+ switch self {
+ case .timeout(let msg): return "VNC driver timeout: \(msg)"
+ case .commandFailed(let args, let code, let output):
+ let suffix = output.isEmpty ? "" : ": \(output)"
+ return "vncdotool \(args.joined(separator: " ")) exited with \(code)\(suffix)"
+ case .unexpectedText(let msg): return "VNC terminal check failed: \(msg)"
+ case .invalidSensitiveText: return "The sensitive VNC input could not be encoded as UTF-8"
+ case .outputCaptureFailed: return "Could not create a private vncdotool output log"
+ }
+ }
+}
diff --git a/libs/lume/src/Virtualization/VMVirtualizationService.swift b/libs/lume/src/Virtualization/VMVirtualizationService.swift
index cf00bc4d70..b4560c4b0a 100644
--- a/libs/lume/src/Virtualization/VMVirtualizationService.swift
+++ b/libs/lume/src/Virtualization/VMVirtualizationService.swift
@@ -326,6 +326,43 @@ final class DarwinVirtualizationService: BaseVirtualizationService {
spiceAgentConsoleDevice.ports[0] = spiceAgentPort
vzConfig.consoleDevices.append(spiceAgentConsoleDevice)
+ // Optional serial console for debugging. When LUME_SERIAL_CONSOLE points
+ // at a writable path, attach a virtio serial port whose output is written
+ // there. Useful for observing early boot / recoveryOS behaviour that has
+ // no other headless channel.
+ if let serialLogPath = ProcessInfo.processInfo.environment["LUME_SERIAL_CONSOLE"],
+ !serialLogPath.isEmpty
+ {
+ if !FileManager.default.fileExists(atPath: serialLogPath) {
+ FileManager.default.createFile(atPath: serialLogPath, contents: nil)
+ }
+ if let writeHandle = FileHandle(forWritingAtPath: serialLogPath) {
+ writeHandle.seekToEndOfFile()
+ let serialAttachment = VZFileHandleSerialPortAttachment(
+ fileHandleForReading: nil,
+ fileHandleForWriting: writeHandle
+ )
+ // 1) Classic virtio serial port.
+ let serialPort = VZVirtioConsoleDeviceSerialPortConfiguration()
+ serialPort.attachment = serialAttachment
+ vzConfig.serialPorts = [serialPort]
+ // 2) A virtio console port marked isConsole, which designates it
+ // as the system console — some guests route console output here.
+ let consoleDevice = VZVirtioConsoleDeviceConfiguration()
+ let consolePort = VZVirtioConsolePortConfiguration()
+ consolePort.isConsole = true
+ consolePort.name = "lume.console"
+ consolePort.attachment = serialAttachment
+ consoleDevice.ports[0] = consolePort
+ vzConfig.consoleDevices.append(consoleDevice)
+ Logger.info("Attached serial console", metadata: ["path": serialLogPath])
+ } else {
+ Logger.error(
+ "Failed to open serial console log for writing",
+ metadata: ["path": serialLogPath])
+ }
+ }
+
// Directory sharing
let directorySharingDevices = createDirectorySharingDevices(
sharedDirectories: config.sharedDirectories)
diff --git a/libs/lume/tests/CommandDocExtractorTests.swift b/libs/lume/tests/CommandDocExtractorTests.swift
new file mode 100644
index 0000000000..f91aaafba7
--- /dev/null
+++ b/libs/lume/tests/CommandDocExtractorTests.swift
@@ -0,0 +1,12 @@
+import Testing
+
+@testable import lume
+
+@Test("CLI reference covers every registered command")
+func commandDocumentationCoversRegistry() {
+ let coverage = CommandDocExtractor.documentationCoverage
+
+ #expect(coverage.missing.isEmpty)
+ #expect(coverage.extra.isEmpty)
+ #expect(CommandDocExtractor.extractAll().commands.contains { $0.name == "sip" })
+}
diff --git a/libs/lume/tests/LumeControllerTests.swift b/libs/lume/tests/LumeControllerTests.swift
index a21548dace..9550bd64c3 100644
--- a/libs/lume/tests/LumeControllerTests.swift
+++ b/libs/lume/tests/LumeControllerTests.swift
@@ -34,6 +34,20 @@ private final class FailingVMFactory: VMFactory {
}
}
+@MainActor
+private final class TestVMFactory: VMFactory {
+ func createVM(
+ vmDirContext: VMDirContext,
+ imageLoader: ImageLoader?
+ ) throws -> VM {
+ MockVM(
+ vmDirContext: vmDirContext,
+ virtualizationServiceFactory: { _ in MockVMVirtualizationService() },
+ vncServiceFactory: { MockVNCService(vmDirectory: $0) }
+ )
+ }
+}
+
@MainActor
@Test("create cleans up pre-created VM directory when setup fails")
func testCreateCleansUpPrecreatedDirectoryOnFailure() async throws {
@@ -87,6 +101,68 @@ func testCreateCleansUpPrecreatedDirectoryOnFailure() async throws {
#expect(!orphanVMDir.exists())
}
+@MainActor
+@Test("clone preserves paired disk and auxiliary storage")
+func testClonePreservesPairedBootPolicyState() throws {
+ let tempConfigDir = try createTempDirectory()
+ let tempHomeDir = try createTempDirectory()
+
+ defer {
+ try? FileManager.default.removeItem(at: tempConfigDir)
+ try? FileManager.default.removeItem(at: tempHomeDir)
+ }
+
+ let previousXDGConfigHome = ProcessInfo.processInfo.environment["XDG_CONFIG_HOME"]
+ setenv("XDG_CONFIG_HOME", tempConfigDir.path, 1)
+ defer {
+ if let previousXDGConfigHome {
+ setenv("XDG_CONFIG_HOME", previousXDGConfigHome, 1)
+ } else {
+ unsetenv("XDG_CONFIG_HOME")
+ }
+ }
+
+ let settingsManager = SettingsManager(fileManager: .default)
+ try settingsManager.setHomeDirectory(path: tempHomeDir.path)
+ let home = Home(settingsManager: settingsManager, fileManager: .default)
+ let controller = LumeController(home: home, vmFactory: TestVMFactory())
+
+ let sourceDir = try home.getVMDirectory("sip-off-seed")
+ try FileManager.default.createDirectory(
+ at: sourceDir.dir.url,
+ withIntermediateDirectories: true
+ )
+
+ let diskData = Data(repeating: 0xA5, count: 1024 * 1024)
+ let nvramData = Data((0..<4096).map { UInt8($0 % 251) })
+ try diskData.write(to: sourceDir.diskPath.url)
+ try nvramData.write(to: sourceDir.nvramPath.url)
+
+ let sourceMachineIdentifier = Data(repeating: 0x11, count: 32)
+ let sourceMacAddress = "02:00:00:00:00:01"
+ let sourceConfig = try VMConfig(
+ os: "macOS",
+ cpuCount: 4,
+ memorySize: 8 * 1024 * 1024 * 1024,
+ diskSize: UInt64(diskData.count),
+ macAddress: sourceMacAddress,
+ display: "1024x768",
+ hardwareModel: Data(repeating: 0x22, count: 32),
+ machineIdentifier: sourceMachineIdentifier
+ )
+ try sourceDir.saveConfig(sourceConfig)
+
+ try controller.clone(name: "sip-off-seed", newName: "worker-001")
+
+ let cloneDir = try home.getVMDirectory("worker-001")
+ let cloneConfig = try cloneDir.loadConfig()
+
+ #expect(try Data(contentsOf: cloneDir.diskPath.url) == diskData)
+ #expect(try Data(contentsOf: cloneDir.nvramPath.url) == nvramData)
+ #expect(cloneConfig.machineIdentifier != sourceMachineIdentifier)
+ #expect(cloneConfig.macAddress != sourceMacAddress)
+}
+
private func createTempDirectory() throws -> URL {
let tempDir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
diff --git a/libs/lume/tests/SipTests.swift b/libs/lume/tests/SipTests.swift
new file mode 100644
index 0000000000..aad4ef8f46
--- /dev/null
+++ b/libs/lume/tests/SipTests.swift
@@ -0,0 +1,166 @@
+import Foundation
+import Testing
+
+@testable import lume
+
+@MainActor private final class MockRecoveryVNCDriver: RecoveryVNCDriving {
+ var events: [String] = []
+ var receivedSensitiveInput = false
+ var usesDirectAccountPrompt = false
+
+ func waitForListening(deadlineSeconds: Double, heartbeat: () throws -> Void) async throws {
+ try heartbeat()
+ events.append("listening")
+ }
+
+ func waitForFramebuffer(minSize: Int, deadlineSeconds: Double, label: String, heartbeat: () throws -> Void)
+ async throws
+ {
+ try heartbeat()
+ events.append("framebuffer:\(label)")
+ }
+
+ func waitForText(
+ containing expectedPhrases: [String], rejecting failurePhrases: [String], deadlineSeconds: Double,
+ label: String, heartbeat: () throws -> Void
+ ) async throws -> String {
+ try heartbeat()
+ let text: String
+ if label == "csrutil prompt" {
+ text = usesDirectAccountPrompt ? expectedPhrases.last ?? "" : "[y/n]"
+ } else {
+ text = expectedPhrases.first ?? ""
+ }
+ events.append("text:\(text)")
+ return text
+ }
+
+ func type(_ text: String) throws { events.append("type:\(text)") }
+
+ func typeSensitive(_ text: String) throws {
+ receivedSensitiveInput = !text.isEmpty
+ events.append("sensitive-input")
+ }
+
+ func key(_ name: String) throws { events.append("key:\(name)") }
+
+ func click(x: Int, y: Int) throws { events.append("click:\(x),\(y)") }
+
+ func snapshot(_ tag: String) throws { events.append("snapshot:\(tag)") }
+}
+
+@MainActor @Test("sip parses stdin credentials and the short confirmation flag") func sipCommandParsing() throws {
+ let root = try Lume.parseAsRoot(["sip", "off", "test-vm", "-y", "--admin-password-stdin"])
+ let command = try #require(root as? Sip)
+
+ #expect(command.state == .off)
+ #expect(command.name == "test-vm")
+ #expect(command.yes)
+ #expect(command.adminPasswordStdin)
+}
+
+@Test("sip validates VM state and target status") func sipValidation() throws {
+ let stoppedMac = vmDetails(os: "macOS", status: "stopped")
+ try Sip.validateInitialState(stoppedMac, expectedName: "test-vm")
+ #expect(Sip.statusMatches("System Integrity Protection status: disabled.", expected: .off))
+ #expect(Sip.statusMatches("System Integrity Protection status: enabled.", expected: .on))
+ #expect(!Sip.statusMatches("System Integrity Protection status: enabled.", expected: .off))
+ let customized = """
+ System Integrity Protection status: enabled (Custom Configuration).
+ Filesystem Protections: disabled
+ Debugging Restrictions: enabled
+ """
+ #expect(!Sip.statusMatches(customized, expected: .off))
+ #expect(!Sip.statusMatches(customized, expected: .on))
+
+ #expect(throws: SipError.self) {
+ try Sip.validateInitialState(vmDetails(os: "linux", status: "stopped"), expectedName: "test-vm")
+ }
+ #expect(throws: SipError.self) {
+ try Sip.validateInitialState(vmDetails(os: "macOS", status: "running"), expectedName: "test-vm")
+ }
+ #expect(throws: SipError.self) { try Sip.requireVNCExecutable(nil) }
+ #expect(throws: SipError.self) { try Sip.validateVNCPasswordCharacters("Uppercase") }
+
+ let vncPasswords = Swift.Set<String>((0..<8).map { _ in Sip.makeVNCPassword() })
+ #expect(vncPasswords.allSatisfy { $0.utf8.count == 8 })
+ #expect(vncPasswords.count > 1)
+}
+
+@MainActor @Test("recovery automation enters the requested csrutil command and verifies its result")
+func sipRecoveryAutomation() async throws {
+ for state in [Sip.State.off, .on] {
+ let driver = MockRecoveryVNCDriver()
+ driver.usesDirectAccountPrompt = state == .on
+ var heartbeats = 0
+ let automator = SipRecoveryAutomator(sleeper: { _ in })
+
+ try await automator.perform(
+ driver: driver, state: state, adminUser: "lume", adminPassword: "secret", heartbeat: { heartbeats += 1 },
+ timeout: { limit, _ in limit })
+
+ let verb = state == .off ? "disable" : "enable"
+ let result = state == .off ? "off" : "on"
+ #expect(driver.events.contains("type:csrutil \(verb)"))
+ #expect(driver.events.contains("text:enter password for user lume:"))
+ #expect(driver.events.contains("key:y") == (state == .off))
+ #expect(driver.events.contains("text:system integrity protection is \(result)."))
+ #expect(driver.events.contains("sensitive-input"))
+ #expect(driver.receivedSensitiveInput)
+ #expect(driver.events.suffix(3).contains("type:sync; shutdown -h now"))
+ #expect(heartbeats > 0)
+ }
+}
+
+@MainActor @Test("sensitive VNC input is sent on stdin and never in argv") func vncSensitiveInputUsesStdin() throws {
+ let directory = FileManager.default.temporaryDirectory.appendingPathComponent(
+ "lume-sip-vnc-test-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let executable = directory.appendingPathComponent("vncdo")
+ let argumentsLog = directory.appendingPathComponent("arguments")
+ let stdinLog = directory.appendingPathComponent("stdin")
+ let script = """
+ #!/bin/sh
+ printf '%s\\n' "$@" > '\(argumentsLog.path)'
+ head -c 262144 /dev/zero
+ cat > '\(stdinLog.path)'
+ """
+ try script.write(to: executable, atomically: true, encoding: .utf8)
+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: executable.path)
+
+ let secret = "sentinel-secret"
+ let driver = VNCDriver(
+ vncdo: executable.path, host: "127.0.0.1", port: 5999, password: "transient-vnc-password", screenshotDir: nil)
+ try driver.typeSensitive(secret)
+
+ let arguments = try String(contentsOf: argumentsLog, encoding: .utf8)
+ let standardInput = try String(contentsOf: stdinLog, encoding: .utf8)
+ #expect(!arguments.contains(secret))
+ #expect(arguments.contains("typefile\n-"))
+ #expect(standardInput == secret)
+}
+
+@MainActor @Test("lume child output cannot fill an undrained pipe") func sipChildProcessHandlesLargeOutput()
+ async throws
+{
+ let child = try SipChildProcess(
+ executable: "/bin/sh", arguments: ["-c", "yes output | head -c 262144"], label: "large-output-test")
+ defer { child.cleanup() }
+
+ try child.start()
+ for _ in 0..<100 where child.isRunning { try await Task.sleep(for: .milliseconds(20)) }
+ if child.isRunning { await child.terminateAndWait() }
+
+ #expect(!child.isRunning)
+ #expect(child.terminationStatus == 0)
+ #expect(!child.outputTail(redacting: []).isEmpty)
+}
+
+private func vmDetails(os: String, status: String) -> VMDetails {
+ VMDetails(
+ name: "test-vm", os: os, cpuCount: 4, memorySize: 8 * 1024 * 1024 * 1024,
+ diskSize: DiskSize(allocated: 1, total: 2), display: "1024x768", status: status, vncUrl: nil, ipAddress: nil,
+ locationName: "home")
+}
diff --git a/scripts/docs-generators/lume.ts b/scripts/docs-generators/lume.ts
index 6142a1b3cd..cd56aafc2d 100644
--- a/scripts/docs-generators/lume.ts
+++ b/scripts/docs-generators/lume.ts
@@ -323,41 +323,44 @@ export function generateCLIReferenceMDX(docs: CLIDocumentation): string {
lines.push('For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).');
lines.push('');
- // Group commands by category
- const vmManagement = ['create', 'run', 'stop', 'delete', 'clone'];
- const vmInfo = ['ls', 'get', 'set'];
- const imageManagement = ['images', 'pull', 'push', 'ipsw', 'prune'];
- const guestAccess = ['ssh', 'setup'];
- const configuration = ['config', 'serve', 'logs', 'check-update', 'update'];
-
- lines.push('## VM Management');
- lines.push('');
- for (const cmd of docs.commands.filter((c) => vmManagement.includes(c.name))) {
- lines.push(...generateCommandDoc(cmd, '###'));
- }
-
- lines.push('## VM Information and Configuration');
- lines.push('');
- for (const cmd of docs.commands.filter((c) => vmInfo.includes(c.name))) {
- lines.push(...generateCommandDoc(cmd, '###'));
- }
-
- lines.push('## Image Management');
- lines.push('');
- for (const cmd of docs.commands.filter((c) => imageManagement.includes(c.name))) {
- lines.push(...generateCommandDoc(cmd, '###'));
- }
+ const groups = [
+ { title: 'VM Management', commands: ['create', 'run', 'stop', 'delete', 'clone'] },
+ { title: 'VM Information and Configuration', commands: ['ls', 'get', 'set'] },
+ {
+ title: 'Image Management',
+ commands: ['images', 'pull', 'push', 'convert', 'ipsw', 'prune'],
+ },
+ { title: 'Guest Access and Security', commands: ['ssh', 'setup', 'sip'] },
+ {
+ title: 'Configuration and Server',
+ commands: ['config', 'serve', 'logs', 'check-update', 'update'],
+ },
+ { title: 'Developer Tools', commands: ['dump-docs'] },
+ ];
- lines.push('## Guest Access and Setup');
- lines.push('');
- for (const cmd of docs.commands.filter((c) => guestAccess.includes(c.name))) {
- lines.push(...generateCommandDoc(cmd, '###'));
+ const assignedCommands = groups.flatMap((group) => group.commands);
+ const duplicateAssignments = assignedCommands.filter(
+ (name, index) => assignedCommands.indexOf(name) !== index
+ );
+ const ungroupedCommands = docs.commands
+ .map((command) => command.name)
+ .filter((name) => !assignedCommands.includes(name));
+
+ if (duplicateAssignments.length > 0 || ungroupedCommands.length > 0) {
+ throw new Error(
+ `CLI command grouping mismatch. Ungrouped: ${[...new Set(ungroupedCommands)].sort().join(', ') || 'none'}; duplicated: ${[...new Set(duplicateAssignments)].sort().join(', ') || 'none'}`
+ );
}
- lines.push('## Configuration and Server');
- lines.push('');
- for (const cmd of docs.commands.filter((c) => configuration.includes(c.name))) {
- lines.push(...generateCommandDoc(cmd, '###'));
+ for (const group of groups) {
+ lines.push(`## ${group.title}`);
+ lines.push('');
+ for (const commandName of group.commands) {
+ const command = docs.commands.find((candidate) => candidate.name === commandName);
+ if (command) {
+ lines.push(...generateCommandDoc(command, '###'));
+ }
+ }
}
// Global options