diff --git a/docs/18_READOOR_DEFENDER_INTEGRATION.md b/docs/18_READOOR_DEFENDER_INTEGRATION.md index 46ff73d..ee8c019 100644 --- a/docs/18_READOOR_DEFENDER_INTEGRATION.md +++ b/docs/18_READOOR_DEFENDER_INTEGRATION.md @@ -145,7 +145,7 @@ func poisonedKey(_ key: String) -> String { - `IG_UNAVAILABLE`(架构/平台不支持、数据缺失)与 `IG_CLEAR` **一律忽略**,绝不当攻击。 - 110 ObjC IMP 合法 swizzling 会误报,故**不单条定罪**,归 MEDIUM。 -- **灰度上线**:先让 §3 的 observer 只打点、**接入点二先不接**(或 `ig_poison_apply` 旁路),用线上 `reason` 分布确认「非越狱设备零 STRONG、MEDIUM 不成对」后,再开毒化。 +- **灰度上线**:先让 observer 只打点、**接入点二先不接**(或 `ig_poison_apply` 旁路),用线上 `reason` 分布确认「非越狱设备零 STRONG、MEDIUM 不成对」后,再开毒化。**可直接贴的 observer 打点骨架 + 判读标准见 [附录 A](#附录-a--灰度第一步observer-打点骨架只观察绝不处置)**。 --- @@ -163,3 +163,109 @@ func poisonedKey(_ key: String) -> String { 3. OLLVM/VMP 覆盖 `ig_poison_mark / ig_poison_mask / ig_poison_apply` 与策略分级表。 4. 毒化基线魔数运行期派生(别硬编码 `0xA5C3F10E7B2D4968`)。 5. 越狱探针真机正向验证:在越狱设备实测命中 400/401,且非越狱设备零 STRONG。 + +--- + +## 附录 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?, 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.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`。