Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
20.6 KB
Raw Blame
// CustomFirmwareWatchDog.swift — force watchdogd's cached "am I a VM?" byte to 1.
//
// Port of `scripts/patchers/cfw_patch_watchdogd.py` (453 lines). EXP only.
//
// Why the patch exists
// --------------------
// The EXP variant renames the kernel's `kern.hv_vmm_present` sysctl OID
// (`KernelExperimentalPatchHvVmmRename`), so every userland caller that still asks for
// that name gets ENOENT. `/usr/libexec/watchdogd` caches the answer at startup:
//
//     adrp x0, <page>
//     add  x0, x0, #<off>        ; "kern.hv_vmm_present"
//     sub  x1, x29, #4           ; &oldval
//     mov  x2, sp                ; &oldlen
//     mov  x3, #0
//     mov  x4, #0
//     bl   _sysctlbyname         ; via __auth_stubs
//     cbnz w0, <skip>            ; ENOENT -> skip the store
//     ldur w8, [x29, #-4]
//     cmp  w8, #0
//     cset w8, ne                ; w8 = (oldval != 0)
//     adrp x9, <page>
//     strb w8, [x9, #<off>]      ; the cached byte, a __DATA zero-fill global
//
// With the OID renamed the `cbnz` is taken, the store never runs, the cached
// byte keeps its BSS zero, and a downstream `cbz` on that byte falls into an
// `_os_crash` wrapper that executes `brk #1`. launchd's `_PanicOnCrash` turns
// the resulting SIGTRAP into a kernel panic, so this is a boot blocker rather
// than a cosmetic detection problem.
//
// What is changed
// ---------------
// Two instructions per site, and nothing else:
//
//     cbnz w0, <skip>   ->  nop            (never skip the store)
//     cset wN, ne       ->  mov wN, #1     (store 1, not the sysctl's answer)
//
// The cstring is deliberately NOT touched: the EXP design keeps every
// `kern.hv_vmm_present` consumer on the now-ENOENT name and opts individual
// consumers out by rewriting their logic, which is what this does. watchdogd
// then takes its clean-exit branch ("detected virtual machine environment and
// no watchdog KEXT found, exiting...") instead of the trap.
//
// How the site is anchored — no offsets, no byte patterns
// ------------------------------------------------------
// Five layers, each read off a Capstone decode or the Mach-O's own tables:
//
//   1. The `"kern.hv_vmm_present\0"` literal is found in a cstring section at a
//      NUL boundary, giving its VA.
//   2. In `__TEXT,__text`, an ADRP+ADD pair whose resolved address is that VA,
//      and whose result reaches x0 before the call — directly, or through a
//      `mov x0, xN`. That is the literal being passed as `sysctlbyname`'s
//      `name` argument rather than merely mentioned.
//   3. The following `bl`'s target is resolved through the indirect symbol
//      table to the imported function `_sysctlbyname`. This is an in-image
//      symbol lookup, which the Python does not do: it accepts any `bl`.
//   4. The instruction right after the call gates the store on the call's
//      return value (`cbnz w0`), and the value stored is `cset wN, ne` — the
//      truthiness of the sysctl's out-parameter. The condition is read from
//      Capstone's decoded condition code, not from operand text.
//   5. The `strb` stores that same wN into an ADRP-relative address inside a
//      `__DATA*` segment — a cached global, not a stack or heap field.
//
// Layers 2, 3 and 5 are additions over the Python, which stops at "some `bl`
// with a `cbnz w0` behind it". On `iPhone17,3` / iOS 27.0 (24A435) both
// implementations select exactly the same two sites; the extra layers are what
// keeps that true when the next firmware moves the code.
//
// Idempotence
// -----------
// A second run must be a no-op, not an error and not a double-apply (commit
// 8eb6c8b fixed exactly that class of bug elsewhere in this tree). The site
// matcher therefore recognises both shapes: the pristine one above and the one
// this patch leaves behind (`nop` … `mov wN, #1` … `strb wN`). A binary whose
// sites are all in the patched shape is reported as `.alreadyPatched`, nothing
// is written, and — importantly — re-attestation is skipped too, so the file
// on disk is byte-for-byte unchanged.
//
// Code signing
// ------------
// Editing bytes inside `__TEXT,__text` invalidates the SHA-256 slot hash of
// each containing 4 KiB page. On `codeSigningMonitor == 2` hardware TXM holds
// those hashes and kills the process on the first demand page-in, so every
// written offset is handed to `CustomFirmwareMachOCodeSignature` to re-hash its page.
//
// The binary is NOT re-signed with an identity. Re-signing would reset the
// code-signing identifier to the local filename, which trips launchd's
// boot-task identity check — the failure mode observed on mobile_obliterator
// before an earlier attempt was reverted. Mutating the CD does change the
// binary's cdHash; the JB kernel patch `patch_amfi_cdhash_in_trustcache`
// short-circuits AMFI's trust-cache check, and that precondition still holds.

