DroidReaver

Previously known as DexMachina. See MIGRATING.md if you are updating old installs, scripts, or workspace config.

Android pentest environment manager — install, sync, diagnose, and repair your entire mobile security toolkit from one CLI.

DroidReaver is evolving from a tool manager into a full Android penetration environment: one command to get adb, frida, jadx, apktool, and the rest of your kit installed, version-locked, and working together. It solves dependency hell — tools like objection, r2frida, and frida-tools all require the exact same frida version, and apktool needs a compatible JDK.

Why DroidReaver

Most Android pentest setups grow from shell history, old notes, and a handful of one-off install scripts. DroidReaver turns that into a repo-local, reproducible environment: curated profiles, version pins, a lockfile, Frida runtime isolation, device readiness checks, and doctor/fix when the setup drifts.

It is not a replacement for MobSF, Corellium, Burp, or manual reverse-engineering judgment. It is the glue layer that gets a consistent workstation and rooted emulator/device ready faster than rebuilding the same adb/frida/objection/jadx setup for every engagement.

Trust and Support

• Trust model: THREAT_MODEL.md
• Vulnerability reporting: SECURITY.md
• Contributing and adding tools: CONTRIBUTING.md
• Rename/migration guide: MIGRATING.md
• Release process: docs/RELEASE.md
• Branch protection checklist: .github/BRANCH_PROTECTION.md
• Release history: CHANGELOG.md

Support matrix

Known good device setups

Install

Recommended: pipx

pipx installs DroidReaver in an isolated environment and exposes the droidreaver command on your shell PATH.

# Kali/Debian/Ubuntu
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install droidreaver

On other Python installs where pipx is not packaged by the OS:

python -m pip install --user pipx
python -m pipx ensurepath
python -m pipx install droidreaver

Restart your terminal, then verify:

droidreaver --help

PyPI with pip

python -m pip install droidreaver

On Kali, Debian 12+, Ubuntu 23.04+, and other PEP 668 distributions, system Python may reject this with externally-managed-environment. Use pipx instead, or install inside a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install droidreaver
droidreaver --help

Avoid --break-system-packages unless you intentionally want to modify the OS Python environment.

If the install succeeds but droidreaver is not found, your Python scripts directory is not on PATH. You can still run DroidReaver as a module:

python -m droidreaver --help

Or add the scripts directory printed by pip to your shell PATH. Common fixes:

# Linux/macOS user installs
python -m pip install --user droidreaver
export PATH="$HOME/.local/bin:$PATH"

# Windows PowerShell user installs
py -m pip install --user droidreaver
$env:PATH = "$env:APPDATA\Python\Python311\Scripts;$env:PATH"

On Windows, the exact Python311 part depends on your Python version. If you use the Python launcher, this always works even when the console script is not on PATH:

py -m droidreaver --help

From GitHub

Install the latest master directly:

python -m pip install "git+https://github.com/Codeblin/DroidReaver.git"

Install a specific release tag:

python -m pip install "git+https://github.com/Codeblin/DroidReaver.git@v0.1.0"

Developer install

git clone https://github.com/Codeblin/droidreaver.git
cd droidreaver
python -m pip install -e ".[dev]"

Run via the installed entrypoint or as a module:

droidreaver --help          # full ASCII banner + commands
droidreaver status          # compact banner + tool table
python -m droidreaver doctor

Set DROIDREAVER_NO_BANNER=1 or pass --no-banner to suppress the ASCII art (useful for scripts/CI).

Use it as a self-contained pentest environment (recommended)

Turn any repo into a portable Android pentest kit. Tools are downloaded into ./.droidreaver/tools/, version-locked, and added to your PATH on demand — the heavy binaries stay gitignored, while the config and lockfile are committed for reproducibility.

cd my-engagement-repo

droidreaver init                 # create droidreaver.toml + .gitignore + .droidreaver/tools
droidreaver up                   # install the profile + set up frida (one command)
droidreaver console              # interactive pentest REPL (recommended)
droidreaver shell                # …or a raw subshell with every tool on PATH

Inside droidreaver shell, tools like jadx, apktool, objection, and frida are directly on your PATH. Type exit to leave.

If doctor or fix reports that a managed tool is installed but not on your shell PATH, use DroidReaver's managed environment instead of editing global shell startup files:

droidreaver shell
# or:
eval "$(droidreaver env)"

Pentest a rooted emulator — full walkthrough

Assuming a rooted emulator/device is running with USB debugging (e.g. a Genymotion / rooted AVD / Corellium instance, visible via adb devices):

# 0) one-time: build the dynamic-analysis kit (adb, frida, objection, …)
droidreaver up --profile dynamic

# 1) drop into the interactive console
droidreaver console

Then drive the engagement from the DroidReaver console:

droidreaver [no-device | no-target]> devices          # auto-selects a single device
droidreaver [emulator-5554 | no-target]> ready        # push + start frida-server
droidreaver [emulator-5554 | no-target]> apps owasp   # find your target (filter)
droidreaver [emulator-5554 | no-target]> target com.example.app
droidreaver [emulator-5554 | com.example.app]> status # device + frida + target summary
droidreaver [emulator-5554 | com.example.app]> proxy 10.0.2.2:8080   # route HTTPS to Burp
droidreaver [emulator-5554 | com.example.app]> hook   # SSL pinning + root bypass (spawn)
droidreaver [emulator-5554 | com.example.app]> objection             # interactive explorer
droidreaver [emulator-5554 | com.example.app]> logcat com.example.app   # watch logs
droidreaver [emulator-5554 | com.example.app]> exit

