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

9.1 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。
  • 灰度上线:先让 §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。