import Foundation
import VPhonePatchKit

public enum CustomFirmwareWatchDog {
    // MARK: - Anchors

    /// Component name carried by every ``PatchRecord`` this patcher emits.
    public static let component = "watchdogd"

    /// The sysctl whose cached answer this patch overrides.
    public static let sysctlName = "kern.hv_vmm_present"

    /// The imported function the call site must resolve to. Layer 3 of the
    /// anchor: a `bl` that goes anywhere else is not this call.
    public static let sysctlFunction = "_sysctlbyname"

    /// `"kern.hv_vmm_present\0"` — the terminator is part of the match, so a
    /// longer name that merely starts with this one cannot pass.
    static let needle = Data((sysctlName + "\0").utf8)

    /// Sections a C string literal can land in. `__cstring` is where the linker
    /// puts them; the ObjC name pools could hold the same bytes, and the
    /// reference scans those too.
    static let literalSectionNames: Set<String> = [
        "__cstring", "__objc_methname", "__objc_classname",
    ]

    static let textSectionKey = "__TEXT,__text"

    /// Segment prefix a cached global must live under. `__bss` and `__common`
    /// are both `__DATA` sections; the prefix also covers `__DATA_DIRTY`.
    static let globalSegmentPrefix = "__DATA"

    /// Where the AArch64 C ABI puts `sysctlbyname`'s first argument.
    static let argumentRegister = "x0"

    // MARK: - Scan windows

    //
    // Instruction counts, not byte counts. Same values as the Python, which
    // measured them against the shipped binary.

    /// ADRP and the ADD that completes it may be separated by argument setup.
    static let pageToOffsetWindow = 8
    /// From the ADD that forms the string pointer forward to the call.
    static let argumentSetupWindow = 20
    /// From the gate forward to the instruction that produces the stored value.
    static let gateToValueWindow = 12
    /// From that instruction forward to the store.
    static let valueToStoreWindow = 8

    // MARK: - Sites

    /// One "cache the VM-presence answer" site, pristine or already patched.
    public struct Site: Sendable, Equatable {
        /// Which shape the site is in.
        public enum State: String, Sendable {
            /// The stock shape: `cbnz w0` gating a `cset wN, ne`.
            case pristine
            /// This patch's own output: `nop` and `mov wN, #1`.
            case patched
        }

        public let state: State
        /// VA of the `"kern.hv_vmm_present\0"` literal this site loads.
        public let literalVMA: UInt64
        /// VA of the ADD that completes the literal's address in x0.
        public let addVMA: UInt64
        /// VA of the `bl _sysctlbyname`.
        public let callVMA: UInt64
        /// VA of the gate — `cbnz w0` when pristine, `nop` when patched.
        public let gateVMA: UInt64
        public let gateFileOffset: Int
        /// VA of the instruction producing the cached value — `cset wN, ne`
        /// when pristine, `mov wN, #1` when patched.
        public let valueVMA: UInt64
        public let valueFileOffset: Int
        /// The `w` register carrying the cached value, e.g. `"w8"`.
        public let valueRegister: String
        /// That register's number, for re-encoding it as `mov wN, #1`.
        public let valueRegisterNumber: UInt32
        /// VA of the `strb` that writes the cached byte.
        public let storeVMA: UInt64
        /// VA of the cached byte itself — the `__DATA` global.
        public let cachedByteVMA: UInt64
    }

