Files
iOSGuard/docs/18_READOOR_DEFENDER_INTEGRATION.md
T
shenleiandClaude Opus 4.8 b76d7cdc21 harden(defender): docs/18 §7 抗静态分析硬化(符号隐藏/串混淆/副本分散/基线派生)
针对「纯客户端抗静态分析」的最高性价比项落地,守在 tests/test_static_hardening.py(6 条,gate 于 iphoneos SDK):

- 符号隐藏 + strip(§7.0 新增):IGVisibility.h 定 IG_INTERNAL=hidden,全库
  -fvisibility=hidden;仅四入口 ig_defender_scan/ig_poison_init/ig_poison_apply/
  ig_policy_scan_and_mark 标 IG_PUBLIC 保持导出,其余 ig_* 变 private external,
  链接后 strip -x 彻底消失——攻击者 nm 不再能按名定位 ig_poison_mark/mask 去 NOP。
- §7.1 串混淆:gen_jb_paths.py(唯一真源)生成 IGJailbreakPaths.inc /
  IGInjectSignatures.inc(XOR keystream,两表不共享 key),运行期解码进栈、用完擦除;
  decode 内 volatile key 屏障阻止 -O2 把常量折叠回 __const 明文。strings 已捞不到
  /var/jb、Cydia、substrate、gum-js-loop 等。--check 守 .inc 与清单同步。
- §7.2 副本分散:g_h0/h1/h2 置于不相邻命名段 __DATA,__ig_p0/p1/p2,加 __ig_pd 诱饵
  (mask 不读);刻意不用 TLS(会破坏跨线程毒化一致性)。
- §7.4 基线派生:删硬编码 0xA5C3F10E7B2D4968,改 ig_poison_baseline() 由拆分种子经
  volatile 屏障派生;otool -tV 已无旧魔数立即数。
- §7.3 OLLVM/VMP:仅留 build 的 IG_OBFUSCATOR hook,stock clang 无能力,需另备工具链(未完成)。
- §7.5 越狱设备正向验证仍阻塞(无设备)。

构建/快照同步:build_defender_lib.sh 加 -fvisibility=hidden + gen --check + IG_OBFUSCATOR
hook;build_poison_device.py 快照纳入 *.inc。全量 69 测试通过;poison_device.m 全模块
iphoneos 交叉编译通过(arm64)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-11-13 10:47:35 +09:00

280 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 18 · readoor 接入 iOSGuard Defender 方案
> 目标:把 iOSGuard 的「检测 → 分级 → 数据依赖毒化」闭环接到 readoor 业务工程。
> 边界:**纯客户端**,不引入服务端;分发渠道=**App Store 上架**,故处置**只用数据污染 + 功能静默降级,不随机崩溃**。
> 本文件只在 iOSGuard 侧产出「可集成产物 + 接入步骤」,**不修改 readoor 代码**。真正落地到 readoor 时须走 readoor 的 Skill 流程 + xcodebuild。
---
## 0. TL;DR —— 接入只有「两处调用」
1. **启动链 / 回前台 / 关键操作前** 调一次策略扫描:
```swift
ig_policy_scan_and_mark(bundlePath, 0, observerSink, nil)
```
命中高置信越狱/Hook 组合时,它**不 exit、不弹窗**,只在内部把毒化态置脏。
2. **epub 解密前**,对密钥字节过一遍毒化掩码:
```swift
ig_poison_apply(keyIn, keyOut, keyLen) // 健康:原样;毒化:逐字节异或掩码
```
健康设备 `keyOut == keyIn`,解密正常;毒化设备 key 被打乱,`sfc_SimpleDeCrypt` 解出乱码,书读不了——**没有可 patch 的 `if` 分支**。
其余都是工程接线(静态库 + bridging header + Header Search Paths)。
---
## 1. 产物(iOSGuard 侧已就绪)
用构建脚本一键产出可集成件:
```sh
sh tools/build_defender_lib.sh /path/to/out
```
产物结构:
```
out/
├── lib/
│ └── libIGDefender.a # arm64 iphoneos 静态库(-O2),只采集 + 毒化,无网络、无 UI、无 exit
└── include/
├── IGGuard.h # 统一公共头(umbrella)—— bridging 只 import 这一个
├── IGDefender.h # IGStatus/IGReason/IGFinding/IGFindingSink + ig_defender_scan
├── poison/IGPoison.h # ig_poison_init / ig_poison_mark / ig_poison_apply
├── policy/IGPolicy.h # ig_policy_scan_and_mark / ig_policy_sink / IGPolicyState
└── … # 其余子模块头,保持相对目录供 umbrella 引用
```
脚本已校验:单一 `-Iout/include` 即可编译 `IGGuard.h`(自洽),且导出符号包含
`ig_policy_scan_and_mark / ig_poison_apply / ig_poison_init / ig_defender_scan`。
> 产物是**纯 C**,不依赖 Foundation/UIKit,无动态加载,无第三方。App Store 合规面只有:静态库里有直发 `svc`(反 libc hook)与越狱特征文件路径常量——均为被动只读探测,不触发拒审项(无私有 API 符号、无越狱必备 entitlement)。
---
## 2. 工程接线(Xcode / readoor31 target)
> 以下是 readoor 侧要做的配置,列出以便一次到位;**本仓不替 readoor 改**。
1. **放置产物**:把 `libIGDefender.a` 与 `include/` 纳入 readoor 工程(建议 `readoor/3.0/Base/Security/IGDefender/`)。
2. **Link**:target → Build Phases → Link Binary With Libraries 加入 `libIGDefender.a`;因含 ObjC runtime 读取,Other Linker Flags 补 `-lobjc`。
3. **Header Search Paths**:加 `$(SRCROOT)/…/IGDefender/include`(非 recursive 即可,umbrella 内部按相对目录引用)。
4. **Bridging Header**:在 readoor 既有 bridging header 里加一行
```objc
#import "IGGuard.h"
```
之后 Swift 侧即可直接调用 `ig_policy_scan_and_mark` / `ig_poison_apply` 等 C 符号。
5. **构建验证**(readoor 默认命令):
```sh
xcodebuild build -workspace readoor.xcworkspace -scheme readoor31 \
-sdk iphoneos -derivedDataPath /private/tmp/readoor-derived
```
---
## 3. 接入点一:处置触发(替换 `RDSecurityGuard.forceExit()`)
**现状**:`readoor/3.0/Base/Security/RDSecurityGuard.swift` 的 `evaluate(event:)` 在 highRisk 时走 `forceExit() → exit(0)`。
`exit/_exit/abort` 都是**单点、显式、可被 hook** 的控制流,Shadow/Liberty 一个断点就废掉。
**改法**:把 `exit(0)` 这条路换成策略扫描 + 毒化(**不 exit**)。在原来调用 `evaluate` 的事件点
(launch / foreground / beforeLogin / beforePayment / beforeVipPurchase / beforeActivation)改为:
```swift
// RDSecurityGuard 内部,原 forceExit() 调用点替换为:
let bundlePath = Bundle.main.bundlePath
_ = bundlePath.withCString { cBundle in
ig_policy_scan_and_mark(cBundle, 0) { finding, _ -> Int32 in
// observer:仅打点,不含敏感信息(不打 Token/手机号/用户ID/订单号)
// 可转发到 RDOSLogManager 记 reason/status 计数,用于灰度观测误报面
return 0
} as IGFindingSink, nil)
}
// 返回后不做任何可见动作:命中与否对 UI 完全透明。
// 真正的「拒服务」在接入点二随解密自然发生。
```
要点:
- **一次扫描即判**:`ig_policy_scan_and_mark` 内部 reset → `ig_defender_scan` → 按档位组合判定 → 命中则 `ig_poison_mark`。
- **检测与处置解耦**:这里**只置脏**,书打不开发生在接入点二,时空分离,攻击者难把「检测」和「后果」对上。
- **observer 打点合规**:遵守 readoor AGENTS — 日志不输出 Token / 手机号 / 用户 ID / 订单号 / 支付结果 / 完整请求参数,只记 `reason` 枚举与计数。
- **保留 Swift 既有探针**:`RDJailbreakDetector`(public API:canOpenURL / FileManager)可留作**观察打点**,但判定权交给 C 侧 svc 直发(绕过 bypass 对 libc/公开 API 的 hook)。即 Swift 层量化误报面,C 层定罪。
---
## 4. 接入点二:数据依赖毒化(epub 解密)
**现状**:`readoor/3.0/Features/ReadView/Epub/RDEncryptedEpubResourceProvider.swift`
`decrypt(path:key:)` 调 `StsSimpleCrypt.sfc_SimpleDeCrypt(path, pass: key)`;
`bookKey = doubled("startiasoft" + bookIdentifier)`,imageKey 走 MD5。
**改法**:在把 key 交给 `sfc_SimpleDeCrypt` **之前**,对 key 字节过 `ig_poison_apply`:
```swift
// decrypt(path:key:) 内,调用 sfc_SimpleDeCrypt 之前:
func poisonedKey(_ key: String) -> String {
var inBuf = Array(key.utf8)
var outBuf = [UInt8](repeating: 0, count: inBuf.count)
ig_poison_apply(&inBuf, &outBuf, inBuf.count)
return String(decoding: outBuf, as: UTF8.self) // 若 key 是二进制,改用 Data 承载,勿走 UTF8
}
// let realKey = poisonedKey(key); StsSimpleCrypt.sfc_SimpleDeCrypt(path, pass: realKey)
```
语义:
- **健康设备**:`ig_poison_mask() == 0` → `ig_poison_apply` 是**恒等变换**,`outBuf == inBuf`,解密与现状完全一致,零影响。
- **毒化设备**:mask ≠ 0 → key 每字节被 `(mask >> ((i&7)*8)) & 0xFF` 异或打乱 → `sfc_SimpleDeCrypt` 解出乱码 → 书页/图片无法渲染。
- **无分支可 patch**:这里没有 `if(越狱)`,毒化靠数据流(mask)天然传播;要绕得逆向整条密钥推导并还原 mask=0 的恒等性,成本从「分钟级断点」抬到「天级逆向」。
> 若 key 实际是二进制(非可打印字符串),**不要**经 `String(UTF8)` 往返(会丢字节)。改成对承载 key 的 `Data`/`[UInt8]` 原地 `ig_poison_apply`,再按 `sfc_SimpleDeCrypt` 需要的类型传入。
---
## 5. 误报底线(上线前提)
毒化**隐蔽且不可逆**:误伤非越狱正常用户=「书打不开」的差评 + 难排查退款。故策略层(`IGPolicy.c`)已内建底线,接入时**不要放宽**:
| 档位 | reason | 触发规则 |
|---|---|---|
| **STRONG**(单条即判) | 400 越狱文件 / 401 沙盒逃逸 / 102 GOT 重绑 / 101 inline hook / 200 注入镜像 / 300 调试器 | `strong_count ≥ 1` |
| **MEDIUM**(需组合) | 100 符号提供方 / 110 ObjC IMP / 203 frida 线程 | `≥2 个不同 MEDIUM`,或与任一 STRONG 同现 |
| **WEAK**(永不毒化) | 201 Bundle 外镜像 / 204 frida 端口 | 仅观察打点 |
- `IG_UNAVAILABLE`(架构/平台不支持、数据缺失)与 `IG_CLEAR` **一律忽略**,绝不当攻击。
- 110 ObjC IMP 合法 swizzling 会误报,故**不单条定罪**,归 MEDIUM。
- **灰度上线**:先让 observer 只打点、**接入点二先不接**(或 `ig_poison_apply` 旁路),用线上 `reason` 分布确认「非越狱设备零 STRONG、MEDIUM 不成对」后,再开毒化。**可直接贴的 observer 打点骨架 + 判读标准见 [附录 A](#附录-a--灰度第一步observer-打点骨架只观察绝不处置)**。
---
## 6. 能力边界(务必对齐预期)
- **纯客户端无法根治 bypass**:Shadow/Liberty 等能把越狱检测 hook 成「干净」。本方案**不锚定「客户端准确判越狱」**,而是:① svc 直发抬高 hook 成本;② 数据污染比 exit 强一个量级;③ 检测-处置解耦 + 延迟分散后果,让「绕过一次」≠「永久绕过」。目标是把破解成本从分钟级抬到天级,不是不可破。
- **App Store 合规**:处置只有数据污染 + 静默降级,**不随机崩溃**,不触发拒审。
---
## 7. 后续硬化 TODO(接入后迭代,不阻塞首版)
> 状态截至 2026-11-13。回归守在 `tests/test_static_hardening.py`(6 条,gate 于 darwin+iphoneos SDK),防以下几条被后续改动悄悄打回。
**0. ✅ 符号隐藏 + strip(本轮新增,针对「抗静态分析」最高性价比项)。**
`defender/include/IGVisibility.h` 定义 `IG_INTERNAL=hidden`;全库 `-fvisibility=hidden`(见 `tools/build_defender_lib.sh`)。只有 readoor 实际调用的四入口标 `IG_PUBLIC`(`ig_defender_scan / ig_poison_init / ig_poison_apply / ig_policy_scan_and_mark`)保持导出,其余 `ig_*` 在 `.a` 里是 private external,链接进可执行文件后 `strip -x` 即彻底消失——攻击者 `nm` 不再能按名定位 `ig_poison_mark/mask` 去 NOP 调用点。
**readoor 侧务必保留 Release 的 `STRIP_INSTALLED_PRODUCT=YES`**,否则内部符号不消失;连那四个 public 入口也可全量 strip(无外部模块 import 它们,仅编译期静态链接用到)。
1. ✅ 越狱路径字符串 `IG_ENC` 混淆。`tools/gen_jb_paths.py`(唯一真源)生成 `IGJailbreakPaths.inc` / `IGInjectSignatures.inc`(XOR keystream,两表不共享 key);运行期解码进栈、用完 `memset` 擦除。`ig_jb_decode/ig_inj_decode` 内 `volatile` key 屏障,阻止 `-O2` 把「常量 enc+常量 key」折叠回 `__const` 明文。`strings` 已捞不到 `/var/jb`、`Cydia`、`substrate`、`gum-js-loop` 等。CI 用 `gen_jb_paths.py --check` 守 .inc 与清单同步。
2. ✅ `IGPoison` 三副本分散存储。`g_h0/g_h1/g_h2` 置于不相邻命名段 `__DATA,__ig_p0/__ig_p1/__ig_p2`,另加 `__ig_pd` 诱饵副本(init/mark 维护但 mask 不读)。**刻意不用 TLS**——会破坏跨线程毒化一致性。
3. ⚠️ OLLVM/VMP 覆盖 `ig_poison_mark / mask / apply` 与策略分级表。**仅留 hook 未落地**:`build_defender_lib.sh` 的 `IG_OBFUSCATOR` 环境变量在指向 OLLVM-clang 时对 `IGPoison.c`/`IGPolicy.c` 启 `-mllvm -fla -bcf -sub`;stock Xcode clang 无此能力,需另备 obfuscator-llvm/商业 VMP 工具链才算真正完成。
4. ✅ 毒化基线魔数运行期派生。删除硬编码 `0xA5C3F10E7B2D4968`,改 `ig_poison_baseline()` 由拆分种子经 `volatile` 屏障派生(阻止常量折叠回单一魔数);值本身不影响行为,只需进程内自洽。`otool -tV` 已无旧魔数立即数。
5. ⛔ 越狱探针真机正向验证:越狱设备实测命中 400/401,且非越狱设备零 STRONG。**仍阻塞**(无越狱设备)。D8 `svc_access_live` 已在非越狱 iPhone 证了 svc 直发探针活性,残留缺口=真越狱文件 400 + 沙盒逃逸 401 的正向命中。
> **尚未做、留到 readoor 接入时的「断边」深化**:把 `ig_poison_apply` 内联进 epub 解密函数(删掉 `bl ig_poison_apply` 这条调用边),以及调用点改间接跳转(`blr` + 运行期解析目标)——符号隐藏只去掉「按名定位」,这两项才去掉静态调用图里的边本身。
---
## 附录 A · 灰度第一步:observer 打点骨架(只观察,绝不处置)
> **用途**:开接入点二毒化**之前**的线上体检。实验室 2 台真机证了「不误报」,但线上是几十万台各机型/各 iOS 版本的真实设备——先只打点、不毒化,用真实用户群把误报率量出来,确认「非越狱用户里 STRONG 出现率≈0、MEDIUM 不成对」后,再按 §4 开毒化。
>
> **本阶段铁律**:此处只记日志,**不调用 `ig_poison_apply`、不 `exit`、不改任何业务行为**。上线风险≈0(纯增日志)。
>
> 下面是可直接贴的 Swift 骨架;真正落地改 readoor 须走其 Skill 流程 + xcodebuild,贴入时对一下 `RDSecurityGuard` / `RDOSLogManager` 的实际签名(本骨架基于现版本 `evaluate(event:)` 与 `RDOSLogManager.logStat/logInfo`)。
### A.1 C→Swift observer 桥接要点
`ig_policy_scan_and_mark(bundle, port, observer, observer_ctx)` 的 `observer` 是 C 函数指针
`int (*)(const IGFinding*, void*)`。Swift 侧用 **`@convention(c)` 闭包**,它**不能捕获上下文**,故计数器等状态必须经 `observer_ctx`(`void*`)传入——用 `Unmanaged` 把一个 Swift 聚合器对象的指针传进去,在回调里取回。
**只读 `status` 与 `reason`(都是 Int)做打点;不碰 `subject`/`evidence` 字符串**——既省去 C 定长 char 数组的桥接麻烦,也天然满足 readoor 日志合规(不输出路径等可能敏感的细节)。
### A.2 骨架代码(新建 `RDDefenderObserver.swift`,放 `3.0/Base/Security/`)
```swift
import Foundation
/// 灰度打点聚合器:单次扫描内累计各 reason 的 DETECTED 计数。只观察、不处置。
/// 经 observer_ctx 传给 C 回调;回调里只读 finding.status / finding.reason。
final class RDDefenderObserver {
// reason(Int) -> 命中次数;只记 IG_DETECTED。
private(set) var detectedByReason: [Int32: Int] = [:]
private(set) var detectedTotal = 0
/// 非捕获的 C 回调:ctx 还原为 self,累计计数。返回 0=继续扫描。
static let sink: @convention(c) (UnsafePointer<IGFinding>?, UnsafeMutableRawPointer?) -> Int32 = { f, ctx in
guard let f = f, let ctx = ctx else { return 0 }
// IG_DETECTED == 1(见 IGDefender.h 的 IGStatus);UNAVAILABLE/CLEAR 不计。
if f.pointee.status.rawValue == IG_DETECTED.rawValue {
let obs = Unmanaged<RDDefenderObserver>.fromOpaque(ctx).takeUnretainedValue()
let reason = f.pointee.reason
obs.detectedByReason[reason, default: 0] += 1
obs.detectedTotal += 1
}
return 0
}
/// 单行埋点:只含 reason 枚举与计数,**不含 Token/手机号/用户ID/订单号/路径**。
func statLine(event: String, triggered: Bool) -> String {
// 形如:reasons=400:1,110:2(按 reason 升序,稳定可聚合)
let reasons = detectedByReason.sorted { $0.key < $1.key }
.map { "\($0.key):\($0.value)" }.joined(separator: ",")
return "[DefenderObserve] event=\(event) triggered=\(triggered) "
+ "detected=\(detectedTotal) reasons=[\(reasons)]"
}
}
```
### A.3 接到 `RDSecurityGuard`(灰度阶段:与现逻辑并行,不替换 forceExit)
```swift
// RDSecurityGuard.evaluate(event:) 内,与现有 Swift 检测并行加一段观察扫描。
// 灰度阶段只打点;forceExit() 暂保留原样(或已按业务决定停用 exit——见下方注释)。
private func observeWithDefender(event: RDSecurityEvent) {
let bundlePath = Bundle.main.bundlePath
let observer = RDDefenderObserver()
let ctx = Unmanaged.passUnretained(observer).toOpaque()
// 返回值 triggered:若现在就开毒化,这里会命中;灰度阶段仅记录,不据此处置。
let triggered = bundlePath.withCString { cBundle in
ig_policy_scan_and_mark(cBundle, 0, RDDefenderObserver.sink, ctx)
}
// 仅埋点。logStat 走统计通道;合规:不输出任何敏感字段。
RDOSLogManager.logStat(observer.statLine(event: eventName(event), triggered: triggered != 0))
// ⚠️ 灰度第一步到此为止:
// - 不调用 ig_poison_apply(接入点二,§4)——那是数据达标后才开。
// - 不因 triggered 做任何 UI/exit/降级。
// triggered 只进日志,用于线上量化误报面。
}
// 复用现有 eventName 文案(启动/回前台/…);若 logRisk 里的 switch 已有,可抽成函数共用。
private func eventName(_ event: RDSecurityEvent) -> String {
switch event {
case .launch: return "launch"
case .foreground: return "foreground"
case .beforeLogin: return "beforeLogin"
case .beforePayment: return "beforePayment"
case .beforeVipPurchase: return "beforeVipPurchase"
case .beforeActivation: return "beforeActivation"
}
}
```
调用点:在 `evaluate(event:)` 里、现有 `logRisk(...)` 之后加 `observeWithDefender(event: event)` 一行即可(launch/foreground 等所有事件都会带出一条打点)。
### A.4 灰度判读与退出条件
收一段线上数据后,看 `[DefenderObserve]` 这条 stat:
| 指标 | 期望(可开毒化) | 不达标说明 |
| --- | --- | --- |
| STRONG reason(400/401/101/102/200/300)在**非越狱机型**出现率 | ≈ 0 | 若某机型/系统版本批量出现 → 有误报源,排查该 reason 再说 |
| MEDIUM reason(100/110/203)成对(≥2 不同)出现率 | 极低 | 合法 swizzling 多发 → 调 §5 分级或把该 reason 降级 |
| `triggered=true` 占比 | 贴近真实越狱盘踞率,且集中在可解释来源 | 明显偏高 → 先别开毒化 |
三项达标 → 按 §4 在 `RDEncryptedEpubResourceProvider.decrypt` 接 `ig_poison_apply`,并把 `observeWithDefender` 里「不据 triggered 处置」的注释解除、改为真正消费(或让毒化在解密侧随 mask 自然生效,二选一,推荐后者=解耦)。
> **为什么并行而非立刻替换 `forceExit`**:灰度期保留现有 Swift 检测路径(哪怕已停用 exit),让新旧两套检测的 reason 分布能在同一批设备上对照,确认 C 侧探针不是凭空多报。待毒化开启、稳定后,再按 §3 用策略扫描收口、下线 `forceExit`。