Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Re-sign debugserver in the restore image

Maximilian Paß2eb85ae7a379
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcher.swift
index 44358cb9..50c3852d 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcher.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcher.swift
@@ -107,6 +107,7 @@ public final class CryptexFilesystemPatcher: BufferedPatcher {
(FirmwareRestoreImagePatchSet.launchdCacheLoader, "Patch launchd_cache_loader"),
(FirmwareRestoreImagePatchSet.virtualBluetooth, "Enable LE connections over the virtual Bluetooth controller"),
(FirmwareRestoreImagePatchSet.watchAudio, "Install the virtio sound HAL plugin for a watch"),
+ (FirmwareRestoreImagePatchSet.debugserver, "Re-sign debugserver so it can attach in the guest"),
]
@discardableResult
@@ -223,6 +224,10 @@ public final class CryptexFilesystemPatcher: BufferedPatcher {
try addWatchAudio(targetMount: targetMount)
try patchWatchAudioBudget(targetMount: targetMount)
}
+ if gate.isEnabled(FirmwareRestoreImagePatchSet.debugserver) {
+ print("- Re-signing debugserver for in-guest attach…")
+ try patchDebugserver(targetMount: targetMount)
+ }
try removeHostEventLog(mount: targetMount)
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcherGuestPayload.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcherGuestPayload.swift
index bbf02398..3e349030 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcherGuestPayload.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CryptexFilesystem/CryptexFilesystemPatcherGuestPayload.swift
@@ -251,6 +251,36 @@ extension CryptexFilesystemPatcher {
at: "System/DriverKit/System/Library/dyld")
}
+ /// Re-sign the guest's debugserver so it can attach in the guest: the same
+ /// entitlement change `cfw install` makes (``CustomFirmwareDebugserver``), but
+ /// in the pre-reseal merge, so debugserver's new hash lands in the image's
+ /// regenerated trust cache and the stock kernel admits it. A logged no-op when
+ /// the merged system ships no debugserver (a stock userland carries it only in
+ /// the Developer disk image). Running and attaching also need kernel and TXM
+ /// patches; ``FirmwarePatchSetCatalog/userspaceDebugging`` groups them.
+ func patchDebugserver(targetMount: String) throws {
+ let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
+ let relative = CustomFirmwareDebugserver.guestPath
+ guard try target.isRegularFile(relative) else {
+ print(" [!] debugserver absent in the merged image; re-sign skipped")
+ return
+ }
+ try editGuestFile(relative, targetMount: targetMount, mode: 0o755) { file in
+ guard let source = try VPhoneSigner.entitlements(ofFileAt: file).first(where: { !$0.isEmpty }) else {
+ throw VPhonePatchKit.PatcherError.patchVerificationFailed(
+ "debugserver has no readable entitlements; cannot grant task_for_pid",
+ )
+ }
+ let entitlements = try CustomFirmwareDebugserver.attachEntitlements(from: source)
+ // Replacement, not merge — see CustomFirmwareDebugserver.attachEntitlements.
+ try VPhoneSigner.sign(
+ fileAt: file,
+ options: VPhoneSignOptions(entitlements: entitlements, style: .appleAdHoc),
+ )
+ }
+ print(" [+] Re-signed debugserver with task_for_pid-allow")
+ }
+
/// Path-based patchers only see this private copy. Guest symlinks cannot
/// redirect their reads or writes into the host filesystem.
func editGuestFile(_ relative: String, targetMount: String, mode: mode_t, edit: (URL) throws -> Void) throws {
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/CustomFirmwareDebugserver.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/CustomFirmwareDebugserver.swift
new file mode 100644
index 00000000..d12a1381
--- /dev/null
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/CustomFirmwareDebugserver.swift
@@ -0,0 +1,49 @@
+// CustomFirmwareDebugserver.swift — the debugserver re-sign shared by both install stages.
+//
+// debugserver reaches a guest two ways, and both need the same entitlement
+// change. `cfw install` re-signs it in the restored, mounted system
+// (VPhoneCustomFirmwareInstaller.patchDebugserver). The `minimal` restore-image
+// merge re-signs it in the pre-reseal image
+// (CryptexFilesystemPatcher.patchDebugserver), so its new hash lands in the
+// regenerated trust cache the stock kernel already trusts. The entitlement
+// transform lives here once so the two stages cannot drift.
+
+import Foundation
+
+public enum CustomFirmwareDebugserver {
+ /// debugserver's path in the guest system volume. A stock userland carries it
+ /// only inside the Developer disk image; a research/cloudOS build is where one
+ /// is present to re-sign. Both stages treat its absence as a logged no-op.
+ public static let guestPath = "usr/libexec/debugserver"
+
+ public enum Error: Swift.Error, CustomStringConvertible {
+ case unreadableEntitlements
+ public var description: String {
+ switch self {
+ case .unreadableEntitlements:
+ "debugserver's entitlements are not a readable property list; cannot grant task_for_pid."
+ }
+ }
+ }
+
+ /// Turn debugserver's own entitlements into the set it needs to attach in the
+ /// guest: drop the `seatbelt-profiles` that would confine it, and grant
+ /// `task_for_pid-allow` so it can take another process's task port. The result
+ /// is the complete entitlement set to embed by **replacement** — merging it
+ /// back over the file's own entitlements would re-add the `seatbelt-profiles`
+ /// removed here, because a merge updates and appends keys but cannot delete
+ /// one.
+ ///
+ /// This only grants the entitlement. Whether the kernel honours it for a
+ /// system daemon is a separate matter: that needs the kernel's task-port,
+ /// debugger and port-to-map patches, which a stock `minimal` kernel lacks
+ /// (``FirmwarePatchSetCatalog/userspaceDebugging``).
+ public static func attachEntitlements(from source: Data) throws -> Data {
+ guard var plist = try PropertyListSerialization.propertyList(from: source, format: nil) as? [String: Any] else {
+ throw Error.unreadableEntitlements
+ }
+ plist.removeValue(forKey: "seatbelt-profiles")
+ plist["task_for_pid-allow"] = true
+ return try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
+ }
+}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index fa54e0be..2052209b 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -415,7 +415,7 @@ public enum FirmwarePatchSetCatalog {
selection: .allow(
minimalDeviceTreePatches
.union(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
- .union(FirmwareRestoreImagePatchSet.manifest.patches.map(\.identifier))
+ .union(FirmwareRestoreImagePatchSet.presetPatches)
.subtracting([FirmwareRestoreImagePatchSet.launchdCacheLoader]),
),
)
@@ -448,7 +448,7 @@ public enum FirmwarePatchSetCatalog {
selection: .allow(
watchOSDeviceTreePatches
.union(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
- .union(FirmwareRestoreImagePatchSet.manifest.patches.map(\.identifier))
+ .union(FirmwareRestoreImagePatchSet.presetPatches)
.subtracting([FirmwareRestoreImagePatchSet.launchdCacheLoader]),
),
)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareRestoreImagePatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareRestoreImagePatchSet.swift
index f92815eb..1df49780 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareRestoreImagePatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareRestoreImagePatchSet.swift
@@ -34,8 +34,19 @@ public enum FirmwareRestoreImagePatchSet {
public static let launchdCacheLoader = "filesystem-exp-launchd_cache_loader_unsecure_cache_gate"
public static let virtualBluetooth = "filesystem-exp-btvc_le_connection"
public static let watchAudio = "filesystem-exp-watch_audio"
+ public static let debugserver = "filesystem-exp-debugserver"
public static let digestRehash = "manifest-boot-digest_rehash"
+ /// Patches a machine asks for by name (`--allow`, or a preset that lists them);
+ /// `minimal` and `watchos` leave them off, so the plain presets stay a lifelike
+ /// stock guest.
+ public static let optInPatches: Set = [debugserver]
+ /// What `minimal` and `watchos` select from this set: everything but the
+ /// opt-in patches.
+ public static var presetPatches: Set<String> {
+ Set(manifest.patches.map(\.identifier)).subtracting(optInPatches)
+ }
+
private static func filesystem(_ identifier: String, _ title: String, _ summary: String) -> VPhonePatchDeclaration {
VPhonePatchDeclaration(
identifier: identifier,
@@ -94,6 +105,12 @@ public enum FirmwareRestoreImagePatchSet {
summary: "Installs the virtio sound HAL plugin on watchOS.",
target: .firmware(.filesystem),
),
+ VPhonePatchDeclaration(
+ identifier: debugserver,
+ title: "debugserver",
+ summary: "Re-signs the guest's debugserver with task_for_pid-allow and no sandbox profile, before the reseal, so it can attach to a process in the guest. Off by default — a lifelike guest ships no debugger, and a stock userland carries debugserver only in the Developer disk image, where this is a no-op. On its own it does not run on minimal's stock kernel and TXM: turn on Userspace debugging, which adds the kernel and TXM patches it needs.",
+ target: .firmware(.filesystem),
+ ),
VPhonePatchDeclaration(
identifier: digestRehash,
title: "Manifest digests",
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index 15d54ad1..944df9c1 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@ -231,7 +231,9 @@ struct FirmwarePatchSetCatalogTests {
iOSBase: VPhoneVersion("26.4"),
cloudOS: VPhoneVersion("26.4"),
)
- let restoreImage = Set(FirmwareRestoreImagePatchSet.manifest.patches.map(\.identifier))
+ // The opt-in patches, like the debugserver re-sign, stay off.
+ let restoreImage = FirmwareRestoreImagePatchSet.presetPatches
+ #expect(!restoreImage.contains(FirmwareRestoreImagePatchSet.debugserver))
let researchBoard = Set(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
// The unsecure-cache gate stays out: the launchd.plist minimal edits is
// signed and in the trust cache, so the stock launchd_cache_loader takes it.
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 15710bb1..6dc2cf9e 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -4079,24 +4079,16 @@ struct VPhoneCustomFirmwareInstaller {
/// entitlements are absent, so the caller does not record it live).
@discardableResult
private func patchDebugserver(system: VPhoneConfinedDirectory, work: WorkDirectory, backupSafe: Bool) throws -> Bool {
- let target = "usr/libexec/debugserver"
+ let target = CustomFirmwareDebugserver.guestPath
guard let staged = try stageOptional(target, from: system, work: work, label: "debugserver") else { return false }
guard
let source = try VPhoneSigner.entitlements(ofFileAt: staged)
- .first(where: { !$0.isEmpty }),
- var plist = try PropertyListSerialization.propertyList(
- from: source, format: nil,
- ) as? [String: Any]
+ .first(where: { !$0.isEmpty })
else {
print("[!] debugserver has no readable entitlements; patch skipped")
return false
}
- plist.removeValue(forKey: "seatbelt-profiles")
- plist["task_for_pid-allow"] = true
- let data = try PropertyListSerialization.data(
- fromPropertyList: plist,
- format: .xml, options: 0,
- )
+ let data = try CustomFirmwareDebugserver.attachEntitlements(from: source)
try backupEntitlementTarget(target, in: system, backupSafe: backupSafe)
// Replacement, not merge: `plist` is already the complete set we want,
// and merging it back over the file's own entitlements would re-add the