droid-re-chain

Headless AI-driven Android reverse engineering automation pipeline.

An MCP server exposing 122 tools across 8 categories for automated static/dynamic analysis of Android arm64 Unity/il2cpp applications. Runs with any MCP-compatible agent: Cursor, Claude Code, opencode, VS Code (Continue/Roo Cline), or any custom MCP host.

One-Liner Install

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/c4x64/droid-re-chain/main/install.sh | bash

# With custom NDK path
curl -fsSL https://raw.githubusercontent.com/c4x64/droid-re-chain/main/install.sh | bash -s -- --ndk /opt/ndk

# Windows (PowerShell)
powershell -Command "iwr -Uri https://raw.githubusercontent.com/c4x64/droid-re-chain/main/install.bat -OutFile install.bat; .\install.bat"

# Run from anywhere
droidre                    # stdio mode (for MCP hosts)
droidre --sse              # SSE mode

# Or from the project dir
cd ~/droid-re-chain && python3 -m src.server

Quick Start

git clone https://github.com/c4x64/droid-re-chain.git
cd droid-re-chain
pip install -r requirements.txt
droidre                        # stdio mode (for MCP hosts)
droidre --sse                  # SSE mode (for browser/dev tools)

For NDK builds, set ANDROID_NDK_HOME to your NDK r25+ path.

Architecture

src/server.py              — MCP entrypoint (--sse/--stdio flags)
src/shared.py              — CrashTrapDaemon, _adb_run, NDK paths, cross-platform OS detection
src/tools_adb.py           — 16 ADB/emulator management tools
src/tools_ndk.py           — 16 NDK/compilation/CMake/ELF verification tools
src/tools_il2cpp.py        — 15 symbol/metadata/Unity runtime tools
src/tools_hook.py          — 15 memory patching/trampoline generation tools
src/tools_trap.py          — 15 logcat crash trap/tombstone analysis tools
src/tools_mem.py           — 15 process/memory/maps/pattern scan tools
src/tools_frida.py         — 15 Frida attach/spawn/stalker/hook tools
src/tools_apk.py           — 15 APK decompile/recompile/sign/patch tools
include/il2cpp.h           — il2cpp API wrapper (READ ONLY)
include/logging.h          — Thread-safe logging, BUILD_HASH, null guards
src/main.cpp               — NDK hook module (constructor guard, install_hook)
scripts/build_ndk.py       — ccache/LTO/sanitizer/ELF verify builder

Tool Categories

Total: 151 tools

Multi-Client Setup

droid-re-chain works with 20+ MCP-compatible clients. Run the auto-installer:

bash scripts/setup_mcp.sh

It detects installed clients and writes configs for all of them:

See MCP_CLIENTS.md for per-client details.

opencode

Already configured in config/opencode.json. Symlink:

ln -sf $PWD/config/opencode.json $PWD/opencode.json

CLI / Any MCP Host

droidre                                   # stdio (default, from anywhere)
droidre --sse --port 8080                 # SSE mode
bash mcp-entrypoint.sh                    # portable launcher

Prerequisites

• Python 3.10+
• Android NDK r25+ — set ANDROID_NDK_HOME for compilation tools
• ADB (platform-tools) — brew install android-platform-tools / apt install adb
• Android emulator or device with ADB debugging enabled (root optional; some tools need su)

Optional

• Frida — pip install frida-tools for frida_* tools
• apktool — for apk_decompile_smali / apk_recompile
• apksigner — for apk_sign (comes with Android SDK build-tools)
• ccache — brew install ccache / apt install ccache (speeds up NDK rebuilds)

Typical Workflow

1. Pull APK from device (apk_pull_from_device)
2. Decompile to smali   (apk_decompile_smali)
3. Find il2cpp offsets   (il2cpp_find_class → il2cpp_find_method → il2cpp_get_method_pointer)
4. Generate hook        (hook_il2cpp_method / hook_arm64_inline)
5. Compile libmod.so    (ndk_build_module)
6. Verify ELF           (verify_elf_header → verify_elf_symbols)
7. Push to device       (adb push via adb_file_*)
8. Frida attach         (frida_attach → frida_eval_script)
9. Monitor crashes      (trap_start_daemon → trap_get_crashes → trap_analyze_crash)
10. Patch & repeat      (trap_suggest_patch → hook_arm64_inline → rebuild)

Cross-Platform

Auto-detects macOS/Linux/Windows for:

• ADB binary name (adb / adb.exe)
• NDK host tag (darwin-x86_64, darwin-aarch64, linux-x86_64, windows-x86_64)
• NDK fallback paths (Homebrew, ~/Android/Sdk, ~/android-ndk)

Development

make install       # pip install everything
make build-release # NDK compile via scripts/build_ndk.py
make test          # 36 tests, all pass
make lint          # ruff check src/
make docs          # regenerate docs/api.md

Testing

python3 -m pytest tests/ -v

36 tests covering OS detection, NDK path resolution, crash parser (empty/signal/full backtrace), ADB error handling, error limit truncation, daemon lifecycle.

Files

License

MIT