Run a virtual iPhone on an Apple Silicon Mac.
Swift
cfw: Add opt-in --force-exc-guard for the EXC_GUARD Mach-port-guard patch
zqxwce31772b381896
diff --git a/.gitignore b/.gitignoreindex bb4e7985..e2cafa0b 100644--- a/.gitignore+++ b/.gitignore@@ -330,4 +330,5 @@ setup_logs//research/xnu/vm/vm.backups+/vm-*//debs/diff --git a/Makefile b/Makefileindex 10786d84..6d93c447 100644--- a/Makefile+++ b/Makefile@@ -100,12 +100,17 @@ help:@echo " IPHONE_SOURCE= URL or local path to iPhone IPSW"@echo " CLOUDOS_SOURCE= URL or local path to cloudOS IPSW"@echo " make fw_patch Patch boot chain with Swift pipeline (regular variant)"+ @echo " Options: FORCE_EXC_GUARD=1 Force the EXC_GUARD Mach-port-guard disable patch even on bases"+ @echo " that don't strictly need it to boot (e.g. a 3rd-party app's"+ @echo " crash-reporting SDK trips a fatal GUARD_TYPE_MACH_PORT violation)"@echo " make fw_patch_less Patch boot chain with Swift pipeline (less patches)"@echo " Options: NO_BINPACK=1 Excludes the SSH, VNC, ... binaries from being installed"@echo " NO_VPHONED=1 Excludes vphoned from being installed"@echo " make fw_patch_dev Patch boot chain with Swift pipeline (dev mode TXM patches)"@echo " make fw_patch_jb Patch boot chain with Swift pipeline (dev + JB extensions)"+ @echo " Options: FORCE_EXC_GUARD=1 (see fw_patch above)"@echo " make fw_patch_exp Patch boot chain with Swift pipeline (JB + EXP experimental)"+ @echo " Options: FORCE_EXC_GUARD=1 (see fw_patch above)"@echo ""@echo "Testing:"@echo " make test_jb_patches Run all JB kernel patches (incl. Sandbox) over every supported cloudOS kernel"@@ -340,7 +345,8 @@ fw_prepare:cd $(VM_DIR) && bash "$(CURDIR)/$(SCRIPTS)/fw_prepare.sh"fw_patch: patcher_build- "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant regular+ "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant regular \+ $(if $(filter 1 true yes YES TRUE,$(FORCE_EXC_GUARD)),--force-exc-guard,)UID := $(shell id -u)ifeq ($(UID),0)@@ -359,10 +365,12 @@ fw_patch_dev: patcher_build"$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant devfw_patch_jb: patcher_build- "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant jb+ "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant jb \+ $(if $(filter 1 true yes YES TRUE,$(FORCE_EXC_GUARD)),--force-exc-guard,)fw_patch_exp: patcher_build- "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant exp+ "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" --variant exp \+ $(if $(filter 1 true yes YES TRUE,$(FORCE_EXC_GUARD)),--force-exc-guard,).PHONY: test_jb_patchesdiff --git a/README.md b/README.mdindex 41eeaa63..32adf078 100644--- a/README.md+++ b/README.md@@ -135,6 +135,8 @@ make setup_machine # full automation through "First Boot" (includes r# JB=1 for jailbreak variant (+ full security bypass)# EXP=1 for experimental variant (JB + research patches: hv_vmm rename, DT identity, post-restore rewrite)# SPOOF_BUILD=<id> (EXP only) Rewrite SystemVersion.plist ProductBuildVersion to <id>, e.g. 23F77+# export FORCE_EXC_GUARD=1 before running to force-enable the EXC_GUARD disable+# patch on bases that don't need it to boot (see FAQ: EXC_GUARD crash on launch)```## Manual Setup@@ -150,6 +152,9 @@ make fw_patch # patch boot chain (regular variant)# or: make fw_patch_dev # dev variant (+ TXM entitlement/debug bypasses)# or: make fw_patch_jb # jailbreak variant (+ full security bypass)# or: make fw_patch_exp # experimental variant (JB + research stack)+# add FORCE_EXC_GUARD=1 to fw_patch/fw_patch_jb/fw_patch_exp to force-enable the+# EXC_GUARD (Mach port guard) disable patch on bases that don't need it to boot —+# see FAQ: "My app crashes on launch with EXC_GUARD / GUARD_TYPE_MACH_PORT"```### Cleaning@@ -323,6 +328,20 @@ Reboot the VM. The SSH server will start automatically on the next boot.Yes. The install menu supports both `.ipa` and `.tipa` packages. Drag and drop or use the file picker.+**Q: My app crashes on launch with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` (e.g. `KOBJECT_REPLY_PORT_SEMANTICS`).**++Some third-party apps that bundle a crash-reporting or RASP SDK call `task_swap_exception_ports()` on launch to install their own exception handler. On bases where this isn't required for the VM itself to boot, the research kernel can enforce that as a fatal Mach port guard violation instead of the silent/non-fatal behavior production iOS exhibits for this call pattern (see [issue #291](https://github.com/Lakr233/vphone-cli/issues/291)).++Re-patch with the guard disable force-enabled, then re-flash:++```bash+make fw_prepare # reset to pristine firmware first+make fw_patch_jb FORCE_EXC_GUARD=1 # or fw_patch / fw_patch_exp+# ... boot_dfu, restore_get_shsh, restore, cfw_install_jb, boot as usual+```++This is always on automatically for iOS 18 bases (needed there to boot at all) — the flag only matters for other bases where an app hits this specific crash.+**Q: Can I update to a newer iOS version?**Yes. Override `fw_prepare` with the IPSW URL for the version you want:diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex 00665233..019a5478 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -116,9 +116,9 @@| 15 | `mov w0,#0` | `_handle_fsioc_graft` | Allow fsioc graft | Y | Y | Y || 16 | NOP (3x) | `handle_get_dev_by_role` | Bypass APFS role-lookup deny gates for boot mounts | Y | Y | Y || 17-26 | `mov x0,#0; ret` (5 hooks) | Sandbox MACF ops table | Stub 5 sandbox hooks | Y | Y | Y |-| 27 | `PACIBSP→RET` | `_thread_guard_violation` | Disable fatal EXC_GUARD (Mach port guard) delivery. Dev variant always; regular/jb/exp gain it automatically on **iOS 18 bases** (18.6.2's runningboardd/SpringBoard trip `GUARD_TYPE_MACH_PORT` "flavor 10", a guard the 26.1 kernel enforces fatally, crash-looping the UI). 26.x bases boot without it and are unaffected. | 18† | Y | 18† |+| 27 | `PACIBSP→RET` | `_thread_guard_violation` | Disable fatal EXC_GUARD (Mach port guard) delivery. Dev variant + iOS 18 bases always; regular/jb/exp otherwise opt-in via `--force-exc-guard` (see note below). | Y* | Y | Y* |-† iOS 18 bases only — auto-detected in `FirmwarePipeline` from `iPhone-BuildManifest.plist`'s `ProductVersion` (the pre-hybrid manifest fw_prepare preserves; the live BuildManifest reads the cloudOS 26.1 version). Passed to `KernelPatcher` as `applyExcGuard`, which gates patch 27.+† Always required on iOS 18 bases (18.6.2's runningboardd/SpringBoard trip `GUARD_TYPE_MACH_PORT` "flavor 10", crash-looping the UI — the VM won't boot without it there). On other bases this is opt-in, not always-on: some third-party apps shipping crash-reporting/RASP SDKs (Bugly, Crashlytics, KSCrash, ...) call `task_swap_exception_ports()`, which the research kernel can enforce as a fatal `GUARD_TYPE_MACH_PORT`/`KOBJECT_REPLY_PORT_SEMANTICS` violation (see [upstream issue #291](https://github.com/Lakr233/vphone-cli/issues/291), reproduced and confirmed via crash logs against a `kernelcache.research.vphone600 (26.1/23B85)` build) — but it's not required for the VM itself to boot on 26.x, so it stays opt-in rather than always-on for regular/jb/exp. `applyExcGuard` in `FirmwarePipeline`/`KernelPatcher` is `iosBaseIs18 || forceExcGuard`; pass `--force-exc-guard` to `patch-firmware` (or `FORCE_EXC_GUARD=1` to the relevant `make fw_patch*` target) to enable it on a base that needs it. `iosBaseIs18` (from `iPhone-BuildManifest.plist`'s `ProductVersion`) also still gates the unrelated 18.x skywalk-netagent boot-arg workaround.### JB-Only Kernel Methods (Reference List)diff --git a/sources/FirmwarePatcher/Kernel/KernelPatcher.swift b/sources/FirmwarePatcher/Kernel/KernelPatcher.swiftindex aeffb14b..c81ea1d4 100644--- a/sources/FirmwarePatcher/Kernel/KernelPatcher.swift+++ b/sources/FirmwarePatcher/Kernel/KernelPatcher.swift@@ -16,10 +16,14 @@ public final class KernelPatcher: KernelPatcherBase, Patcher {public var isDev: Bool = false/// When true, apply the EXC_GUARD (Mach port guard) disable even on- /// non-dev variants. Set for iOS 18 bases: their older userland- /// (runningboardd/SpringBoard) trips a Mach port guard the 26.1 kernel- /// enforces fatally (EXC_GUARD, GUARD_TYPE_MACH_PORT "flavor 10"),- /// which crash-loops the UI. Scoped to iOS 18 bases so 26.x is unaffected.+ /// non-dev variants. Always required on iOS 18 bases: their older+ /// userland (runningboardd/SpringBoard) trips a Mach port guard+ /// "flavor 10" that crash-loops the UI. On other bases this is opt-in+ /// (see `FirmwarePipeline`'s `forceExcGuard`/`--force-exc-guard`): some+ /// third-party apps calling task_swap_exception_ports() (crash-reporting/+ /// RASP SDKs) can trip a GUARD_TYPE_MACH_PORT/KOBJECT_REPLY_PORT_SEMANTICS+ /// violation that the research kernel enforces fatally (upstream issue+ /// #291 / PR #297), but it's not required for the VM itself to boot.public var applyExcGuard: Bool = falsepublic convenience init(data: Data, verbose: Bool = true, isDev: Bool, applyExcGuard: Bool = false) {@@ -53,8 +57,7 @@ public final class KernelPatcher: KernelPatcherBase, Patcher {patchSandbox() // 16-25// EXC_GUARD (Mach port guard) disable — applied on the dev variant- // always, and on any variant with an iOS 18 base (see applyExcGuard).- // Not applied to 26.x bases, which boot without it.+ // always, and on regular/jb/exp via applyExcGuard (see its doc comment).if isDev || applyExcGuard {patchExcGuardBehavior() // 26}diff --git a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swiftindex 63da0298..431f7499 100644--- a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift+++ b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift@@ -80,11 +80,12 @@ public final class FirmwarePipeline {let verbose: Boollet noBinpack: Boollet noVphoned: Bool+ let forceExcGuard: Boollet loader: any FirmwareLoader/// Set when the iPhone base is iOS 18.x (read from iPhone-BuildManifest.plist).- /// Gates the EXC_GUARD kernel patch, which iOS 18 bases need but 26.x don't.- /// Computed in `patchAll()` before `buildComponentList()` runs.+ /// Gates the skywalk-netagent boot-arg workaround (18.x-specific mDNSResponder+ /// crash-loop). Computed in `patchAll()` before `buildComponentList()` runs.private var iosBaseIs18 = false/// Set when the iPhone base is iOS 27.x. Gates the iOS-27-only JB kernel patches@@ -100,6 +101,7 @@ public final class FirmwarePipeline {verbose: Bool = true,noBinpack: Bool = false,noVphoned: Bool = false,+ forceExcGuard: Bool = false,loader: (any FirmwareLoader)? = nil) {self.vmDirectory = vmDirectory@@ -107,6 +109,7 @@ public final class FirmwarePipeline {self.verbose = verboseself.noBinpack = noBinpackself.noVphoned = noVphoned+ self.forceExcGuard = forceExcGuardself.loader = loader ?? ContainerFirmwareLoader()}@@ -124,11 +127,11 @@ public final class FirmwarePipeline {// Detect the iPhone base iOS version (from the pre-hybrid manifest that// fw_prepare preserves — the live BuildManifest.plist reads the cloudOS- // version, not the base). iOS 18 bases need the EXC_GUARD patch.+ // version, not the base). iOS 18 bases need the skywalk-netagent boot-arg.let baseVersion = Self.readBaseProductVersion(restoreDir)iosBaseIs18 = baseVersion?.hasPrefix("18.") ?? falseiosBaseIs27 = baseVersion?.hasPrefix("27.") ?? false- let baseGateNote = iosBaseIs18 ? " (enabling iOS-18 EXC_GUARD kernel patch)"+ let baseGateNote = iosBaseIs18 ? " (enabling iOS-18 netagent boot-arg)": iosBaseIs27 ? " (enabling iOS-27 JB kernel patches)" : ""log("[*] iPhone base iOS: \(baseVersion ?? "unknown")\(baseGateNote)")@@ -201,8 +204,17 @@ public final class FirmwarePipeline {var components: [ComponentDescriptor] = []// Captured by value into the patcher factory closures below (avoids- // capturing self). True only for iOS 18 bases; gates the EXC_GUARD patch.- let applyExcGuard = iosBaseIs18+ // capturing self). Always on for iOS 18 bases: 18.6.2's runningboardd/+ // SpringBoard trips GUARD_TYPE_MACH_PORT flavor 10, crash-looping the+ // UI, and the VM won't boot without this patch there. Otherwise off by+ // default and opt-in via `forceExcGuard` (--force-exc-guard):+ // some third-party apps shipping crash-reporting/RASP SDKs call+ // task_swap_exception_ports(), which the research kernel can enforce+ // as a fatal EXC_GUARD/GUARD_TYPE_MACH_PORT/KOBJECT_REPLY_PORT_SEMANTICS+ // violation (see upstream issue #291 / PR #297) — but this isn't+ // required for the VM itself to boot on 26.x, so it stays opt-in+ // rather than always-on for regular/jb/exp.+ let applyExcGuard = iosBaseIs18 || forceExcGuard// Same capture-by-value; true only for iOS 27 bases. Gates the iOS-27-only// JB kernel patches so 18.x/26.x bases apply none of them.diff --git a/sources/vphone-cli/VPhoneCLI.swift b/sources/vphone-cli/VPhoneCLI.swiftindex 9a5cff7e..38e5f904 100644--- a/sources/vphone-cli/VPhoneCLI.swift+++ b/sources/vphone-cli/VPhoneCLI.swift@@ -173,13 +173,20 @@ struct PatchFirmwareCLI: ParsableCommand {@Flag(name: .customLong("no-vphoned"), help: "Exclude vphoned from being installed (patchless-only).")var noVphoned: Bool = false+ @Flag(+ name: .customLong("force-exc-guard"),+ help: "Force-enable the EXC_GUARD (Mach port guard) disable patch on regular/jb/exp, even on bases where it isn't required to boot. Use if a third-party app's crash-reporting/RASP SDK trips a fatal GUARD_TYPE_MACH_PORT violation on launch. Always on for iOS 18 bases regardless of this flag."+ )+ var forceExcGuard: Bool = false+mutating func run() throws {let pipeline = FirmwarePipeline(vmDirectory: vmDirectory,variant: variant.pipelineVariant,verbose: !quiet,noBinpack: noBinpack,- noVphoned: noVphoned+ noVphoned: noVphoned,+ forceExcGuard: forceExcGuard)let records = try pipeline.patchAll()