Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

kernel: add patch 27 — disable thread_guard_violation (EXC_GUARD)

Angus24a9acdf71be
diff --git a/AGENTS.md b/AGENTS.md
index 0ceef984..6a1241dc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,7 +31,7 @@ For any changes applying new patches, also update research/0_binary_patch_compar
| Variant | Boot Chain | CFW | Make Targets |
| --------------- | :---------: | :-------: | ---------------------------------- |
| **Regular** | 51 patches | 10 phases | `fw_patch` + `cfw_install` |
-| **Development** | 64 patches | 12 phases | `fw_patch_dev` + `cfw_install_dev` |
+| **Development** | 65 patches | 12 phases | `fw_patch_dev` + `cfw_install_dev` |
| **Jailbreak** | 126 patches | 14 phases | `fw_patch_jb` + `cfw_install_jb` |
> JB finalization (symlinks, Sileo, apt, TrollStore) runs automatically on first boot via `/cores/vphone_jb_setup.sh` LaunchDaemon. Monitor progress: `/var/log/vphone_jb_setup.log`.
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index 1d27e02d..08d6d5b6 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -71,6 +71,7 @@
| 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 EXC_GUARD delivery (match production behavior) | - | Y | - |
### JB-Only Kernel Methods (Reference List)
@@ -155,20 +156,20 @@
| iBEC | 3 | 3 | 3 |
| LLB | 6 | 6 | 6 |
| TXM | 1 | 12 | 12 |
-| Kernel (base) | 28 | 28 | 28 |
+| Kernel (base) | 28 | 29 | 28 |
| Kernel (JB methods) | - | - | 59 |
-| Boot chain total | 41 | 52 | 112 |
+| Boot chain total | 41 | 53 | 112 |
| CFW binary patches | 4 | 5 | 6 |
| CFW installed components | 6 | 7 | 9 |
| CFW total | 10 | 12 | 15 |
-| Grand total | 51 | 64 | 127 |
+| Grand total | 51 | 65 | 127 |
## Ramdisk Variant Matrix
| Variant | Pre-step | `Ramdisk/txm.img4` | `Ramdisk/krnl.ramdisk.img4` | `Ramdisk/krnl.img4` | Effective kernel used by `ramdisk_send.sh` |
| ------------- | ------------------- | -------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------- |
| `RAMDISK` | `make fw_patch` | release TXM + base TXM patch (1) | base kernel (28), legacy `*.ramdisk` preferred else derive from pristine CloudOS | restore kernel from `fw_patch` (28) | `krnl.ramdisk.img4` preferred, fallback `krnl.img4` |
-| `DEV+RAMDISK` | `make fw_patch_dev` | release TXM + base TXM patch (1) | base kernel (28), same derivation rule | restore kernel from `fw_patch_dev` (28) | `krnl.ramdisk.img4` preferred, fallback `krnl.img4` |
+| `DEV+RAMDISK` | `make fw_patch_dev` | release TXM + base TXM patch (1) | base kernel (28), same derivation rule | restore kernel from `fw_patch_dev` (29) | `krnl.ramdisk.img4` preferred, fallback `krnl.img4` |
| `JB+RAMDISK` | `make fw_patch_jb` | release TXM + base TXM patch (1) | base kernel (28), same derivation rule | restore kernel from `fw_patch_jb` (28+59) | `krnl.ramdisk.img4` preferred, fallback `krnl.img4` |
## Cross-Version Dynamic Snapshot
diff --git a/sources/FirmwarePatcher/Kernel/KernelPatcher.swift b/sources/FirmwarePatcher/Kernel/KernelPatcher.swift
index 6de004c7..699452ce 100644
--- a/sources/FirmwarePatcher/Kernel/KernelPatcher.swift
+++ b/sources/FirmwarePatcher/Kernel/KernelPatcher.swift
@@ -1,4 +1,4 @@
-// KernelPatcher.swift — Regular kernel patcher orchestrator (26 patches).
+// KernelPatcher.swift — Regular kernel patcher orchestrator.
//
// Historical note: this file replaces the old Python firmware patcher implementation.
// Each patch method is defined as an extension in its own file under Patches/.
@@ -12,6 +12,14 @@ import Foundation
public final class KernelPatcher: KernelPatcherBase, Patcher {
public let component = "kernelcache"
+ /// When true, includes dev-only kernel patches (e.g. EXC_GUARD disable).
+ public var isDev: Bool = false
+
+ public convenience init(data: Data, verbose: Bool = true, isDev: Bool) {
+ self.init(data: data, verbose: verbose)
+ self.isDev = isDev
+ }
+
// MARK: - Find All
public func findAll() throws -> [PatchRecord] {
@@ -36,6 +44,11 @@ public final class KernelPatcher: KernelPatcherBase, Patcher {
patchApfsMount() // 13-15
patchSandbox() // 16-25
+ // Dev-only patches (not applied to regular or JB variants)
+ if isDev {
+ patchExcGuardBehavior() // 26 (dev only)
+ }
+
return patches
}
diff --git a/sources/FirmwarePatcher/Kernel/Patches/KernelPatchExcGuard.swift b/sources/FirmwarePatcher/Kernel/Patches/KernelPatchExcGuard.swift
new file mode 100644
index 00000000..a6f83c3c
--- /dev/null
+++ b/sources/FirmwarePatcher/Kernel/Patches/KernelPatchExcGuard.swift
@@ -0,0 +1,109 @@
+// KernelPatchExcGuard.swift — Disable EXC_GUARD for Mach port guard violations.
+//
+// Research kernels enforce Mach port guard violations as fatal EXC_GUARD exceptions.
+// Any app calling task_swap_exception_ports() on a guarded port is killed with
+// EXC_GUARD. This commonly affects apps that install custom exception handlers.
+// Production iOS kernels do not enforce these fatally.
+//
+// The enforcement path is: guard check → thread_guard_violation() → AST delivery.
+// thread_guard_violation stores violation info in the thread struct and triggers an
+// AST that delivers the fatal EXC_GUARD exception when the thread returns to userspace.
+//
+// Patch strategy: find thread_guard_violation via anchor chain and replace its first
+// instruction with RET so it returns immediately without recording or delivering
+// the violation. This disables ALL Mach port guard violations (acceptable for
+// research VMs where guard enforcement is not needed).
+//
+// Anchor chain:
+// 1. "com.apple.security.only-one-exception-port" string
+// 2. → ADRP+ADD code ref in set_exception_behavior_allowed() [may be dead code]
+// 3. → scan function body for BL to set_exception_behavior_violation()
+// 4. → in that target, find BL to thread_guard_violation()
+// 5. → patch thread_guard_violation prologue to RET
+
+import Capstone
+import Foundation
+
+extension KernelPatcher {
+ /// Disable Mach port guard violation enforcement (EXC_GUARD).
+ ///
+ /// Patches `thread_guard_violation` to return immediately, preventing
+ /// all guard violations from being delivered as fatal exceptions.
+ @discardableResult
+ func patchExcGuardBehavior() -> Bool {
+ log("\n[26] exc_guard: disable thread_guard_violation")
+
+ // Step 1: locate the anchor string.
+ guard let strOff = buffer.findString("com.apple.security.only-one-exception-port") else {
+ log(" [-] anchor string not found")
+ return false
+ }
+
+ // Step 2: find ADRP+ADD code reference (inside set_exception_behavior_allowed).
+ let refs = findStringRefs(strOff)
+ guard let (_, addOff) = refs.first else {
+ log(" [-] no code ref to anchor string")
+ return false
+ }
+
+ // Step 3: scan the surrounding function for BL instructions to find
+ // set_exception_behavior_violation. It's the BL whose target starts with
+ // PACIBSP and contains a TBZ/TBNZ within the first ~10 instructions
+ // (the thid_should_crash check), followed by a BL (to thread_guard_violation).
+ // Scan a wide window around the string ref (the function may be ~600 bytes)
+ let scanStart = max(0, addOff - 200)
+ let scanEnd = min(buffer.count - 4, addOff + 400)
+ for off in stride(from: scanStart, to: scanEnd, by: 4) {
+ let insn = buffer.readU32(at: off)
+ guard insn >> 26 == 0b100101 else { continue } // BL
+ let imm26 = insn & 0x03FF_FFFF
+ let signedImm = Int32(bitPattern: imm26 << 6) >> 6
+ let target = off + Int(signedImm) * 4
+ guard target > 0, target + 40 <= buffer.count else { continue }
+ // Check if target starts with PACIBSP
+ guard buffer.readU32(at: target) == ARM64.pacibspU32 else { continue }
+ // Check if target contains TBZ/TBNZ within first 20 instructions
+ // followed by a BL (pattern of set_exception_behavior_violation)
+ var hasTbCheck = false
+ var innerBLTarget: Int? = nil
+ for delta in stride(from: 4, through: 20 * 4, by: 4) {
+ let ioff = target + delta
+ guard ioff + 4 <= buffer.count else { break }
+ let iraw = buffer.readU32(at: ioff)
+ // TBZ/TBNZ: [30:25] = 01101x
+ if (iraw & 0x7E000000) == 0x36000000 {
+ hasTbCheck = true
+ }
+ // After TBZ, look for BL
+ if hasTbCheck, iraw >> 26 == 0b100101 {
+ let iimm26 = iraw & 0x03FF_FFFF
+ let isigned = Int32(bitPattern: iimm26 << 6) >> 6
+ let bt = ioff + Int(isigned) * 4
+ if bt > 0, bt + 4 <= buffer.count,
+ buffer.readU32(at: bt) == ARM64.pacibspU32
+ {
+ innerBLTarget = bt
+ }
+ break
+ }
+ }
+ if let inner = innerBLTarget {
+ log(" [*] set_exception_behavior_violation at foff 0x\(String(format: "%X", target))")
+ log(" [*] thread_guard_violation at foff 0x\(String(format: "%X", inner))")
+ // Step 4: patch thread_guard_violation → RET
+ let va = fileOffsetToVA(inner)
+ emit(
+ inner,
+ ARM64.ret,
+ patchID: "kernel.thread_guard_violation",
+ virtualAddress: va,
+ description: "PACIBSP→RET (disable guard violation delivery)"
+ )
+ return true
+ }
+ }
+
+ log(" [-] thread_guard_violation not found via anchor chain")
+ return false
+ }
+}
diff --git a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
index 533d4a7b..9dda3a70 100644
--- a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
+++ b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
@@ -261,14 +261,18 @@ public final class FirmwarePipeline {
return switch variant {
case .less:
[]
- case .regular, .dev:
+ case .regular:
+ [{ data, verbose in
+ KernelPatcher(data: data, verbose: verbose, isDev: false)
+ }]
+ case .dev:
[{ data, verbose in
- KernelPatcher(data: data, verbose: verbose)
+ KernelPatcher(data: data, verbose: verbose, isDev: true)
}]
case .jb:
[
{ data, verbose in
- KernelPatcher(data: data, verbose: verbose)
+ KernelPatcher(data: data, verbose: verbose, isDev: false)
},
{ data, verbose in
KernelJBPatcher(data: data, verbose: verbose)