luca-regne/batuta
GitHub: luca-regne/batuta
整合多种逆向工具的 Android 应用静态分析命令行工具，提供从 APK 提取、反编译到修改重打包的一站式工作流。
Stars: 0 | Forks: 0
# batuta
`batuta` 是一个用于 Android 应用程序静态分析的 Python CLI —— 专为渗透测试人员、漏洞赏金猎人和恶意软件分析师设计。它在干净、可组合的界面背后封装了经过实战检验的 RE 工具（`apktool`、`jadx`、`adb`、`APKEditor`）。
## 功能特性
- **APK 提取** —— 通过包名、应用名或过滤模式提取 APK
- **Split APK 支持** —— 自动检测拆分包，提取每个部分，并通过 `batuta apk merge` 或 `--auto-merge` 合并它们
- **反编译** —— 通过 `batuta apk decompile` 或 `batuta apk pull --decompile` 运行 `jadx` 和/或 `apktool`
- **APK 修补** —— 通过 `batuta apk patch` 重新构建、对齐、签名并选择性安装
- **框架检测** —— 通过 `batuta analyze framework` 检测跨平台框架（Flutter, React Native, Xamarin, Cordova, Unity）
- **交互式选择** —— 搜索时在出现多个匹配项时进行选择（自动提示）
- **脚本优先设计** —— 每个命令都支持 `--json` 输出，以便通过管道传输到 `jq`、`grep` 或自定义工具
- **库优先架构** —— 核心逻辑可独立于 CLI 导入使用
## 环境要求
### Python
- Python >= 3.14
### 外部工具
这些工具必须安装并在您的 `PATH` 中可用：
| 工具 | 用途 | 安装 |
| ----------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `adb` | Android Debug Bridge — 设备通信 | [Android SDK Platform Tools](https://developer.android.com/tools/releases/platform-tools) |
| `apktool` | APK 解码, smali 反汇编 | [Apktool Webiste](https://apktool.org/) |
| `jadx` | Java/Kotlin 反编译 | [Jadx GitHub Repository](https://github.com/skylot/jadx) |
| `APKEditor` | Split APK 合并 | [APKEditor Repository](https://github.com/REAndroid/APKEditor) |
`batuta` 会在命令入口检查所需工具，并在缺失时报告清晰的安装说明。
### 配置 APKEditor
`APKEditor` 以 JAR 文件形式发布。Batuta 按以下顺序解析它：
1. `APKEDITOR_JAR` 环境变量（指向 `.jar` 或其父目录）
2. `~/.batuta/config.json` → `apkeditor_path`
3. 位于 `PATH` 中某处名为 `APKEditor` 的可执行封装器
示例：
```
# 1. 环境变量（仅当前 shell 临时生效）
export APKEDITOR_JAR="$HOME/tools/APKEditor/APKEditor.jar"
# 2. 配置文件（~/.batuta/config.json）
{
"apkeditor_path": "~/tools/APKEditor/APKEditor.jar"
}
# 3. 放置在 PATH 中的 Wrapper 脚本（例如，/usr/local/bin/APKEditor）
#!/bin/bash
exec java -jar "$HOME/tools/APKEditor/APKEditor.jar" "$@"
```
您可以将 `apkeditor_path` 指向 JAR 文件本身或包含 `APKEditor.jar` 的目录。无论您使用哪种解析方法，Batuta 都会在合并后保留提取的拆分目录原封不动。
## 安装
使用 uv 从源码安装：
```
git clone https://github.com/luca-regne/batuta
cd batuta
uv sync
```
或使用 pip：
```
pip install -e .
```
## 快速入门
```
# 列出已连接的设备
batuta device list
# 按名称搜索包
batuta apk search google
# 获取包的详细信息
batuta apk info com.example.app
# 拉取 APK（支持部分名称和过滤器）
batuta apk pull youtube
# 在存在多个匹配项时进行交互式选择拉取（自动提示）
# 拉取到指定目录
batuta apk pull com.example.app --output ./apks/
# 拉取并立即反编译
batuta apk pull com.example.app --decompile
# 从本地 APK 进行独立反编译
batuta apk decompile ./apks/com.example.app.apk --java-only
# 合并 split APK 目录（保留原始文件）
batuta apk merge ./apks/com.example.app --output ./apks/com.example.app.merged.apk
# 检测跨平台框架
batuta analyze framework ./apks/com.example.app.apk
# 带 JSON 输出的框架检测
batuta analyze framework ./apks/com.example.app.apk --json
```
## 命令参考
```
batuta
├── analyze
│ └── framework Detect cross-platform frameworks in APK
│
├── device
│ ├── list List connected ADB devices
│ └── shell [COMMAND...] Open ADB shell (or run command)
│
└── apk
├── list List installed packages
├── search Search packages by name or filter
├── info Show detailed package information
├── pull Pull APK from connected device (optional decompile)
├── merge Merge split APK folder into a single APK (keeps folder)
├── patch Build/align/sign APK from apktool output
└── decompile Decompile APK to Java and/or smali
```
### 通用选项
| 选项 | 描述 |
| ---------------- | -------------------------------------------------- |
| `--device`, `-d` | 通过 ID 指定目标设备 |
| `--json`, `-j` | 输出为 JSON 用于脚本 |
| `--system`, `-s` | 在搜索中包含系统包 |
| `--decompile` | (pull) 提取后反编译 (Java + smali) |
| `--auto-merge` | (pull) 通过 APKEditor 合并 split APK 文件夹 |
| `--java-only` | (pull/decompile) 仅限于 Java (`jadx`) 输出 |
| `--smali-only` | (pull/decompile) 仅限于 smali/资源 (`apktool`)
Split APK 提取操作总是会保存 base/split 部分的原始目录。使用 `--auto-merge` 立即合并（文件夹保持原样），或稍后运行 `batuta apk merge `。当提供 `--decompile` 时，拆分包会自动合并，以便 jadx/apktool 无需额外步骤即可运行。
### 示例
```
# 用于脚本编写的 JSON 输出
batuta device list --json | jq '.[0].id'
batuta apk search facebook --json | jq '.[].package_name'
# 指定目标设备
batuta apk pull com.example.app --device RX8WC00D7JE
# 包含系统包
batuta apk list --system --filter android
```
## 库用法
核心逻辑可独立于 CLI 导入使用：
```
from batuta.core.adb import ADBWrapper
# 列出设备
adb = ADBWrapper()
devices = adb.list_devices()
for device in devices:
print(f"{device.id}: {device.model} ({device.state})")
# 搜索包
packages = adb.search_packages("google")
for pkg in packages:
print(f"{pkg.package_name} v{pkg.version_name}")
# 拉取 APK
result = adb.pull_apk("com.example.app", output_dir=Path("./apks"))
print(f"Pulled to: {result.local_path}")
```
## 架构
```
src/batuta/
├── cli/ # Typer commands — argument parsing and rich output only
├── core/ # Business logic — importable as a library
├── models/ # Pydantic v2 data models
├── utils/ # Shared utilities: deps checker, output helpers, process wrapper
└── exceptions.py # Typed exception hierarchy
```
关键架构约束：
- `cli/` 永远不包含业务逻辑 —— 仅调用 `core/`
- 所有子进程调用都通过 `utils/process.py`
- 所有外部工具需求都在命令入口通过 `utils/deps.py` 检查
## 开发
```
# 安装 dev dependencies
uv sync --group dev
# Lint
ruff check src/batuta/
# 自动修复 lint 问题
ruff check src/batuta/ --fix
# 类型检查
mypy src/batuta/
# 运行 CLI
uv run batuta --help
```
## 许可证
MIT
标签：ADB, Amass, Android安全, Apktool, APK修补, APK反编译, DAST, Flutter, Jadx, Python, React Native, Unity, 云安全监控, 云资产清单, 恶意软件分析, 无后门, 框架识别, 目录枚举, 移动安全, 签名绕过, 自动化分析, 跨站脚本, 逆向工具, 逆向工程, 静态分析