Skip to content
BranchesTags

Repository files navigation

中文 | English

QQ交流群:1076516767

ReconBridge —— 通用逆向分析 KernelSU 模块

在 Android（KernelSU root）设备上运行的通用逆向能力后端。手机侧只做原子能力（拉包 / 读文件 / 列 so / 注入 hook），所有智能（定位函数、生成 hook、分析结果）都在 PC 侧（Claude Code + MCP）完成。

📌 给 AI agent / 新会话的一页纸速查：AGENTS_QUICKSTART.md —— 全部 MCP 工具签名、M5 用法、典型工作流、高频坑，读一篇即可上手。

进度：M1 / M2 / M3 / M4 / M5 均已完成并真机验证（Xiaomi SM8750 / Android 16 / KernelSU + ZygiskNext + LSPosed）。

⚠️ 免责声明 / Disclaimer

本项目仅供已获授权的安全研究、CTF、逆向学习与防御性研究使用。使用者须对自己所分析的设备与应用拥有合法授权（自有设备、明确授权的渗透测试、公开的教学样本等）。

禁止将本项目用于未经授权的破解、绕过版权/许可保护、窃取数据、攻击第三方系统或任何违反当地法律的行为。作者不对任何滥用或由此产生的后果负责。继续使用即表示你已理解并接受以上条款。

For authorized security research and educational use only. You are responsible for having proper authorization for any device/app you analyze.

快速开始

PC 端（一键装 MCP 工具）

支持两种 AI 客户端：Claude Code（写 ~/.claude.json）与 ChatGPT Codex（写 ~/.codex/config.toml）。默认 both＝自动探测：只注册进「已安装」的客户端（Claude 看 ~/.claude.json/~/.claude/，Codex 看 ~/.codex/），没装的那个自动跳过、不建目录；两个都没检测到就只装工具本体、不写任何配置（等你装好客户端再重跑注册，或用 --target 强制写入）。另需 adb（Android platform-tools，连真机用）。

推荐：一行在线安装（Windows，无需 clone 仓库、无需 Python）

irm https://github.com/lm060719/reconbridge/releases/latest/download/install.ps1 | iex

自动下载打包好的 MCP exe、解压到 %LOCALAPPDATA%\ReconBridge\、注册进客户端用户级配置，并铺一个 reconbridge skill（逆向类任务时新会话自动加载工作流）：

  • Claude Code → ~/.claude.json 的 mcpServers.reconbridge + skill 到 ~/.claude/skills/
  • ChatGPT Codex → ~/.codex/config.toml 的 [mcp_servers.reconbridge] + skill 到 ~/.codex/skills/

装完重启对应客户端即用。

exe 内含 MCP server 与核心依赖（含 androguard）；jadx / Ghidra 仍为可选反编译工具，解压到 %LOCALAPPDATA%\ReconBridge\tools\ 即被自动探测（toolchain_status 查看）。 强制只装一个（跳过探测）：先设 $env:RB_TARGET="codex"（或 "claude"）再执行——此时即使目录不存在也会创建。wifi 传输：先设 $env:RB_TRANSPORT="wifi"。

更新：重跑上面那条安装命令即可——它会原地覆盖 exe 并重新注册，保留 work\（拉包/dump 数据）与 tools\。

卸载：

irm https://github.com/lm060719/reconbridge/releases/latest/download/uninstall.ps1 | iex

从两个客户端注销 reconbridge 并删除安装目录（默认保留 work\/tools\ 数据；连数据一起删设 $env:RB_PURGE="1"；只卸某一个设 $env:RB_TARGET="codex"）。等价地，exe 也能自注销：reconbridge-mcp.exe --unregister [--target codex]。

本地控制台（可选，图形化选连接方式 / 看状态）

reconbridge-mcp --serve            # 一键安装会把它加进 PATH——装完「新开一个终端」即可用；浏览器自动打开 127.0.0.1:9000
# 若提示找不到命令（PATH 未生效或未加），用全路径：
#   %LOCALAPPDATA%\ReconBridge\reconbridge-mcp\reconbridge-mcp.exe --serve
# 源码装法：python -m reconbridge_mcp --serve

网页里选 adb / wifi、一键连接、看 daemon 状态与只读监控（活动 hook / 近期事件流 / 落盘 dumps），省去命令行设环境变量、手抄 token。仅绑 127.0.0.1（本机）。--port N 改端口、--no-open 不自动开浏览器。