    // MARK: - Report

    /// What a run did, as a whole.
    public enum Outcome: String, Sendable, Equatable {
        /// Every site was already in the patched shape; nothing was written.
        case alreadyPatched
        /// `dryRun` was set: sites were located and reported only.
        case wouldPatch
        /// Bytes were written and the affected pages re-attested.
        case patched
    }

    /// The outcome of one run, and what it acted on.
    public struct Report: Sendable {
        public let outcome: Outcome
        /// Every site the matcher recognised, in address order.
        public let sites: [Site]
        /// One record per instruction actually rewritten — two per patched
        /// site. Empty for `.alreadyPatched`.
        public let records: [PatchRecord]
        /// Code-directory slots re-hashed as a result.
        public let rehashedSlots: [CustomFirmwareSlotRehash]

        /// Sites whose bytes this run changed. The parity number against the
        /// Python, whose `patch_watchdogd()` returns exactly this.
        public var sitesWritten: Int {
            records.count / 2
        }
    }

    /// Where progress goes when the caller does not say. The Python prints to
    /// stdout and `cfw_install_exp.sh` captures that, so this does too.
    public static let stdoutLog: @Sendable (String) -> Void = { print($0) }

    // MARK: - Patching

    /// Patch the watchdogd Mach-O at `url` in place.
    ///
    /// - Returns: a ``Report``. `.alreadyPatched` leaves the file untouched,
    ///   which is what makes a second install run a clean no-op.
    /// - Throws: ``PatcherError/invalidFormat(_:)`` when the file is not the
    ///   kind of Mach-O this patch understands, and
    ///   ``PatcherError/patchSiteNotFound(_:)`` when it is but holds no site in
    ///   either shape — a watchdogd that no longer caches the sysctl, which has
    ///   to stop the install rather than be silently skipped.
    @discardableResult
    public static func patch(
        at url: URL,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let report = try patch(&data, dryRun: dryRun, log: log)
        if !dryRun, report.outcome == .patched {
            try data.write(to: url)
            log?("  [+] \(url.path): wrote \(report.sitesWritten) site(s)")
        }
        return report
    }

