From 60d868a351c5c02e7752aa1071aa3d5024cd4a53 Mon Sep 17 00:00:00 2001 From: shenlei Date: Fri, 13 Nov 2026 10:02:02 +0900 Subject: [PATCH] =?UTF-8?q?docs(18):=20=E9=99=84=E5=BD=95=20A=20=E2=80=94?= =?UTF-8?q?=20=E7=81=B0=E5=BA=A6=E7=AC=AC=E4=B8=80=E6=AD=A5=20observer=20?= =?UTF-8?q?=E6=89=93=E7=82=B9=E9=AA=A8=E6=9E=B6(=E5=8F=AA=E8=A7=82?= =?UTF-8?q?=E5=AF=9F=E4=B8=8D=E5=A4=84=E7=BD=AE)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 开毒化前的线上体检:实验室真机证了不误报,但线上几十万台各机型/系统, 先只打点、不毒化,用真实用户群量误报率,达标再开接入点二。 - A.1 C→Swift 桥接要点:@convention(c) 闭包不能捕获,状态经 observer_ctx (Unmanaged 指针)传入;只读 status/reason 打点,不碰 subject/evidence 字符串 (省桥接 + 合规不输出路径)。 - A.2 RDDefenderObserver.swift 骨架:按 reason 聚合 DETECTED 计数,statLine 只含 reason 枚举与计数(不含 Token/手机号/用户ID/订单号/路径)。 - A.3 接 RDSecurityGuard.evaluate:灰度期与现逻辑并行加一行 observeWithDefender, 铁律——不调 ig_poison_apply、不 exit、不改业务;triggered 只进日志。 - A.4 判读与退出条件:STRONG 非越狱出现率≈0、MEDIUM 不成对、triggered 占比可解释 三项达标 → 按 §4 开毒化。§5 加指向附录的交叉引用。 基于 readoor 现版 evaluate(event:) 与 RDOSLogManager.logStat/logInfo 实签名; 不碰 readoor 工程,落地须走其 Skill 流程 + xcodebuild。 Co-Authored-By: Claude Opus 4.8 --- docs/18_READOOR_DEFENDER_INTEGRATION.md | 108 +++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) 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`。