adb 还是 wifi？监听地址的坑

  • adb（USB，默认）：自动读 token、建 USB 隧道，免配置、最安全（daemon 只绑本机回环）。代价：连接时会把设备端监听地址钉成 127.0.0.1（配合隧道），且要给 adb shell root。
  • wifi（局域网直连）：需要设备端 daemon 绑到局域网 IP。在**手机 WebUI「网络设置」→「监听地址」**填 auto（自动绑 wlan0 局域网 IP）保存，或设备上 rbctl setbind auto；然后用 http://<手机IP>:<端口> + token 连（IP / 端口 / token 都在手机 WebUI 显示）。
  • ⚠️ 用过 adb 模式后想切 wifi：bind 已被钉成 127.0.0.1，电脑连不上——把「监听地址」改回 auto 即可。想固定走 wifi，就别再用 adb 模式（每次会重新钉回 127.0.0.1）。

从源码运行（开发者 / Linux / macOS，需 Python 3.10+）

# Windows
git clone https://github.com/lm060719/reconbridge.git
cd reconbridge
./install.ps1              # 建 venv → 装依赖 → 注册 reconbridge + 铺 skill（默认 Claude + Codex）
./install.ps1 -Target codex   # 只装 Codex（另可 -Transport wifi）
# Linux / macOS
git clone https://github.com/lm060719/reconbridge.git
cd reconbridge
./install.sh                  # 默认 both；只装 Codex：./install.sh adb codex

装完重启对应客户端：Claude Code 里 claude mcp list / /mcp 能看到 reconbridge（25 个工具），Codex 的 ~/.codex/config.toml 里有 [mcp_servers.reconbridge]；两端都会随装一个 reconbridge skill（~/.claude/skills/ 或 ~/.codex/skills/，逆向类任务时新会话自动加载工作流与踩坑清单）。

脚本直接写 ~/.claude.json / ~/.codex/config.toml（用户级作用域），比客户端自带的 add 命令更稳（后者在 Windows / 非 ASCII 路径下对引号/编码处理有坑）；写 TOML 时只增删 reconbridge 表块，用户其它配置与注释原样保留。如只想在本仓库目录内启用 Claude，见 .mcp.json.example。自己构建 exe：./build_exe.ps1（产出 dist/reconbridge-mcp-win64.zip）。

设备端（刷入 KernelSU 模块）

设备需已 root（KernelSU），装 ZygiskNext（M3/M4 动态 hook 需要）。

./build.ps1               # 用 NDK 编译 arm64-v8a（需 Android NDK，见下）
./pack.ps1                # 打包 dist/ReconBridge-M1.zip

在 KernelSU Manager → 模块 → 从本地安装 dist/ReconBridge-M1.zip → 重启。

仓库已内置预编译产物（module/bin、module/zygisk、module/system/lib64），若不想自己编译，直接 ./pack.ps1 打包即可，或用 Releases 里的 zip。

装好后对 Claude Code 说一句「连一下手机看状态」即可开始。详见下方各里程碑文档。

手机 AI 直连（Streamable HTTP）

手机端 MCP 与 PC 端口完全独立，固定只监听设备回环地址。可在 KernelSU WebUI 的「手机本地 MCP」卡片开启，或执行：

sh /data/adb/modules/reconbridge/rbctl mcp-enable
# 可选：修改端口，不能与 PC 端口相同
sh /data/adb/modules/reconbridge/rbctl setmcpport 8790

在支持 Streamable HTTP、自定义请求头和明文 localhost HTTP 的手机 AI 客户端中添加 MCP 配置时，必须在 AI 软件的「自定义请求头 / Custom Headers」中新增：

  • 请求头名称：X-Token
  • 请求头值：KernelSU WebUI 中显示的完整 token

不要把 token 填进 URL、MCP 名称或请求体。最终配置应为：

传输类型：Streamable HTTP
URL：http://127.0.0.1:8790/mcp
自定义请求头：
  X-Token: <WebUI 中显示的完整 token>

也支持 Authorization: Bearer <token>。手机 MCP 可在 PC 端口关闭时单独运行，提供与 PC MCP 相同的 25 个工具名称和输入契约；设备、文件、进程、shell、hook、事件、场景、Java trace/patch、dump 与产物工具均直接在手机执行。

decompile_apk、dexkit_search、ghidra_analyze、hermes_decompile 需要额外的 ReconBridge Mobile Toolpack，标准模块包目前不内置这些大型静态分析后端。未安装时工具会返回明确的 ok: false 和预期执行器路径，可用 toolchain_status 检查；PC MCP 的本地 jadx/androguard/Ghidra/Hermes 不受影响。