The console keeps live session state (selected device + target app), so you don't retype serials/packages. Every verb maps to the same engines the flat CLI uses (device ready, bypass, objection, …) — just faster to chain.

Console commands

Reproduce the exact kit on another machine:

droidreaver lock                 # write droidreaver.lock.toml (commit this)
# … teammate clones the repo …
droidreaver restore              # install the locked tools + frida runtime

Quick Start

# One-command environment (auto-inits a repo-local workspace inside a git repo)
droidreaver up --profile dynamic

# See / inspect profiles
droidreaver profile list
droidreaver profile show static

# Drive an engagement interactively
droidreaver console              # pentest REPL with live device + target state

# Put every installed tool on PATH
droidreaver shell                # subshell (easiest)
droidreaver env                  # or print the PATH snippet for your shell

# Get a single tool, downloaded + on PATH + verified
droidreaver get jadx

# Get a device frida-ready in one shot (runtime + push-server + verify)
droidreaver device ready

# Check what's installed vs latest (use --offline to skip network)
droidreaver status --offline

# Diagnose / auto-repair
droidreaver doctor
droidreaver fix --bootstrap

When to run up

Run droidreaver up when creating an environment, after cloning an engagement workspace, or after changing its profile, pins, or lockfile. It is safe to run again: tools and Frida environments that already satisfy the configuration are skipped. Use droidreaver update for upgrades and --force only when you intentionally want a reinstall.

For a normal daily pentest session, you usually only need:

droidreaver device ready          # reconnect/restart the matching frida-server
droidreaver console               # resume device + target workflow

Commands

Get started

Environment

Device & arsenal

Profiles

Profiles are curated tool bundles for one-command setup with droidreaver up --profile NAME:

Repo-local layout

droidreaver init produces a portable, reproducible workspace:

my-repo/
├── droidreaver.toml         # committed — settings + profile + pins
├── droidreaver.lock.toml    # committed — exact installed versions (droidreaver lock)
├── .gitignore              # auto-updated to ignore downloaded tools
└── .droidreaver/
    ├── tools/              # downloaded CLIs/jars (gitignored)
    └── cache/              # PyPI/GitHub cache (gitignored)

Frida runtimes live in per-version venvs under ~/.droidreaver/venvs/ (machine-specific, recreated by droidreaver use / droidreaver restore), so they're never committed.

Configuration

~/.droidreaver/droidreaver.toml (or ./droidreaver.toml in the project directory):

[settings]
adb_path = "adb"
java_path = "java"
install_dir = "~/.droidreaver/tools"
auto_push_frida_server = false

[pins]
frida = "16.1.4"   # pins the entire frida group

[ignored]
tools = ["ghidra", "wireshark"]

Frida pin group (important)

The frida runtime (pip package frida) uses the version you care about for device hooks — e.g. 17.11.0.

frida-tools and objection have their own pip version numbers (e.g. 14.9.0, 1.12.5) but must be compatible with the frida runtime. DroidReaver never installs frida-tools==17.11.0 — that was the old bug.

After droidreaver use X, run the droidreaver env output in your shell, then droidreaver push-server.

Arsenal — run tools through DroidReaver

Tools with a CLI are registered as native commands:

droidreaver arsenal              # ready vs missing
droidreaver frida --version
droidreaver frida-ps -U
droidreaver objection explore
droidreaver jadx --help
droidreaver run mitmproxy        # explicit form

Resolution order: active frida venv → ~/.droidreaver/tools/*/bin → system PATH.

Tool Categories

• Dynamic Analysis — frida, objection, r2frida, medusa
• Static Analysis — jadx, apktool, smali, radare2, ghidra (manual)
• Traffic Interception — mitmproxy, apk-mitm, Burp (manual)
• Device & ADB — adb, scrcpy, pidcat, androguard
• APK Manipulation — uber-apk-signer, apksigner (manual)
• Automated Scanners — MobSF, drozer, nuclei
• Data & Storage — binwalk, trufflehog, gitleaks
• Network — nmap, tcpdump, wireshark (manual)

Manual-only tools appear in status and doctor with install instructions but are not auto-installed.

droidreaver fix

Three-phase repair flow: diagnose → plan → apply → re-check.

Safe by default (from doctor findings):

Flags:

Manual steps (Python upgrade, Java, Node.js, no device connected) are listed but never auto-applied.

Impact levels

Each fix shows an Impact column — how disruptive the change is, not a security rating.

Every droidreaver fix run prints a legend panel explaining these before the plan. Use --no-legend to hide it.

Roadmap: Pentest Environment

DroidReaver aims to become a batteries-included Android pentest environment:

• Today — tool registry, version pinning, doctor, fix, frida-server push
• Next — environment profiles (minimal, dynamic, full), PATH/setup shell hook, workspace templates
• Future — bundled configs (mitmproxy certs, MobSF docker compose), project scaffolds, CI-ready headless mode

GitHub API

Release versions are fetched from the GitHub Releases API with a 1-hour cache in ~/.droidreaver/cache/. Set GITHUB_TOKEN to avoid rate limits.

On Kali or shared networks you may hit unauthenticated GitHub API limits during droidreaver up, install, or fix --bootstrap. Create a fine-grained GitHub token with read-only public repository access and export it before retrying:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
droidreaver fix --bootstrap

Development

pip install -e ".[dev]"
pytest

License

MIT