    /// In-memory form of ``patch(at:dryRun:log:)``.
    @discardableResult
    public static func patch(
        _ data: inout Data,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let sites = try locateSites(in: data, log: log)
        let pending = sites.filter { $0.state == .pristine }

        guard !pending.isEmpty else {
            log?("  [.] all \(sites.count) matching site(s) already patched — nothing to do")
            return Report(outcome: .alreadyPatched, sites: sites, records: [], rehashedSlots: [])
        }
        log?("  [+] found \(sites.count) '\(sysctlName)' cache site(s), \(pending.count) to patch")

        let disassembler = ARM64Disassembler()
        var records: [PatchRecord] = []
        var modifiedOffsets: [Int] = []

        for site in pending {
            guard let value = ARM64Encoder.encodeMovzW(rd: site.valueRegisterNumber, imm16: 1) else {
                throw PatcherError.patchVerificationFailed(
                    "could not encode `mov \(site.valueRegister), #1`",
                )
            }
            let gate = ARM64.nop

            log?("    site @ add 0x\(hex(site.addVMA))  (bl 0x\(hex(site.callVMA)), "
                + "gate 0x\(hex(site.gateVMA)), value \(site.valueRegister) 0x\(hex(site.valueVMA)), "
                + "strb 0x\(hex(site.storeVMA)) -> cached byte 0x\(hex(site.cachedByteVMA)))")

            records.append(record(
                in: data,
                at: site.gateFileOffset,
                virtualAddress: site.gateVMA,
                patched: gate,
                id: "system-\(component)-exp-hv_vmm_cache.cbnz@0x\(hex(site.gateVMA))",
                description: "NOP the cbnz w0 that skips the cached hv_vmm_present store",
                disassembler: disassembler,
            ))
            records.append(record(
                in: data,
                at: site.valueFileOffset,
                virtualAddress: site.valueVMA,
                patched: value,
                id: "system-\(component)-exp-hv_vmm_cache.cset@0x\(hex(site.valueVMA))",
                description: "cset \(site.valueRegister) -> mov \(site.valueRegister), #1 "
                    + "(cached 'am I a VM?' byte forced to 1)",
                disassembler: disassembler,
            ))

            if !dryRun {
                data.replaceSubrange(site.gateFileOffset ..< site.gateFileOffset + 4, with: gate)
                data.replaceSubrange(site.valueFileOffset ..< site.valueFileOffset + 4, with: value)
            }
            modifiedOffsets.append(site.gateFileOffset)
            modifiedOffsets.append(site.valueFileOffset)
        }

        for record in records {
            log?("      [+] 0x\(hex(UInt64(record.fileOffset))): \(record.beforeDisasm) -> \(record.afterDisasm)")
        }

        guard !dryRun else {
            log?("  [.] dry-run — nothing written, no page re-attested")
            return Report(outcome: .wouldPatch, sites: sites, records: records, rehashedSlots: [])
        }

        for directory in CustomFirmwareMachOCodeSignature.unsupportedCodeDirectories(in: data) {
            log?("  [!] CodeDirectory @0x\(hex(UInt64(directory.offset))) uses hashType "
                + "\(directory.hashType); its slots are left stale")
        }

        let rehashed = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: modifiedOffsets)
        for slot in rehashed {
            log?("      [+] re-attest: \(slot)")
        }
        log?("  [+] re-attest updated \(rehashed.count) slot(s)")