pull_apk、pull_libs、read_remote_file、list_dumps 和 list_artifacts 返回的文件会附带 artifact：其中包含 30 分钟有效的 download_url 和单文件 download_headers。AI 软件的 rootfs 可直接流式下载，不需要把二进制放进 MCP JSON：

curl -L -C - \
  -H 'Authorization: Bearer <artifact.download_headers 中的短期 token>' \
  '<artifact.download_url>' \
  -o base.apk

下载支持 HEAD、Range 续传和 ETag；也可改用 MCP 配置中的全局 X-Token。artifact ID 只映射模块工作目录和 dumps 目录中的普通文件，过期、被替换或内容元数据发生变化后不再提供下载。

里程碑总览

里程碑 内容 文档
M1 静态传输层：KernelSU 模块 + C++ HTTP 守护进程 + WebUI + 静态接口 本文（下方）
M2 PC 端 MCP Server：M1 接口 + 本地反编译链（jadx / DexKit→androguard / Ghidra / Hermes）封装为 Claude Code 工具 pc/README.md
M3 通用动态 hook 执行器：Zygisk 注入 + 数据驱动 ShadowHook + SSE/WS 命中推流 m3/README.md · 协议 m3/HOOK_PROTOCOL.md
M4 加固/反调试增强：通用内存 dex dump（/dump_dex）+ 反检测 hook 配置模板 m4/README.md
M5 通用 Java trace + 实时篡改与 Action Pipeline（LSPosed 模块） m5/README.md · 协议 m5/JAVA_HOOK_PROTOCOL.md

构建全部产物：./build.ps1 → ./pack.ps1（生成 dist/ReconBridge-M1.zip）。

设备端注意：Windows 经 adb 传 /data/... 路径需 export MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*'（Git Bash 否则会改写 Unix 路径）。

M1 —— 静态传输层

KernelSU 模块骨架 + C++ HTTP 守护进程 + WebUI 端口开关 + 静态接口。

目录结构

逆向模块/
├─ src/
│  ├─ daemon.cpp              # C++17 守护进程源码
│  └─ third_party/
│     ├─ httplib.h            # cpp-httplib 0.18.3（单头）
│     └─ json.hpp             # nlohmann/json 3.11.3（单头）
├─ module/                    # 刷入 zip 的内容（zip 根 = 此目录）
│  ├─ module.prop
│  ├─ customize.sh            # 安装脚本（架构检查 / 权限）
│  ├─ service.sh              # late_start 拉起守护进程
│  ├─ rbctl                   # 控制脚本（enable/disable/info…）
│  ├─ bin/reconbridge_daemon  # 编译产物（arm64-v8a）
│  └─ webroot/index.html      # KernelSU WebUI
├─ CMakeLists.txt             # cmake 构建（可选）
├─ build.ps1                  # 直接用 NDK clang++ 构建（推荐，无需 cmake）
├─ pack.ps1                   # 打包成刷入 zip
└─ README.md

一、编译

需要 Android NDK（本项目用 r27c）。已在 %LOCALAPPDATA%\Android\Sdk\ndk\ 下自动探测。

# 方式 A（推荐，无需 cmake）：直接调用 NDK clang++
./build.ps1

# 方式 B：cmake + ninja
cmake -B build -G Ninja `
  -DCMAKE_TOOLCHAIN_FILE=$env:ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake `
  -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-26 -DCMAKE_BUILD_TYPE=MinSizeRel
cmake --build build

产物：module/bin/reconbridge_daemon（AArch64 PIE ELF，~900 KB，静态链接 libc++）。

二、打包刷入 zip

./pack.ps1
# 生成 dist/ReconBridge-M1.zip

三、刷入

  • KernelSU Manager → 模块 → 从本地安装 → 选 ReconBridge-M1.zip → 重启。
  • 或 adb： 
    adb push dist/ReconBridge-M1.zip /data/local/tmp/
adb shell su -c "ksud module install /data/local/tmp/ReconBridge-M1.zip"
adb reboot

四、开启端口

重启后端口默认关闭。在 KernelSU Manager → 模块 → ReconBridge 打开 WebUI：

  1. 打开「端口开关」。
  2. 记下页面显示的 访问 URL（如 http://192.168.x.x:8787）与 token。
  3. 用完记得关闭开关。

WebUI 只写 config.conf，守护进程通过 inotify 感知变更即时生效，不直接控制 native 进程。

