docs(18): 附录 A — 灰度第一步 observer 打点骨架(只观察不处置)
开毒化前的线上体检:实验室真机证了不误报,但线上几十万台各机型/系统, 先只打点、不毒化,用真实用户群量误报率,达标再开接入点二。 - 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 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 4.8
parent
4fb76ae528
commit
60d868a351
@@ -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<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)
|
||||
|
||||
```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`。
|
||||
|
||||
Reference in New Issue
Block a user