std-microblock/fripack
GitHub: std-microblock/fripack
将 Frida 脚本打包为多种格式的可执行文件，解决 Frida 分发难、依赖重的问题
Stars: 205 | Forks: 45
# Fripack
### 将你的 Frida 脚本打包为可执行文件。
[中文](./README_zh.md)
Frida 是一个强大的工具，但其庞大的体积以及对 root 权限的需求，使得向最终用户分发脚本变得具有挑战性。这通常限制了 Frida 在为更广泛受众开发插件方面的应用。
Fripack 解决了这个问题，它将你的 Frida 脚本打包成各种可执行格式——例如 Xposed Modules、修补过的 apk、用于 `LD_PRELOAD` 的共享对象或可注入的 DLL——从而实现了基于 Frida 的插件的轻松分发和使用。
### 二进制文件大小很重要
最初的 Frida 项目体积相当大。Fripack 对 Frida 进行了精简和压缩，使得在所有平台（Linux 除外）上的二进制输出文件都小于 10 MB。
### 一键构建
跨平台 Frida 脚本往往使得为不同目标构建交付物变得繁琐——即使使用 Frida Gadget 也是如此。Fripack 通过支持一次性为多个平台进行构建，简化了开发流程。
## 安装
从 [releases 页面](https://github.com/std-microblock/fripack/releases/latest) 下载最新的二进制文件，并根据需要进行安装。
如果你的电脑上已经安装了 Rust，你也可以使用 cargo 进行安装：
```
cargo install --git https://github.com/std-microblock/fripack/
```
## 快速入门
### 基本配置
Fripack 使用名为 `fripack.json` 的配置文件，该文件支持 JSON5 语法。以下是一个基本示例：
```
{
"xposed": {
"type": "xposed",
"version": "1.0.0",
"fridaVersion": "17.5.1",
"entry": "main.js",
"platform": "android-arm64",
"xposed": {
"packageName": "com.example.myxposedmodule",
"name": "My Xposed Module"
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
}
}
```
配置中的每个键代表一个构建目标。你可以使用以下命令构建所有目标：
```
fripack build
```
或者构建特定目标（例如 `xposed`）：
```
fripack build xposed
```
或者监视特定目标的更改：
```
fripack watch xposed
```
### 通用配置选项
以下选项适用于所有目标类型：
- `xz` (默认值: `false`): 使用 LZMA 压缩脚本。
- `entry` (必填): 要打包的入口点脚本。
- `fridaVersion` (必填): 要使用的 Frida 版本（必须为 17.5.1 或更高版本）。
- `outputDir` (默认值: `./fripack`): 构建产物的输出目录。
- `platform`: 目标平台 (例如 `android-arm64`, `windows-x86_64`)。
- 有效值: `android-arm32`, `android-arm64`, `android-x86`, `android-x64`, `windows-x64`, `linux-x64`
- `version`: 插件的版本。
- `type`: 目标的类型 (定义输出格式)。
- `inherit`: 要继承配置的另一个目标的键。
- `targetBaseName` (可选): 输出文件的基本名称 (默认为目标键)。
- `beforeBuild` (可选): 在构建目标之前执行的命令。
- `afterBuild` (可选): 在成功构建目标之后执行的命令。
- `watchPath` 监视文件更改的附加目录。
- `pushPath` : 在 `watch` 模式下将 JavaScript 文件推送到设备的目标路径。默认为 `/data/local/tmp/fripack_dev.js`。
使用继承来避免重复的示例：
```
{
"base": {
"version": "1.0.0",
"fridaVersion": "17.5.1",
"entry": "main.js",
"xz": true,
"outputDir": "./fripack",
"platform": "android-arm64"
},
"xposed": {
"inherit": "base",
"type": "xposed",
"xposed": {
"packageName": "com.example.myxposedmodule",
"name": "My Xposed Module"
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
},
"raw-so": {
"inherit": "base",
"type": "shared"
}
}
```
只有包含 `type` 字段的目标才会被构建。
### 支持的目标类型
#### `xposed`
将你的 Frida 脚本构建为 Xposed Module。仅支持 `Android` 平台。
**需要：** 系统中已安装 [`apktool`](https://apktool.org/)。
**附加选项：**
- `xposed` (必填): Xposed 配置对象。
- `packageName` (必填): Xposed 模块的包名。
- `name` (必填): 模块的显示名称。
- `icon` (可选): 模块图标的路径 (期望在同一目录下包含 `ic_launcher.webp` 和 `ic_launcher_round.webp`)。
- `scope` (可选): 模块的建议目标作用域。
- `description` (可选): 模块的描述。
- `sign` (可选): 签名配置。如果作为对象提供，APK 将被签名。
- `keystore`: keystore 的路径。
- `keystorePass`: keystore 密码。
- `keystoreAlias`: keystore 中的别名。
- `keyPass` (可选): 签名者私钥的密码。
#### `shared`
将你的 Frida 脚本构建为共享库 (`.so` / `.dll`)，可以通过各种方法加载 (例如 `LD_PRELOAD`)。
#### `inject-apk`
通过修改现有 APK 的一个原生库，将你的 Frida 脚本注入其中。仅支持 `Android` 平台。
**需要：** 系统中已安装 [`apktool`](https://apktool.org/)。
同时也建议在你的路径中包含 [`zipalign`](https://developer.android.com/tools/zipalign)。
**附加选项：**
- `injectApk` (必填): 注入配置对象。
- `sourceApkPath` (可选): 要注入的源 APK 文件路径。
- `sourceApkPackageName` (可选): 要从已连接设备中提取的 APK 包名。
- 必须提供 `sourceApkPath` 或 `sourceApkPackageName` 中的任意一个。
- 当使用 `sourceApkPackageName` 时，APK 将从已连接的设备中提取并缓存以供将来构建。这需要系统中安装 [`adb`](https://developer.android.com/studio/command-line/adb)。
- `injectMode` (可选): 注入模式。目前仅支持 `"NativeAddNeeded"`。
- `targetLib` (可选): 注入目标的特定原生库 (例如 `"libnative-lib.so"`)。
- 如果未指定，将按以下优先顺序搜索库：
1. `libCrashSight.so`, `libBugly.so`, `libmmkv.so` (白名单)
2. lib 目录中最小的 `.so` 文件 (会有警告)
- `sign` (可选): 最终 APK 的签名配置 (格式与 Xposed 相同)。
- `keystore`: keystore 的路径。
- `keystorePass`: keystore 密码。
- `keystoreAlias`: keystore 中的别名。
- `keyPass` (可选): 签名者私钥的密码。
**配置示例：**
```
{
"inject-apk": {
"type": "inject-apk",
"platform": "android-arm64",
"fridaVersion": "17.5.1",
"entry": "main.js",
"injectApk": {
"sourceApkPackageName": "com.example.app",
"injectMode": "NativeAddNeeded",
"targetLib": "libnative-lib.so",
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
}
}
```
#### `zygisk`
将你的 Frida 脚本构建为 Magisk 的 Zygisk 模块。仅支持 `Android` 平台。
**附加选项：**
- `zygisk` (必填): Zygisk 配置对象。
- `id` (必填): 模块 ID
- `name` (必填): 模块显示名称
- `version` (可选): 模块版本 (默认为 "1.0")。
- `versionCode` (可选): 模块版本代码 (默认为 1)。
- `author` (可选): 模块作者 (默认为 "FriPack")。
- `description` (可选): 模块描述。
- `scope` (必填): 注入的目标应用程序，用分号分隔。
**配置示例：**
```
{
"zygisk": {
"type": "zygisk",
"platform": "android-arm64",
"fridaVersion": "17.5.1",
"entry": "main.js",
"zygisk": {
"id": "com.example.myzygiskmodule",
"name": "My Zygisk Module",
"version": "1.0.0",
"versionCode": 1,
"author": "Your Name",
"description": "A Zygisk module that injects Frida scripts",
"scope": "com.example.app1;com.example.app2"
}
}
}
```
### 使用 Fripack 开发 Frida 脚本
Fripack 支持用于开发的监视模式 (watch mode)，该模式无需重新构建整个包即可实现 JavaScript 文件的热重载。
#### 用法
开始监视一个目标：
```
fripack watch my-watch-target
```
监视进程将会：
1. 首先构建并安装目标。请注意，对于非 `xposed` 类型的目标，你需要手动安装目标。
2. 监视文件更改
3. 检测到更改时自动更新
4. 持续运行直到你按下 Ctrl+C
**注意**：监视模式需要安装 `adb` 并可在你的 PATH 中访问，以便将文件推送到 Android 设备并安装软件包。
#### 这是如何工作的？
在监视模式下，注入的 payload 会监视指定的路径，并在文件更改时触发重载。该路径通过 `pushPath` 设置，默认为 `/data/local/tmp/fripack_dev.js`。在 Android 平台上，fripack 还会监视 `entry` 文件，并在其被修改时自动将其推送到 `pushPath` 位置。在其他平台上，你可以设置自己的 `pushPath` 并在更改时手动复制文件，或者继续使用 `frida-server` 直接进行开发工作流。
## 备注
### 如何查看日志？
在 Android 上，日志通过 Android 日志系统输出，标签为 `FriPackInject`。你可以使用 adb 查看它们：
```
adb logcat FriPackInject:D *:S
```
在 Windows 上，日志会同时写入 `stdout` 和 Windows Debug Log。要查看它们，你可以：
- 将调试器附加到目标应用程序
- 在你的 Frida 脚本中使用 `AllocConsole` 和 `freopen`
- 在控制台中启动目标应用程序
- 使用 [DebugView](https://learn.microsoft.com/en-us/sysinternals/downloads/debugview) 监视全局系统日志
在其他平台上，日志会直接输出到 `stdout`。
### ReferenceError: 'Java' is not defined
从 Frida 17.0.0 开始，bridges 不再与 Frida 的 GumJS runtime 捆绑在一起。这意味着用户现在必须显式引入他们想要使用的 bridges。
你必须安装 bridge 并在打包前通过 `frida-compile` 构建你的脚本。查看 https://frida.re/docs/bridges/ 了解更多详情。
## 致谢
- [Frida](https://github.com/frida/frida)
- [Florida](https://github.com/Ylarod/Florida)
- [xmake](https://xmake.io/)
Frida 是一个强大的工具，但其庞大的体积以及对 root 权限的需求，使得向最终用户分发脚本变得具有挑战性。这通常限制了 Frida 在为更广泛受众开发插件方面的应用。
Fripack 解决了这个问题，它将你的 Frida 脚本打包成各种可执行格式——例如 Xposed Modules、修补过的 apk、用于 `LD_PRELOAD` 的共享对象或可注入的 DLL——从而实现了基于 Frida 的插件的轻松分发和使用。
### 二进制文件大小很重要
最初的 Frida 项目体积相当大。Fripack 对 Frida 进行了精简和压缩，使得在所有平台（Linux 除外）上的二进制输出文件都小于 10 MB。
### 一键构建
跨平台 Frida 脚本往往使得为不同目标构建交付物变得繁琐——即使使用 Frida Gadget 也是如此。Fripack 通过支持一次性为多个平台进行构建，简化了开发流程。
## 安装
从 [releases 页面](https://github.com/std-microblock/fripack/releases/latest) 下载最新的二进制文件，并根据需要进行安装。
如果你的电脑上已经安装了 Rust，你也可以使用 cargo 进行安装：
```
cargo install --git https://github.com/std-microblock/fripack/
```
## 快速入门
### 基本配置
Fripack 使用名为 `fripack.json` 的配置文件，该文件支持 JSON5 语法。以下是一个基本示例：
```
{
"xposed": {
"type": "xposed",
"version": "1.0.0",
"fridaVersion": "17.5.1",
"entry": "main.js",
"platform": "android-arm64",
"xposed": {
"packageName": "com.example.myxposedmodule",
"name": "My Xposed Module"
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
}
}
```
配置中的每个键代表一个构建目标。你可以使用以下命令构建所有目标：
```
fripack build
```
或者构建特定目标（例如 `xposed`）：
```
fripack build xposed
```
或者监视特定目标的更改：
```
fripack watch xposed
```
### 通用配置选项
以下选项适用于所有目标类型：
- `xz` (默认值: `false`): 使用 LZMA 压缩脚本。
- `entry` (必填): 要打包的入口点脚本。
- `fridaVersion` (必填): 要使用的 Frida 版本（必须为 17.5.1 或更高版本）。
- `outputDir` (默认值: `./fripack`): 构建产物的输出目录。
- `platform`: 目标平台 (例如 `android-arm64`, `windows-x86_64`)。
- 有效值: `android-arm32`, `android-arm64`, `android-x86`, `android-x64`, `windows-x64`, `linux-x64`
- `version`: 插件的版本。
- `type`: 目标的类型 (定义输出格式)。
- `inherit`: 要继承配置的另一个目标的键。
- `targetBaseName` (可选): 输出文件的基本名称 (默认为目标键)。
- `beforeBuild` (可选): 在构建目标之前执行的命令。
- `afterBuild` (可选): 在成功构建目标之后执行的命令。
- `watchPath` 监视文件更改的附加目录。
- `pushPath` : 在 `watch` 模式下将 JavaScript 文件推送到设备的目标路径。默认为 `/data/local/tmp/fripack_dev.js`。
使用继承来避免重复的示例：
```
{
"base": {
"version": "1.0.0",
"fridaVersion": "17.5.1",
"entry": "main.js",
"xz": true,
"outputDir": "./fripack",
"platform": "android-arm64"
},
"xposed": {
"inherit": "base",
"type": "xposed",
"xposed": {
"packageName": "com.example.myxposedmodule",
"name": "My Xposed Module"
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
},
"raw-so": {
"inherit": "base",
"type": "shared"
}
}
```
只有包含 `type` 字段的目标才会被构建。
### 支持的目标类型
#### `xposed`
将你的 Frida 脚本构建为 Xposed Module。仅支持 `Android` 平台。
**需要：** 系统中已安装 [`apktool`](https://apktool.org/)。
**附加选项：**
- `xposed` (必填): Xposed 配置对象。
- `packageName` (必填): Xposed 模块的包名。
- `name` (必填): 模块的显示名称。
- `icon` (可选): 模块图标的路径 (期望在同一目录下包含 `ic_launcher.webp` 和 `ic_launcher_round.webp`)。
- `scope` (可选): 模块的建议目标作用域。
- `description` (可选): 模块的描述。
- `sign` (可选): 签名配置。如果作为对象提供，APK 将被签名。
- `keystore`: keystore 的路径。
- `keystorePass`: keystore 密码。
- `keystoreAlias`: keystore 中的别名。
- `keyPass` (可选): 签名者私钥的密码。
#### `shared`
将你的 Frida 脚本构建为共享库 (`.so` / `.dll`)，可以通过各种方法加载 (例如 `LD_PRELOAD`)。
#### `inject-apk`
通过修改现有 APK 的一个原生库，将你的 Frida 脚本注入其中。仅支持 `Android` 平台。
**需要：** 系统中已安装 [`apktool`](https://apktool.org/)。
同时也建议在你的路径中包含 [`zipalign`](https://developer.android.com/tools/zipalign)。
**附加选项：**
- `injectApk` (必填): 注入配置对象。
- `sourceApkPath` (可选): 要注入的源 APK 文件路径。
- `sourceApkPackageName` (可选): 要从已连接设备中提取的 APK 包名。
- 必须提供 `sourceApkPath` 或 `sourceApkPackageName` 中的任意一个。
- 当使用 `sourceApkPackageName` 时，APK 将从已连接的设备中提取并缓存以供将来构建。这需要系统中安装 [`adb`](https://developer.android.com/studio/command-line/adb)。
- `injectMode` (可选): 注入模式。目前仅支持 `"NativeAddNeeded"`。
- `targetLib` (可选): 注入目标的特定原生库 (例如 `"libnative-lib.so"`)。
- 如果未指定，将按以下优先顺序搜索库：
1. `libCrashSight.so`, `libBugly.so`, `libmmkv.so` (白名单)
2. lib 目录中最小的 `.so` 文件 (会有警告)
- `sign` (可选): 最终 APK 的签名配置 (格式与 Xposed 相同)。
- `keystore`: keystore 的路径。
- `keystorePass`: keystore 密码。
- `keystoreAlias`: keystore 中的别名。
- `keyPass` (可选): 签名者私钥的密码。
**配置示例：**
```
{
"inject-apk": {
"type": "inject-apk",
"platform": "android-arm64",
"fridaVersion": "17.5.1",
"entry": "main.js",
"injectApk": {
"sourceApkPackageName": "com.example.app",
"injectMode": "NativeAddNeeded",
"targetLib": "libnative-lib.so",
},
"sign": {
"keystore": "./.android/debug.keystore",
"keystorePass": "android",
"keystoreAlias": "androiddebugkey"
}
}
}
```
#### `zygisk`
将你的 Frida 脚本构建为 Magisk 的 Zygisk 模块。仅支持 `Android` 平台。
**附加选项：**
- `zygisk` (必填): Zygisk 配置对象。
- `id` (必填): 模块 ID
- `name` (必填): 模块显示名称
- `version` (可选): 模块版本 (默认为 "1.0")。
- `versionCode` (可选): 模块版本代码 (默认为 1)。
- `author` (可选): 模块作者 (默认为 "FriPack")。
- `description` (可选): 模块描述。
- `scope` (必填): 注入的目标应用程序，用分号分隔。
**配置示例：**
```
{
"zygisk": {
"type": "zygisk",
"platform": "android-arm64",
"fridaVersion": "17.5.1",
"entry": "main.js",
"zygisk": {
"id": "com.example.myzygiskmodule",
"name": "My Zygisk Module",
"version": "1.0.0",
"versionCode": 1,
"author": "Your Name",
"description": "A Zygisk module that injects Frida scripts",
"scope": "com.example.app1;com.example.app2"
}
}
}
```
### 使用 Fripack 开发 Frida 脚本
Fripack 支持用于开发的监视模式 (watch mode)，该模式无需重新构建整个包即可实现 JavaScript 文件的热重载。
#### 用法
开始监视一个目标：
```
fripack watch my-watch-target
```
监视进程将会：
1. 首先构建并安装目标。请注意，对于非 `xposed` 类型的目标，你需要手动安装目标。
2. 监视文件更改
3. 检测到更改时自动更新
4. 持续运行直到你按下 Ctrl+C
**注意**：监视模式需要安装 `adb` 并可在你的 PATH 中访问，以便将文件推送到 Android 设备并安装软件包。
#### 这是如何工作的？
在监视模式下，注入的 payload 会监视指定的路径，并在文件更改时触发重载。该路径通过 `pushPath` 设置，默认为 `/data/local/tmp/fripack_dev.js`。在 Android 平台上，fripack 还会监视 `entry` 文件，并在其被修改时自动将其推送到 `pushPath` 位置。在其他平台上，你可以设置自己的 `pushPath` 并在更改时手动复制文件，或者继续使用 `frida-server` 直接进行开发工作流。
## 备注
### 如何查看日志？
在 Android 上，日志通过 Android 日志系统输出，标签为 `FriPackInject`。你可以使用 adb 查看它们：
```
adb logcat FriPackInject:D *:S
```
在 Windows 上，日志会同时写入 `stdout` 和 Windows Debug Log。要查看它们，你可以：
- 将调试器附加到目标应用程序
- 在你的 Frida 脚本中使用 `AllocConsole` 和 `freopen`
- 在控制台中启动目标应用程序
- 使用 [DebugView](https://learn.microsoft.com/en-us/sysinternals/downloads/debugview) 监视全局系统日志
在其他平台上，日志会直接输出到 `stdout`。
### ReferenceError: 'Java' is not defined
从 Frida 17.0.0 开始，bridges 不再与 Frida 的 GumJS runtime 捆绑在一起。这意味着用户现在必须显式引入他们想要使用的 bridges。
你必须安装 bridge 并在打包前通过 `frida-compile` 构建你的脚本。查看 https://frida.re/docs/bridges/ 了解更多详情。
## 致谢
- [Frida](https://github.com/frida/frida)
- [Florida](https://github.com/Ylarod/Florida)
- [xmake](https://xmake.io/)标签：Android安全, API接口, DLL注入, Docker支持, Frida, Gadget, iOS安全, LD_PRELOAD, Linux安全, Rust, XML 请求, Xposed模块, 二进制分析, 云安全运维, 云资产清单, 免Root, 动态二进制插桩, 可执行文件, 可视化界面, 安全开发, 打包工具, 流量审计, 灰色软件工具, 目录枚举, 移动安全, 网络安全, 网络流量审计, 脚本封装, 逆向工程, 通知系统, 隐私保护