Skip to content

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/.gitignore
index 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/Makefile
index 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 dev
fw_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_patches
diff --git a/README.md b/README.md
index 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.md
index 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.swift
index 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 = false
public 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.swift
index 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: Bool
let noBinpack: Bool
let noVphoned: Bool
+ let forceExcGuard: Bool
let 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 = verbose
self.noBinpack = noBinpack
self.noVphoned = noVphoned
+ self.forceExcGuard = forceExcGuard
self.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.") ?? false
iosBaseIs27 = 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.swift
index 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()