1#!/usr/bin/env python3
2import argparse
3import contextlib
4import fcntl
5import hashlib
6import json
7import logging
8import multiprocessing
9import os
10from pathlib import Path
11import re
12import select
13import secrets
14import shlex
15import signal
16import socket
17import socketserver
18import struct
19import subprocess
20import sys
21import tempfile
22import threading
23import time
24
25
26ROOT = Path(os.environ.get("MAC_AGENT_VM_HOME", "/Volumes/Documents/VM/macOS Code Sandbox"))
27TART = ROOT / "runtime/tart.app/Contents/MacOS/tart"
28NAME = "gui-agent"
29PRIVATE = ROOT / "private"
30# Never reach the guest with `tart exec` or `tart ip --resolver=agent` unless it needs the GUI session:
31# their vsock connect intermittently traps inside Virtualization.framework and kills the whole VM.
32GUEST = "admin@AgentVM.local"
33
34
35def tart(*args, **kwargs):
36 return subprocess.run([str(TART), *args], env={**os.environ, "TART_HOME": str(ROOT / "state")},
37 check=True, **kwargs)
38
39
40def ssh_args():
41 return ["ssh", "-F", "/dev/null", "-i", str(PRIVATE / "ssh_key"),
42 "-o", "AddressFamily=inet", "-o", "IdentitiesOnly=yes", "-o", "BatchMode=yes", "-o", "ForwardAgent=no",
43 "-o", "StrictHostKeyChecking=yes", "-o", "HostKeyAlias=" + NAME,
44 "-o", f'UserKnownHostsFile="{PRIVATE / "known_hosts"}"',
45 "-o", "GlobalKnownHostsFile=/dev/null", "-o", "ConnectTimeout=10"]
46
47
48def guest(*command, **kwargs):
49 kwargs.setdefault("check", True)
50 return subprocess.run([*ssh_args(), GUEST, shlex.join(command)], **kwargs)
51
52
53def guest_ready(**kwargs):
54 guest("/bin/sh", "-c", '[ "$(/usr/bin/stat -f %Su /dev/console)" = admin ]', **kwargs)
55
56
57def shut_down():
58 # ssh can drop as the guest powers off, so the stopped state is the proof.
59 guest("sudo", "-n", "shutdown", "-h", "now", check=False, timeout=15)
60 wait_for_state("stopped")
61
62
63def exact(stream, size):
64 data = bytearray()
65 while len(data) < size:
66 chunk = stream.recv(size - len(data))
67 if not chunk:
68 raise ConnectionError("VNC connection closed")
69 data.extend(chunk)
70 return bytes(data)
71
72
73def vm():
74 rows = json.loads(tart("list", "--format", "json", capture_output=True, text=True).stdout)
75 return next(row for row in rows if row["Name"] == NAME and row["Source"] == "local")
76
77
78def wait_for_state(state):
79 for _ in range(90):
80 if vm()["State"] == state:
81 return
82 time.sleep(1)
83 raise ValueError(f"The guest has not reached {state}; inspect status before another lifecycle action.")
84
85
86@contextlib.contextmanager
87def guest_screen():
88 with tempfile.TemporaryDirectory(prefix="vnc-", dir=PRIVATE) as directory:
89 path = Path(directory) / "console.sock"
90 tunnel = subprocess.Popen([*ssh_args(), "-N", "-o", "ExitOnForwardFailure=yes",
91 "-o", "ServerAliveInterval=5", "-o", "ServerAliveCountMax=2",
92 "-o", "StreamLocalBindMask=0177", "-L",
93 f"{path}:127.0.0.1:5900", GUEST],
94 stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
95 stderr=subprocess.DEVNULL)
96 try:
97 for _ in range(100):
98 if tunnel.poll() is not None:
99 raise ValueError("The guest console is unavailable. Wait for the VM to start, then reconnect.")
100 if path.exists():
101 break
102 time.sleep(0.1)
103 else:
104 raise ValueError("The guest console tunnel did not start. Reconnect to try again.")
105 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as upstream:
106 upstream.settimeout(10)
107 upstream.connect(str(path))
108 authenticate_screen(upstream)
109 yield upstream
110 finally:
111 tunnel.terminate()
112 try:
113 tunnel.wait(timeout=5)
114 except subprocess.TimeoutExpired:
115 tunnel.kill()
116 tunnel.wait()
117
118
119def authenticate_screen(upstream):
120 from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
121 password = (PRIVATE / "password").read_bytes()
122 if len(password) > 63:
123 raise ValueError("Apple Screen Sharing supports at most 63 UTF-8 password bytes.")
124 if not exact(upstream, 12).startswith(b"RFB 003."):
125 raise ValueError("Unsupported VNC server version")
126 upstream.sendall(b"RFB 003.008\n")
127 kinds = exact(upstream, exact(upstream, 1)[0])
128 if 30 not in kinds:
129 raise ValueError("The guest does not offer Apple Screen Sharing authentication.")
130 upstream.sendall(b"\x1e")
131 generator, size = struct.unpack(">HH", exact(upstream, 4))
132 if not 16 <= size <= 512:
133 raise ValueError("The guest sent an unsupported Screen Sharing key size.")
134 prime = int.from_bytes(exact(upstream, size), "big")
135 public = int.from_bytes(exact(upstream, size), "big")
136 if not 1 < generator < prime or not 1 < public < prime - 1:
137 raise ValueError("The guest sent invalid Screen Sharing key parameters.")
138 private = secrets.randbelow(prime - 3) + 2
139 client_public = pow(generator, private, prime).to_bytes(size, "big")
140 shared = pow(public, private, prime).to_bytes(size, "big")
141 credentials = bytearray(secrets.token_bytes(128))
142 credentials[:6] = b"admin\0"
143 credentials[64:65 + len(password)] = password + b"\0"
144 # MD5 and AES-ECB are Apple RFB type 30's wire protocol, carried inside pinned SSH.
145 encryptor = Cipher(algorithms.AES(hashlib.md5(shared).digest()), modes.ECB()).encryptor()
146 upstream.sendall(encryptor.update(bytes(credentials)) + encryptor.finalize() + client_public)
147 if exact(upstream, 4) != b"\0\0\0\0":
148 raise ValueError("VNC authentication failed")
149
150
151def relay_screen(upstream, incoming, outgoing):
152 def read(size):
153 data = bytearray()
154 while len(data) < size:
155 chunk = os.read(incoming, size - len(data))
156 if not chunk:
157 raise ConnectionError("The viewer disconnected.")
158 data.extend(chunk)
159 return bytes(data)
160
161 def write(data):
162 while data:
163 data = data[os.write(outgoing, data):]
164
165 write(b"RFB 003.008\n")
166 if not read(12).startswith(b"RFB 003."):
167 raise ValueError("Unsupported viewer protocol.")
168 write(b"\x01\x01")
169 if read(1) != b"\x01":
170 return
171 write(b"\0\0\0\0")
172 upstream.settimeout(None)
173 while True:
174 ready, _, _ = select.select([upstream, incoming], [], [], 300)
175 for source in ready:
176 data = os.read(source if isinstance(source, int) else source.fileno(), 65536)
177 if not data:
178 return
179 if source is upstream:
180 write(data)
181 else:
182 upstream.sendall(data)
183
184
185def console(host, port):
186 from websockify.auth_plugins import AuthenticationError
187 from websockify.websocketproxy import ProxyRequestHandler, WebSocketProxy
188
189 def terminate(signum, frame):
190 raise SystemExit(0)
191
192 signal.signal(signal.SIGTERM, terminate)
193 logging.basicConfig(level=logging.INFO, format="%(message)s")
194 multiprocessing.set_start_method("fork")
195
196 class SameOrigin:
197 def authenticate(self, headers, target_host, target_port):
198 if headers.get("Host") != f"{host}:{port}" or headers.get("Origin") != f"http://{host}:{port}":
199 raise AuthenticationError(response_msg="This console accepts only its configured origin.")
200
201 class ConsoleHandler(ProxyRequestHandler):
202 def do_GET(self):
203 if self.headers.get("Host") != f"{host}:{port}":
204 self.send_error(403)
205 return
206 super().do_GET()
207
208 class Relay(socketserver.BaseRequestHandler):
209 def handle(self):
210 with guest_screen() as upstream:
211 relay_screen(upstream, self.request.fileno(), self.request.fileno())
212
213 with socketserver.ThreadingTCPServer(("127.0.0.1", 0), Relay) as server:
214 server.daemon_threads = True
215 threading.Thread(target=server.serve_forever, daemon=True).start()
216 print(f"http://{host}:{port}/vnc_lite.html?autoconnect=true&resize=scale", flush=True)
217 try:
218 WebSocketProxy(RequestHandlerClass=ConsoleHandler, listen_host=host, listen_port=port,
219 web=str(ROOT / "runtime/novnc"), file_only=True, auth_plugin=SameOrigin(),
220 target_host="127.0.0.1", target_port=server.server_address[1]).start_server()
221 finally:
222 server.shutdown()
223
224
225def main():
226 parser = argparse.ArgumentParser(description="Manage this Mac's isolated GUI-agent VM.")
227 sub = parser.add_subparsers(dest="action", required=True)
228 sub.add_parser("start")
229 sub.add_parser("status")
230 sub.add_parser("stop")
231 sub.add_parser("suspend")
232 sub.add_parser("reboot")
233 sub.add_parser("revive", help="Start the VM unless it is running or was stopped on purpose")
234 for action in ["exec", "ssh"]:
235 command = sub.add_parser(action)
236 command.add_argument("command", nargs=argparse.REMAINDER)
237 forward = sub.add_parser("forward", help="Reach a guest loopback server from this Mac")
238 forward.add_argument("port", type=int, help="Guest server port")
239 forward.add_argument("--local-port", type=int, help="Host loopback port (default: same as guest)")
240 viewer = sub.add_parser("console")
241 viewer.add_argument("--listen", default="127.0.0.1")
242 viewer.add_argument("--port", type=int, default=17891)
243 args = parser.parse_args()
244 if args.action == "forward":
245 local_port = args.local_port if args.local_port is not None else args.port
246 if not 1 <= args.port <= 65535 or not 1 <= local_port <= 65535:
247 parser.error("Ports must be between 1 and 65535.")
248 print(f"Forwarding http://127.0.0.1:{local_port} to guest port {args.port}; Ctrl-C closes the tunnel.",
249 file=sys.stderr, flush=True)
250 os.execvp("ssh", [*ssh_args(), "-N", "-T", "-o", "ExitOnForwardFailure=yes",
251 "-o", "ServerAliveInterval=5", "-o", "ServerAliveCountMax=2",
252 "-L", f"127.0.0.1:{local_port}:127.0.0.1:{args.port}", GUEST])
253 if args.action == "revive":
254 if (PRIVATE / "stopped").exists() or vm()["Running"]:
255 return
256 crashes = sorted(Path("/Library/Logs/DiagnosticReports").glob("tart-*.ips"))
257 print(f"{time.ctime()}: VM is down; newest tart crash report: {crashes[-1] if crashes else 'none'}", flush=True)
258 args.action = "start"
259 if args.action in {"start", "stop", "suspend", "reboot"}:
260 lock = (PRIVATE / "lifecycle.lock").open("a")
261 os.chmod(PRIVATE / "lifecycle.lock", 0o600)
262 try:
263 fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
264 except BlockingIOError:
265 raise ValueError("Another VM power operation is running. Wait for it to finish.") from None
266 lock.seek(0)
267 lock.truncate()
268 lock.write(args.action)
269 lock.flush()
270 if args.action == "reboot":
271 shut_down()
272 args.action = "start"
273 if args.action == "start":
274 (PRIVATE / "stopped").unlink(missing_ok=True)
275 interface = re.search(r"interface: (\S+)", subprocess.run(["/sbin/route", "-n", "get", "default"],
276 capture_output=True, text=True, check=True).stdout)[1]
277 if vm()["Running"]:
278 print("GUI-agent VM is already running.")
279 else:
280 # Closing an agent session kills every process it ever spawned, so sshd must own the VM.
281 # Bridged so iPhones can find and pair with the guest's Xcode over Bonjour.
282 run = shlex.join(["nohup", "/usr/bin/env", f"TART_HOME={ROOT / 'state'}", "/usr/bin/caffeinate", "-i",
283 str(TART), "run", NAME, "--no-graphics", "--no-audio", "--no-usb-accessories",
284 "--no-clipboard", "--suspendable", "--root-disk-opts=sync=full",
285 f"--net-bridged={interface}"])
286 (PRIVATE / "run.log").write_text("")
287 os.chmod(PRIVATE / "run.log", 0o600)
288 subprocess.run(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=10", "localhost",
289 f"{run} >{shlex.quote(str(PRIVATE / 'run.log'))} 2>&1 </dev/null &"], check=True)
290 deadline = time.monotonic() + 90
291 while True:
292 if time.monotonic() > deadline:
293 raise ValueError("VM startup is still pending; inspect status before retrying.")
294 if subprocess.run(["pgrep", "-f", f"tart run {NAME}"], capture_output=True).returncode:
295 raise ValueError("VM startup failed; inspect the private run log locally.")
296 try:
297 guest_ready(capture_output=True, timeout=5)
298 except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
299 time.sleep(1)
300 else:
301 break
302 print("GUI-agent VM is ready in its logged-in guest session.")
303 # The bridged guest is on the LAN: only this Mac may reach its services; iPhones pair on ephemeral ports.
304 host = subprocess.run(["/usr/sbin/ipconfig", "getifaddr", interface],
305 capture_output=True, text=True, check=True).stdout.strip()
306 guest("sudo", "-n", "/bin/sh", "-c",
307 "/sbin/pfctl -q -a com.apple/net.paperclover -f - && /sbin/pfctl -q -E",
308 input=f"table <mac-host> {{ {host} }}\n"
309 "block in quick on ! lo0 proto tcp from ! <mac-host> to any port < 49152 flags S/SA\n"
310 "block in quick on ! lo0 proto udp to any port { 88 137 138 }\n",
311 capture_output=True, text=True)
312 elif args.action == "status":
313 tart("get", NAME)
314 elif args.action == "exec":
315 if not args.command:
316 parser.error("exec requires a guest command")
317 tart("exec", "-i", NAME, *args.command)
318 elif args.action == "ssh":
319 command = ssh_args()
320 if not args.command:
321 command.append("-t")
322 os.execvp("ssh", [*command, GUEST, *args.command])
323 elif args.action == "stop":
324 shut_down()
325 (PRIVATE / "stopped").touch()
326 print("GUI-agent VM shut down.")
327 elif args.action == "suspend":
328 tart("suspend", NAME)
329 wait_for_state("suspended")
330 (PRIVATE / "stopped").touch()
331 print("GUI-agent VM suspended.")
332 elif args.action == "console":
333 python = ROOT / "runtime/venv/bin/python"
334 if Path(sys.prefix) != python.parent.parent:
335 os.execv(str(python), [str(python), __file__, *sys.argv[1:]])
336 console(args.listen, args.port)
337
338
339if __name__ == "__main__":
340 try:
341 main()
342 except (ValueError, OSError, subprocess.CalledProcessError) as error:
343 print(str(error), file=sys.stderr)
344 sys.exit(1)