# Liter8 逆向笔记：语义化固件 patch 是怎么做的

> 15,021 行 Swift / 69 文件 / 195 个测试。核心信条写在 `liter8 --help` 里：
> **"Offsets are outputs, never inputs: every patch site is rediscovered in the binary in front of it."**
> 没有一个偏移是写死的 —— 每次构建都按代码形状重新找。

---

## 1. 分层

```
Sources/Liter8Core/
├── Binary/        1,135 行   Mach-O / IM4P / IMG4 解析，MaskedInstructionPattern
├── Firmware/      2,291 行   IPSW 解包、BuildManifest、TSS 代理
├── Patching/        459 行   PatchRecord、GuardedPatchApplier、FixtureManifest
├── Profiles/      1,097 行   机型 × build × plan 的绑定表（"哪台机器哪个版本用哪套"）
└── Resolvers/     7,405 行   真正找 patch 站点的地方
    ├── iBoot/          4 个
    ├── Kernel/        14 个
    ├── TXM/            6 个
    ├── DeviceTree/     1 个
    └── Userland/       6 个
```

`Profiles/FirmwareProfile.swift` 是总开关：每个条目固定 `productVersion` / `builds` / `boards` / 支持哪些 plan。
`detect` 靠**内核里的整条 XNU 版本串**匹配，不是靠文件名或 build 号 ——
所以同一个 XNU 串的三个 board（n104ap / d421ap / d431ap）必须共用一个 profile，拆开会让 `detect` 同时返回 nil。

---

## 2. 站点是怎么找到的

三层信息，从粗到细：

### 2.1 Mach-O 布局

`MachOLayout` 给出每个 segment/section 的文件区间，只在这些区间里扫，避免把数据当代码。

### 2.2 掩码指令模式

```swift
struct MaskedInstructionPattern {
    let name: String
    let values: [UInt32]   // 参考 build 里抄下来的指令字
    let masks:  [UInt32]   // 每个字哪些位必须相等
}
```

- `values/masks` 成对：mask 为 0 的位不参与比较（寄存器号、立即数可漂移）
- `allowDataLayoutDrift`：额外把 load/store 的立即数也掩掉 —— 因为 XNU 的 C++ 对象字段在版本之间会挪位

### 2.3 数据流校验

有些站点光靠指令形状不够，resolver 会再验一层语义。例如 AMFI 的 trust-cache 查询：

> 用**输出参数在哪个寄存器**来定位，而不是靠固定 prologue 偏移。
> beta 4 的调用方把出参放在 `x3`，旧实现用 `x2` —— resolver 从函数体里解出寄存器号，再用它生成 stub。

这就是"形状"而不是"位置"的意思。

---

## 3. 写补丁：三态 + 两遍

`GuardedPatchApplier` 是整个工具的安全底线：

```
每个 byte range 只有三种合法状态：
  ① == originalBytes    → 写入 replacementBytes
  ② == replacementBytes → 记 alreadyApplied（幂等，重复跑不会二次破坏）
  ③ 其他                 → 整个 plan 中止

两遍走：
  第一遍 preflight：所有 range 全部校验通过（长度相等、区间不重叠）
  第二遍才真正写：patch #10 失败时，绝不会留下 patch #1..#9 半装状态
```

因为 CFW 是可反复重建的产物，这个设计让"跑一半崩了"不会污染工作目录。

---

## 4. tfp0：把 `task_for_pid(0)` 打开

目标：让无特权的用户态进程拿到 **kernel task port**，然后 `libkrw0-tfp0` 就能对内核任意读写。

五个站点，每个都是一条语义明确的改动：

| id | 原始 | 补丁 | 干了什么 |
|---|---|---|---|
| `kernel.tfp0.task-conversion` | `1f0009eb` (`CMP X0,X9`) | `ff031feb` (`CMP XZR,XZR`) | 让"转换成功"这条边无条件成立 |
| `kernel.tfp0.pid-zero` | `f7070034` (`CBZ W7,reject`) | `1f2003d5` (`NOP`) | pid 0 不再被拒 |
| `kernel.tfp0.kernel-map` | `41010054` (`B.NE`) | `0a000014` (`B +0x28`) | 跳过 kernel-map 的 panic |
| `kernel.tfp0.dyld-info-cave` | 56 字节 0 | `6893fed0 083145f9 …` | 在代码洞里放 slide 返回桩 |
| `kernel.tfp0.dyld-info-slide-scoped` | `88f241f9` | `51f41f14` (`B` 到 cave) | 只对 kernel_task 返回 slide |

### 为什么要 "scoped"

最初的写法是直接把共享的 `TASK_DYLD_INFO` 返回路径改成返回 `0` + `vm_kernel_slide`。
但那条路径**不检查问的是哪个 task**，于是每个进程的 dyld info 都被清零：

