live-hub-py/docs/Hook脚本运行与捕获约定.md

Hook 脚本运行与捕获约定（强制遵守）

适用范围：本仓库所有 scripts/hook_*.py / probe_*.py / scan_*.py 的创建、修改与运行。 原则：脚本挂上 hooks 后，用后台任务运行；数据实时写日志；目标数据一命中，立刻主动停止任务。绝不用 bash 前台 sleep 等超时结束再看结果。

1. 运行方式（必须）

• 启动：一律 bash 工具的 run_in_background: true，例如：

  cd /Users/yml/codes/Reverse-Engineering-Agent-Universal-v3.0 && \
  .venv/bin/python -u scripts/hook_xxx.py > /tmp/hook_xxx.log 2>&1 &
  

  脚本内部必须 print(..., flush=True)（或 -u），保证日志实时落盘。
• 观察：用 bash 前台 tail -f /tmp/hook_xxx.log（或 grep 关键字）实时查看日志，不要 sleep 120 后一次性读。
• 停止：一旦日志中出现目标数据（[hit] / [wire] / [FOUND] 等命中标记），立即：

  pkill -f hook_xxx.py   # 或 job_kill 对应后台任务
  

  保存 evidence/*.json 后即可分析。不需要等脚本自身的超时窗口走完。
• 配套交互：需要用户在手机上操作（退出登录→重新登录）时，脚本打印提示后立即进入等待，hook 数据实时刷日志；用户操作完成后我们随时 tail 查看，命中即杀。

2. 脚本自身结构（必须）

• 主循环用 time.sleep(5) 轮询，但每条捕获都立即 send()，on_message 里 print(flush=True)。
• 超时窗口（如 150s）只是兜底，不是等待方式：数据命中即可提前退出（pkill/job_kill）。
• 捕获结果写 evidence/ 下 JSON：script.on('message') 全程收集事件，退出前统一落盘；但如果提前被杀，落盘逻辑可能不执行 —— 因此命中即打印+写入：on_message 里命中类型直接 OUT 文件追加写入，保证被杀前数据已持久化。
• 统一模块：RE = Path("/Users/yml/codes/Reverse-Engineering-Agent-Universal-v3.0")（frida 环境 + bypass 脚本在此）。
• 设备连接：frida.get_device_manager().add_remote_device("127.0.0.1:31877")（设备上 frida-server 14.2.18 监听 0.0.0.0:31877，macOS 侧 adb forward tcp:31877 tcp:31877）。
• spawn 流程（稳定版，参考 hook_genbiz.py）：
  1. device.spawn(["com.duowan.kiwi"])
  2. 加载 bypass_msaoaid_maps_art_callsite.js
  3. 加载 mask_frida_maps_only.js
  4. device.resume(pid)，sleep 11
  5. 加载 patch_guard_block_termination.js
  6. 再 create_script 主 hook JS
• 注意：不要直接 attach 运行中的 kiwi 进程（App 有 msaoaid 反调试，attach 会被杀/闪退）；必须 spawn + 三件套 bypass。
• 注意：脚本里的 JS 若在 resume 前 load()，目标 so 尚未加载，hook 会落空 —— 模块相关枚举/attach 用 setInterval 轮询或放在 resume+11s 之后。

3. 常见坑

• frida-ps -U 正常但 remote spawn 报 TransportError：检查 adb forward --list，必须 tcp:31877 -> tcp:31877。
• 设备上会同时存在多个 kiwi 进程（主进程 + cloudpatch/logcat 子进程）；hook 必须挂在我们 spawn 的主进程 pid 上，用户手动操作的若为旧实例，hook 会空转（日志 0 命中）。操作前先 am force-stop com.duowan.kiwi 清掉旧实例。
• datadiv 导出名是 .datadiv_decode...（带点前缀），匹配用 name.indexOf('datadiv') >= 0，不要用 === 0。
• libhydeviceid.so 业务符号全部混淆/内部化（只导出 hy_* syscall 包装 + JNI_OnLoad），dfpReport 加密体生成函数不在导出表；静态搜不到魔数 571882cf664bb39401ee 属正常（运行时拼装）。