NIGHT-z8a/ModPatcher

# ModPatcher 将 mod menu 自动注入到 Android APK（.apks bundle）的自动化流水线。 ## 流水线 ``` extract → decompile → inject → build → zipalign → sign ``` ## 快速开始 ``` # 1. 安装 dependencies bash setup.sh # 2. 运行（支持 .apk 和 .apks） python3 main.py --input game.apk --modmenu app-debug.apk python3 main.py --input game.apks --modmenu app-debug.apk ``` ## 环境要求 | 工具 | 用途 | |------|---------| | Python 3.10+ | 运行时环境 | | apktool | 反编译 / 重新打包 APK | | Java JDK | apktool 运行和签名的必要条件 | | apksigner | 签名 APK（来自 Android SDK build-tools） | | unzip | 解压 .apks bundle | ## 安装说明 ### 选项 1：自动安装 ``` bash setup.sh ``` ### 选项 2：手动安装 ``` # Ubuntu/Debian sudo apt install -y default-jdk apktool unzip python3-pip pip3 install pyyaml # Arch sudo pacman -S jdk-openjdk apktool unzip python-pip pip install pyyaml # macOS brew install openjdk apktool unzip pip3 install pyyaml ``` 然后安装 [Android SDK 命令行工具](https://developer.android.com/studio#command-line-tools-only)并设置 `ANDROID_HOME`： ``` export ANDROID_HOME=$HOME/Android/Sdk ``` ## 使用方法 ### 基础用法 ``` python3 main.py --input game.apks --modmenu app-debug.apk ``` ### 使用选项 ``` python3 main.py \ --input game.apks \ --modmenu app-debug.apk \ --output ./output \ --output-name MyMod.apk \ --arch armeabi-v7a \ --lib libGameHack.so ``` ### 参数说明 | 标志 | 简写 | 必填 | 默认值 | 描述 | |------|-------|----------|---------|-------------| | `--input` | `-i` | 是 | — | 目标 .apk 或 .apks bundle | | `--modmenu` | `-m` | 是 | — | mod menu APK（从源码构建） | | `--output` | `-o` | 否 | `./output` | 输出目录 | | `--output-name` | — | 否 | `ModMenu.apk` | 输出文件名 | | `--arch` | `-a` | 否 | `arm64-v8a` | 目标架构：`arm64-v8a`、`armeabi-v7a`、`x86`、`x86_64` | | `--lib` | `-l` | 否 | `libMyLibName.so` | mod menu 的 .so 文件名 | | `--sdk-path` | — | 否 | auto | Android SDK 路径 | | `--config` | `-c` | 否 | `config.yaml` | 自定义配置文件 | | `--keep-work` | — | 否 | false | 构建后保留工作目录 | ## 项目结构 ``` ├── config.yaml # All configurable settings ├── main.py # Entry point ├── requirements.txt # Python dependencies ├── setup.sh # Dependency installer ├── patcher/ │ ├── extractor.py # .apks bundle extraction │ ├── decompiler.py # apktool decompile / build │ ├── injector.py # smali injection, manifest edits │ ├── packager.py # zipalign + apksigner │ └── utils.py # helpers, tool discovery ├── templates/ │ └── hooks/ │ └── modmenu.smali # Smali hook template └── README.md ``` ## 工作原理 1. **解压** — 如果是 `.apks`，则解压 bundle 以获取 `base.apk` 和拆分 APK。如果是 `.apk`，则直接使用 2. **反编译** — 使用 apktool 反编译基础 APK 和 mod menu APK 3. **注入** — 复制 mod menu 的 smali 文件、.so 库和游戏原生库 4. **Hook** — 将 `Main.Start()` 调用注入到游戏主 activity 的 `onCreate` 中 5. **清单文件** — 添加 `SYSTEM_ALERT_WINDOW` 权限和 `Launcher` 服务，移除拆分属性 6. **构建** — 使用 apktool 重新构建 APK 7. **Zipalign** — 将未压缩文件（.arsc、.so）对齐到 4 字节边界 8. **签名** — 使用 apksigner 签名（v2/v3 方案，保持对齐） ## 自定义 ### 修改 Hook 编辑 `templates/hooks/modmenu.smali`： ``` invoke-static {p0}, Lcom/android/support/Main;->Start(Landroid/content/Context;)V ``` ### 修改 Mod Menu 包名 如果你的 mod menu 使用了不同的包名，请更新 `config.yaml`： ``` hook: template: "templates/hooks/modmenu.smali" detection_pattern: "com/yourpackage/Main.*->Start" ``` ### 添加更多权限 编辑 `config.yaml`： ``` manifest: add_permissions: - "android.permission.SYSTEM_ALERT_WINDOW" - "android.permission.INTERNET" ``` ## 故障排除 ### "未找到 apksigner" 设置 `ANDROID_HOME` 或传入 `--sdk-path`： ``` export ANDROID_HOME=$HOME/Android/Sdk # 或 python3 main.py --input game.apks --modmenu menu.apk --sdk-path /path/to/sdk ``` ### "未找到 apktool" 安装它：https://apktool.org/docs/install ### "Unsigned short value 超出范围" 单个 dex 中的方法数过多。脚本会将 mod menu 文件放入编号最高的 `smali_classes` 目录中。如果游戏有多个 dex，这应该会自动生效。 ### 游戏启动时崩溃 - 检查 .so 架构是否与你的设备匹配 - 验证 hook 是否被注入到了正确的 activity 中 - 使用 `adb logcat` 检查崩溃日志 ## 许可证 本项目基于 [GNU 通用公共许可证 v3.0](LICENSE) 授权。

标签：apktool, APK修改, APK反编译, APK注入, APK签名, CSV导出, Mod菜单, Python, SO库注入, 云资产清单, 安卓, 安卓逆向, 应用篡改, 恶意代码分类, 无后门, 游戏破解, 目录枚举, 移动安全, 逆向工具, 逆向工程, 重打包