```
所有 task: all_image_info_addr=0x0, size=vm_kernel_slide  ← slide 泄露给任何进程
_dyld_process_info_create 对所有 pid 返回 kr=5
lldb: (No executable module.), image list 报错
Settings 在 scene-create 阶段被 watchdog 杀（~19.9 s）
  └─ 卡在 MKBGetDeviceLockState → get_aks_client_connection → aks-client-queue
```

逐条 bisect 8 次开机后确认：`task-conversion + pid-zero + kernel-map` 三条就够 tfp0 用，
slide patch 只是给 libkrw 学 slide 用。于是改成：

```asm
; cave 里
CMP  X20, kernel_task        ; 问的是内核吗
B.NE replay                  ; 不是 → 原样执行被挪走的 4 条指令
MOV  X0, #0                  ; 是 → 返回 0
MOV  X1, vm_kernel_slide     ;      和 slide
B    back
```

两个全局量也是**语义恢复**的：`vm_kernel_slide` 来自内核里那条 slide 日志字符串，
`kernel_task` 来自 task-conversion 站点本就用到的那对 `ADRP/LDR`。

---

## 5. Fixtures：把一次成功固化成回归用例

```json
{
  "target":   { "board": "n104ap", "build": "24A446",
                "component": "kernelcache.release.iphone12b", "device": "iPhone 11" },
  "sha256":   "813be26a…",           // 干净输入
  "expectedSize": 67534848,
  "expectedPatches": [
    { "id": "kernel.tfp0.task-conversion", "offset": 52127296,
      "originalBytes": "1f0009eb", "replacementBytes": "ff031feb" }
  ],
  "expectedOutputSHA256": "…"        // 打完补丁的产物
}
```

三条硬约束：

1. **输入哈希**：保证"这份 manifest 描述的是这个二进制"，不是"某个版本的近似"
2. **逐记录 originalBytes**：`verify` 时重新在二进制里找，找不到就对不上
3. **输出哈希**：连"打完长什么样"一起锁死

生成与校验用的是**同一个 resolver + 同一个 GuardedPatchApplier**，写完立刻回读验证 ——
"连自己二进制都验不了的 manifest 比没有更糟"。

27.0 与 27.0.1 的对照很能说明问题：

```
24A435  size 67534848  sha fdaf5ccc…   五个站点 0x31b6640 / 0x36bf37c / 0x31b7fa8 / 0x39fd53c / 0x32003f8
24A446  size 67534848  sha 813be26a…   同上偏移、同上原字节
```

两个 build 的内核不同（哈希不同），但 patch 站点**逐字节重合** —— 这就是为什么 27.0 的 plan 能直接吃 27.0.1。

---

## 6. 给新 build 加支持

```sh
# 1) 全量体检：哪个 plan 挂了
liter8 survey work-24B119/extracted

# 2) 单独的 plan，只打印
liter8 resolve kernel boot-tfp0 --input kernelcache.release.iphone12b

# 3) 定位新形状
liter8 inspect func   0x31b6640 kernelcache     # 这个偏移属于哪个函数
liter8 inspect xrefs  0x31b6640 kernelcache     # 谁引用它（ADRP+ADD）
liter8 inspect strings "called exception_triage" kernelcache
liter8 inspect objc-methods initWithCoder       # ObjC 实现

# 4) 改 resolver（加一个 Site / 放宽 mask / 加 allowDataLayoutDrift）
#    Sources/Liter8Core/Resolvers/Kernel/Kernel*/…swift

# 5) 固化
liter8 fixture kernel boot-tfp0 kernelcache fixtures/<build>/<board>/<name>.json \
        --device "iPhone 11" --board n104ap --build 24A446 \
        --component-name kernelcache.release.iphone12b

# 6) 回归
swift test
```

测试是**真跑二进制**的：`Tests/Liter8CoreTests/Resolvers/ReleaseFixtureTests.swift` 会去
`offsets/24A435/` 下读真 iBSS / TXM / kernelcache，把 resolver 重跑一遍，再和 fixture 对。
二进制不在（还没从 IPSW 提出）就 skip —— 所以这个仓库能公开而不带 Apple 二进制。

---

## 7. 编译与自检

```sh
swift build -c release          # 本机 32.6 秒，Swift 6.4.2 / Xcode 27.2
./.build/release/liter8 --version      # 0.2.3
./.build/release/liter8 preflight      # 宿主工具是否齐
```

依赖只有三个：`libcapstone-spm`（反汇编，用于 inspect）、`libimg4-spm`（IMG4/IM4P）、
`swift-argument-parser`（子命令）。