五、验收（PC 侧，同一 Wi-Fi）

设 IP/TOKEN/PKG 为实际值：

# 1) 存活
curl -H "X-Token: TOKEN" http://IP:8787/health

# 2) 列应用
curl -H "X-Token: TOKEN" "http://IP:8787/packages"

# 3) 查某应用全部 apk 路径（含所有 split）
curl -H "X-Token: TOKEN" "http://IP:8787/apk?pkg=PKG"

# 4) 拉某个 apk（流式，等价 adb pull，不依赖 adb 授权）
#    从上一步取到具体 path 后：
curl -H "X-Token: TOKEN" "http://IP:8787/apk?pkg=PKG&path=/data/app/.../base.apk" -o base.apk

# 5) 拉 native so
curl -H "X-Token: TOKEN" "http://IP:8787/libs?pkg=PKG"
curl -H "X-Token: TOKEN" "http://IP:8787/libs?pkg=PKG&path=/data/app/.../lib/arm64/libfoo.so" -o libfoo.so

# 6) 读任意文件
curl -H "X-Token: TOKEN" "http://IP:8787/file?path=/system/build.prop"

# 7) procfs
curl -H "X-Token: TOKEN" "http://IP:8787/proc?pid=1&what=status"

# 8) 白名单 shell
curl -H "X-Token: TOKEN" -X POST "http://IP:8787/shell" \
     -d '{"argv":["getprop","ro.product.model"]}'

M1 验收标准：PC 上用 curl 带 token，能把手机上任意一个 App 的完整 APK（含所有 split）和 native so 拉到本地，效果等价于 adb pull 但不依赖 adb 授权。

静态接口清单

方法 路径 说明
GET /health 存活探测（name/version/pid/uptime）
GET /packages 列出已安装应用（包名 / versionCode / 路径 / 是否系统应用）
GET /apk?pkg= 列出该应用全部 apk 路径（base + split）；加 &path= 流式下载单个
GET /file?path= root 流式读任意文件（绝对路径）
GET /libs?pkg= 列出该应用 lib 目录下 native .so；加 &path= 下载单个
GET /proc?pid=&what=maps|status|cmdline 转发 procfs
POST /shell 白名单命令执行，body：{"argv":[...]} 或 {"cmd":"..."}

鉴权：三选一 —— 请求头 X-Token: <token>、Authorization: Bearer <token>、或查询参数 ?token=<token>。

/shell 白名单：id whoami getprop uname ls cat stat du df md5sum sha1sum sha256sum pm cmd dumpsys ps getenforce settings wc head tail ip netstat pgrep mount readlink basename dirname find date。不走 sh -c，直接 execvp，白名单外拒绝。

安全说明

  • 端口默认关闭，仅用户在 WebUI 手动开启，用完手动关闭；重启后回到关闭。
  • 全部接口 token 鉴权；token 启动时随机生成（16 字节 hex）。
  • 默认绑定 wlan0 的局域网 IP（bind=auto），非 0.0.0.0；未探测到时回退 0.0.0.0 并告警。监听地址可在 **WebUI「网络设置」→「监听地址」**修改（auto / 0.0.0.0 / 具体 IP / 127.0.0.1）。注意 adb 模式连接会自动把它设为 127.0.0.1。
  • 手机侧只做搬运，不含任何特定 App 逻辑（符合 ndde.md 设计原则）。

运行时文件

/data/adb/reconbridge/：

  • config.conf —— enabled / port / bind / token
  • daemon.log —— 守护进程日志

已知限制（M1）

  • /packages 的「版本」取 versionCode（pm 一次调用即可，快）；versionName 需 dumpsys，M1 未纳入。
  • /libs 只列落地的 .so；若应用 extractNativeLibs=false，so 在 apk 内 lib/arm64-v8a/，请用 /apk 拉包后本地解包（接口会在 note 提示）。
  • /shell 的 cmd 字符串按空白朴素切分，不支持引号；复杂命令用 argv 数组形式。

About

通用逆向分析 KernelSU 模块：手机侧只做原子能力，智能全在 PC 侧（Claude Code + MCP）。仅限授权安全研究与教育用途。

Topics

androguardandroidandroid-hookingapk-analysisclaude-codectf-toolsdex-dumpdexkitfrida-alternativeghidrajadxkernelsulsposedmagisk-modulemcpmcp-servermodel-context-protocolreverse-engineeringsecurity-researchzygisk

Resources

Readme
MIT license
Activity

Stars

15 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages