Files
iOSGuard/docs/18_READOOR_DEFENDER_INTEGRATION.md
T
shenleiandClaude Opus 4.8 599e1da5ce feat(defender): 可集成静态库 + readoor 接入方案(检测→分级→数据毒化闭环)
在 iOSGuard 侧产出可集成产物与接入文档,不修改 readoor 代码。

- defender/: anti_hook/anti_frida/anti_debug/anti_jailbreak 探针 + syscall 直发、
  policy 分级层、poison 数据依赖毒化、dispatch/resolve/call_bridge 等子模块
- poison: 三副本冗余、无分支掩码;健康恒等、毒化破坏 key(替代 if-exit 处置)
- policy: STRONG/MEDIUM/WEAK 分级,守误报底线,仅 DETECTED 参与、组合命中才毒化
- anti_jailbreak: IGSyscall 直发 svc 检测越狱文件(400)/沙盒逃逸(401),绕 libc hook
- tools/build_defender_lib.sh: 一键交叉编译打包 libIGDefender.a(arm64) + umbrella 头
- docs/18_READOOR_DEFENDER_INTEGRATION.md: 精确到文件/bridging/替换点/代码片段
- docs/05-17 + evidence + tests + macho_guard/static_sdk_redirect 工具链

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-11-12 22:16:47 +09:00

166 lines
9.1 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。
- **灰度上线**:先让 §3 的 observer 只打点、**接入点二先不接**(或 `ig_poison_apply` 旁路),用线上 `reason` 分布确认「非越狱设备零 STRONG、MEDIUM 不成对」后,再开毒化。
---
## 6. 能力边界(务必对齐预期)
- **纯客户端无法根治 bypass**:Shadow/Liberty 等能把越狱检测 hook 成「干净」。本方案**不锚定「客户端准确判越狱」**,而是:① svc 直发抬高 hook 成本;② 数据污染比 exit 强一个量级;③ 检测-处置解耦 + 延迟分散后果,让「绕过一次」≠「永久绕过」。目标是把破解成本从分钟级抬到天级,不是不可破。
- **App Store 合规**:处置只有数据污染 + 静默降级,**不随机崩溃**,不触发拒审。
---
## 7. 后续硬化 TODO(接入后迭代,不阻塞首版)
1. 越狱路径字符串 `IG_ENC` 混淆(避免 `strings` 直接捞出 `/var/jb`、`Cydia` 等常量)。
2. `IGPoison` 三副本分散存储(TLS/heap,别全在 BSS 相邻)。
3. OLLVM/VMP 覆盖 `ig_poison_mark / ig_poison_mask / ig_poison_apply` 与策略分级表。
4. 毒化基线魔数运行期派生(别硬编码 `0xA5C3F10E7B2D4968`)。
5. 越狱探针真机正向验证:在越狱设备实测命中 400/401,且非越狱设备零 STRONG。