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

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

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。