Files
iOSGuard/docs/18_READOOR_DEFENDER_INTEGRATION.md
T
shenleiandClaude Opus 4.8 2e43ff6da2 harden(poison): 断边原语 IGPoisonInline.h——毒化内联进解密 TU,删掉可 NOP 的调用边
docs/18 §7「断边」:符号隐藏只抹掉节点名字,调用图的边 bl ig_poison_apply/mask 仍在、
可被攻击者 NOP 或把被调函数 stub 成恒等。本提交提供能内联进接入方解密 TU 的 always_inline 核心。

- defender/poison/IGPoisonInline.h(单一真源):把「读健康值→推掩码→扰动密钥」做成
  always_inline。接入方在解密 TU #include 后调用 ig_poison_mix_key_inline(key,n),编译器
  把这段揉进解密函数自身——反汇编里没有 bl ig_poison_* 调用边可 NOP,毒化藏进 key schedule
  (比后置改输出更难摘)。推荐形态:扰动 key 派生(健康→key 不变→正常解密;毒化→乱码)。
- 跨 TU 唯一共享的是数据 ig_pstate[](中性名、hidden、strip 后无符号名),是 data 重定位
  非调用边。
- IGPoison.c 重构为复用该头的 core(baseline/lane_k/spread/mask/apply 只此一处定义),
  库 out-of-line 入口与接入方内联路径语义等价、永不漂移;g_state 改名 ig_pstate 并提升为
  hidden 全局供跨 TU 内联直读。IGVisibility.h 加 IG_ALWAYS_INLINE。

验证(tests/test_poison_inline.py,+2):
- test_inline_equals_outofline(host/macosx):内联 mask/apply == 库入口,mix_key 健康恒等、
  毒化扰动,逐例 0 fail。
- test_no_call_edge_after_inline(iphoneos,gate SDK):模拟解密 TU rd_derive_key 调用
  mix_key,-O2 反汇编断言零 bl、仅对 ig_pstate 的 data 引用,无 ig_poison_mask/apply 符号引用。

全量 72 测试通过;poison_device.m 全模块 iphoneos 交叉编译 arm64 通过。docs/18 §7 补 7.6 接入形态。

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

20 KiB
Raw Blame History

18 · readoor 接入 iOSGuard Defender 方案

目标:把 iOSGuard 的「检测 → 分级 → 数据依赖毒化」闭环接到 readoor 业务工程。 边界:纯客户端,不引入服务端;分发渠道=App Store 上架,故处置只用数据污染 + 功能静默降级,不随机崩溃。 本文件只在 iOSGuard 侧产出「可集成产物 + 接入步骤」,不修改 readoor 代码。真正落地到 readoor 时须走 readoor 的 Skill 流程 + xcodebuild。


0. TL;DR —— 接入只有「两处调用」

  1. 启动链 / 回前台 / 关键操作前 调一次策略扫描:

    ig_policy_scan_and_mark(bundlePath, 0, observerSink, nil)
    

    命中高置信越狱/Hook 组合时,它不 exit、不弹窗,只在内部把毒化态置脏。

  2. epub 解密前,对密钥字节过一遍毒化掩码:

    ig_poison_apply(keyIn, keyOut, keyLen)   // 健康:原样;毒化:逐字节异或掩码
    

    健康设备 keyOut == keyIn,解密正常;毒化设备 key 被打乱,sfc_SimpleDeCrypt 解出乱码,书读不了——没有可 patch 的 if 分支。

其余都是工程接线(静态库 + bridging header + Header Search Paths)。


1. 产物(iOSGuard 侧已就绪)

用构建脚本一键产出可集成件:

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 里加一行
    #import "IGGuard.h"
    
    之后 Swift 侧即可直接调用 ig_policy_scan_and_mark / ig_poison_apply 等 C 符号。
  5. 构建验证(readoor 默认命令):
    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)改为:

// 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:

// 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。

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 调用点。

对抗自验结论(2026-11-13,对链接+strip 的宿主实测 nm/otool -l/-tV/strings):

  • 内部 ig_*、旧魔数、越狱/注入明文串 strip -x 后全部消失 ✓。
  • 但四个 public 入口名 _ig_poison_init/apply 等 strip -x 抹不掉(global external),而名字本身就写着 "poison",等于告诉攻击者毒化入口在哪。完整 strip(style=all,非 -x)实测连这四个名也抹掉 ✓。故 readoor Release 必须用完整 strip(STRIP_INSTALLED_PRODUCT=YES 且 STRIP_STYLE=all,Xcode app target 默认即 all;切勿配成 -x/non-global)。更稳的做法:接入层给这四个入口包一层中性名(如 rd_blob_init/transform),别让 "poison" 字样进最终符号表。
  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 分散存储。对抗自验揪出并修掉了上一版的反效果设计:原用自定义命名段 __DATA,__ig_p0/p1/p2/pd——命名段会原样留在 Mach-O load command 里、strip 也抹不掉,otool -l | grep __ig_p 一把定位毒化副本,比匿名 BSS 更糟。现改为:三路真副本 + 诱饵散在一个匿名数组 g_state[12] 的非相邻下标(IG_LANE={2,7,11}、IG_DECOY=5,其余为陪衬槽),全进匿名 __bss/__data;每槽存 baseline ^ lane_k(i) 使各槽值互不相同,消除「数组里几个相同的字=一组健康值」这种可一眼框定的 tell;mask 只读三真副本。回归守在 test_no_telegraphing_sections。刻意不用 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 的正向命中。

6. ✅ 断边原语(C 侧已就绪,留 readoor 接入时挂点)。 符号隐藏只去掉「按名定位」,调用图的边(bl ig_poison_apply/mask)仍在、可被 NOP。本轮提供 defender/poison/IGPoisonInline.h:把「读健康值→推掩码→扰动密钥」做成 always_inline 核心,接入方在解密 TU 内联后反汇编不留 bl ig_poison_* 调用边(已用 tests/test_poison_inline.py 的 test_no_call_edge_after_inline 对 arm64 -O2 产物断言:rd_derive_key 内零 bl,对 ig_pstate 仅 data 引用)。库内 IGPoison.c 的 out-of-line 入口复用同一真源,内联路径与库路径语义等价(test_inline_equals_outofline 逐例校验),不会漂移。

7.6 断边接入形态(readoor 解密 TU)

推荐把毒化揉进 key 派生(落在 key schedule,比后置改输出更难摘),而不是改解密输出:

#include "poison/IGPoisonInline.h"   // dist/include/poison/IGPoisonInline.h

// readoor 取得明文 epub 解密 key 后、喂给解密器之前:
ig_poison_mix_key_inline(key, key_len);   // 健康→key 不变→正常解密;毒化→key 被扰动→乱码
// 随后照常 AES/chacha 解密(key, …)

编译后 ig_poison_mix_key_inline 整段内联进 readoor 的解密函数:没有可 NOP 的调用边,基线派生+三副本读取+异或全部化进解密函数自身的指令流,与真实 key schedule 混在一起。唯一跨 TU 符号是数据 ig_pstate(中性名、hidden、strip 后无名),非调用边。

仍未做:调用点级别的间接跳转(blr + 运行期解析目标)——内联已消除热路径的调用边,间接跳转是针对「仍保留 out-of-line 入口」场景的额外一层,价值低于内联,按需再做。


附录 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/)

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)

// 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。