        try verify(sites: pending, in: data)
        return Report(outcome: .patched, sites: sites, records: records, rehashedSlots: rehashed)
    }

    // MARK: - Verification

    /// Read the patched words back out and confirm they are what was written.
    static func verify(sites: [Site], in data: Data) throws {
        for site in sites {
            let gate = data.subdata(in: site.gateFileOffset ..< site.gateFileOffset + 4)
            guard gate == ARM64.nop else {
                throw PatcherError.patchVerificationFailed(
                    "gate at 0x\(hex(site.gateVMA)) reads \(gate.hex) after write",
                )
            }
            let value = data.subdata(in: site.valueFileOffset ..< site.valueFileOffset + 4)
            guard value == ARM64Encoder.encodeMovzW(rd: site.valueRegisterNumber, imm16: 1) else {
                throw PatcherError.patchVerificationFailed(
                    "value at 0x\(hex(site.valueVMA)) reads \(value.hex) after write",
                )
            }
        }
    }

    // MARK: - Records

    static func record(
        in data: Data,
        at fileOffset: Int,
        virtualAddress: UInt64,
        patched: Data,
        id: String,
        description: String,
        disassembler: ARM64Disassembler,
    ) -> PatchRecord {
        let original = data.subdata(in: fileOffset ..< fileOffset + patched.count)
        return PatchRecord(
            patchID: id,
            component: component,
            fileOffset: fileOffset,
            virtualAddress: virtualAddress,
            originalBytes: original,
            patchedBytes: patched,
            beforeDisasm: text(of: original, at: virtualAddress, disassembler),
            afterDisasm: text(of: patched, at: virtualAddress, disassembler),
            description: description,
        )
    }

    static func text(of word: Data, at address: UInt64, _ disassembler: ARM64Disassembler) -> String {
        guard let instruction = disassembler.disassembleOne(word, at: address) else { return "???" }
        return instruction.operandString.isEmpty
            ? instruction.mnemonic
            : "\(instruction.mnemonic) \(instruction.operandString)"
    }

    // MARK: - Instruction helpers

    /// Index of the first instruction at or after `from` that satisfies
    /// `predicate`, within `within` instructions. A word the disassembler could
    /// not decode ends the window: past it the stream is no longer this
    /// function's instructions.
    static func firstIndex(
        in instructions: [ARM64Instruction],
        from: Int,
        within: Int,
        where predicate: (ARM64Instruction) -> Bool,
    ) -> Int? {
        guard from >= 0 else { return nil }
        let end = min(instructions.count, from + within)
        var index = from
        while index < end {
            guard instructions[index].isDecoded else { return nil }
            if predicate(instructions[index]) {
                return index
            }
            index += 1
        }
        return nil
    }

    /// Page address an ADRP put in `register`, searching back from `before`
    /// (exclusive) no further than `notBefore`.
    static func pageAddress(
        ofRegister register: UInt32,
        before: Int,
        notBefore: Int,
        in instructions: [ARM64Instruction],
    ) -> UInt64? {
        var index = before - 1
        while index >= notBefore {
            let instruction = instructions[index]
            if instruction.mnemonic == "adrp", registerNumber(instruction, 0) == register,
               let page = immediate(instruction, 1)
            {
                return UInt64(bitPattern: page)
            }
            index -= 1
        }
        return nil
    }

    /// True for `mov wN, #1` in any encoding the disassembler aliases to it
    /// (MOVZ, and the ORR-immediate form) — the shape this patch writes.
    static func isMoveOfOne(_ instruction: ARM64Instruction) -> Bool {
        guard instruction.mnemonic == "mov",
              let register = registerName(instruction, 0), register.hasPrefix("w"),
              let value = immediate(instruction, 1)
        else { return false }
        return value == 1
    }

    /// The instruction's raw little-endian word, for the branch decoder.
    static func word(of instruction: ARM64Instruction) -> UInt32 {
        var value: UInt32 = 0
        for byte in instruction.bytes.prefix(4).reversed() {
            value = (value << 8) | UInt32(byte)
        }
        return value
    }

    static func registerName(_ instruction: ARM64Instruction, _ index: Int) -> String? {
        guard let operands = instruction.detail?.operands, index < operands.count,
              operands[index].type == .register
        else { return nil }
        return operands[index].reg.name
    }

    static func registerNumber(_ instruction: ARM64Instruction, _ index: Int) -> UInt32? {
        guard let operands = instruction.detail?.operands, index < operands.count,
              operands[index].type == .register
        else { return nil }
        return UInt32(operands[index].reg.rawValue)
    }

    static func immediate(_ instruction: ARM64Instruction, _ index: Int) -> Int64? {
        guard let operands = instruction.detail?.operands, index < operands.count,
              operands[index].type == .immediate
        else { return nil }
        return operands[index].imm
    }

    static func memoryOperand(_ instruction: ARM64Instruction) -> ARM64MemoryOperand? {
        guard let operands = instruction.detail?.operands,
              let operand = operands.first(where: { $0.type == .memory })
        else { return nil }
        return operand.mem
    }

    /// `"w8"` -> 8. `wzr` is rejected: the patch re-encodes this register as
    /// the destination of a `mov #1`, which is meaningless for the zero
    /// register and would mean the shape was misread.
    static func wRegisterNumber(_ name: String) -> UInt32? {
        guard name.hasPrefix("w"), let number = UInt32(name.dropFirst()), number <= 30 else { return nil }
        return number
    }

    // MARK: - Addresses

    static func fileOffset(of address: UInt64, in text: MachOSectionInfo) -> Int {
        Int(text.fileOffset) + Int(address &- text.address)
    }

    static func hex(_ value: UInt64) -> String {
        String(value, radix: 16, uppercase: true)
    }
}