phantom-frida

phantom-frida 从源码构建 Android Frida Server 和 Gadget，同时更改一组有针对性的可观察运行时标识符。它是一个构建与验证框架，而非承诺能击败所有特定于应用的检测方法。

当前兼容目标为 Android 上的 Frida 17.16.4。其他 Frida 版本在源代码合约、完整构建和已 root 设备验收流程被重复验证之前，均有意视为未经核实。

请仅将本项目用于你拥有或获授权测试的应用和设备。

已验证内容

仓库区分三类证据：

1. 单元测试与夹具测试验证输入处理、精确的 Frida 17.16.4 源码补丁合约、DEX 重建、产物提升、元数据、工作流及失败行为。
2. build.py --verify 要求同时具备 Server 与 Gadget，剥离暂存阶段的 Gadget，并在发布任一产物之前拒绝已知的禁止运行时标记。
3. scripts/android_smoke.py 在一台已 root 设备上实测构建产物：认证的抽象 UNIX 传输、原版客户端 RPC、spawn、attach、Java bridge 断言、/proc 检查、外部 root 内存扫描，以及单独加载的 Gadget。

源码测试或字节扫描通过并不等同于运行时隐身。关于 Android 行为的声明应附带生成的、经脱敏的冒烟测试报告。

使用 GitHub Actions 构建

从 Actions 标签页运行 Build Custom Frida。该可复用构建工作流：

• 校验所有用户可控的构建输入；
• 从 Google 下载 Android NDK r29 并核对其已发布的校验和；
• 克隆全新的上游源码树，而不是缓存已打补丁的源码；
• 剥离 Gadget 符号，并且仅当硬产物与标记门禁全部通过后才上传；
• 将 build-info.json 与 SHA256SUMS 包含在同一个构建产物中。

每周工作流通过经过认证的 GitHub API 解析最新版本，调用同一只读构建工作流，验证下载的产物，对其进行证明，并且仅向最终任务授予发布写入权限。

本地构建

要求：

• Ubuntu 22.04 或更新版本（支持 WSL）；
• Python 3.10 或更新版本；
• Git、curl、unzip、C/C++ 工具链、JDK 17，以及 Node.js 18 或更新版本（CI 使用 Node.js 24.13.1）；
• 包含 android.jar 与 D8 的 Android SDK platform 与 build-tools；
• 约 20 GB 可用磁盘空间。

如果省略 --ndk-path，构建器会将 Android NDK r29 下载到 build/ 下。一个经过核验的固定输入 arm64 构建示例如下：

export ANDROID_SDK_ROOT=/path/to/Android/Sdk
python3 build.py \
  --version 17.16.4 \
  --name oemcodec \
  --arch android-arm64 \
  --port 27142 \
  --extended \
  --strict-wx \
  --verify

实用选项：

--version, -v    Exact Frida semantic version (required)
--name, -n       Lowercase replacement name, 3-20 characters
--arch, -a       One or more supported Android architectures
--port, -p       Listening port; omitted keeps 27042
--extended, -e   Apply the optional extended identifier transformations
--strict-wx      Harden Frida-owned persistent anonymous RWX mappings on Android
--temp-fixes     Apply opt-in, device-specific stability changes
--verify         Reject known forbidden markers in final artifacts
--skip-build     Patch source without compiling
--skip-clone     Use an existing source tree in the work directory
--ndk-path       Use an existing Android NDK r29 directory

输出与出处

对于上述示例，output/ 包含：

oemcodec-server-17.16.4-android-arm64
oemcodec-server-17.16.4-android-arm64.gz
oemcodec-gadget-17.16.4-android-arm64.so
oemcodec-gadget-17.16.4-android-arm64.so.gz
build-info.json
SHA256SUMS

build-info.json 记录构建器、Frida 与 frida-core 的精确提交、NDK 版本、UTC 构建时间、架构、名称、端口、严格 W^X 代码池模式，以及在 Actions 中构建时的工作流 URL。使用前请先验证下载的二进制文件：

cd output
sha256sum --check SHA256SUMS
python3 -m json.tool build-info.json >/dev/null

公开的每周发布还会获得 GitHub 构建来源证明。SHA256SUMS 标识一组输出；不同构建主机上的二进制哈希并不预期一致。

原版客户端兼容性

构建器保留 re.frida.* 下的 D-Bus 协议接口、/re/frida/GadgetSession 路径、公开的大写 Frida JavaScript API 字符串，以及原版客户端所需的生成 C ABI 符号。重命名这些值会破坏正常的 Frida 客户端/服务器合约。

D-Bus 服务标识符、helper JNI 包、zymbiote 套接字前缀、选定的进程/库/路径标识符、选定的线程名称以及可选的自定义端口，是构建器可以转换的独立实现细节。输出验证器会拒绝以下显式标记集合：

frida\0
frida-zymbiote
re/frida/HelperBackend
frida-server
frida-helper
frida-agent
frida-gadget
frida-eternal-agent
frida-generate-certificate
frida-main-loop
frida:rpc
FridaScriptEngine
GLib-GIO
GDBusProxy
GumScript
Frida/
gum-js-loop
gmain\0
gdbus\0
pool-frida
pool-spawner
jit-cache\0

确切的公共 API 字符串 Frida\0 以及白名单中的 re.frida.* 协议标识符会被有意保留。HTTP/Inspector 前缀 Frida/ 属于验证器失败项，会被独立重命名。

已 root 的 Android 验收

安装 build-info.json 中记录的精确 Python 绑定，安装固定版本的 Java bridge 依赖，并仅连接一台已 root 的 Android 设备：

python3 -m pip install "frida==17.16.4" frida-tools
npm ci --ignore-scripts

python3 scripts/android_smoke.py \
  --server output/oemcodec-server-17.16.4-android-arm64 \
  --gadget output/oemcodec-gadget-17.16.4-android-arm64.so \
  --name oemcodec \
  --port 27142 \
  --package com.example.app \
  --ndk build/android-ndk-r29 \
  --report android-smoke-report.json

该包必须是一个已安装的 Java 应用，并且你获授权对其进行测试。测试框架使用 Frida 17 所要求的显式 frida-java-bridge 编译 test_comprehensive.js。Server 与 Gadget 各自监听一个随机的、经过认证的抽象 UNIX 套接字；它们的主机 TCP 端口仅以 ADB 转发形式存在，设备上不暴露任何 TCP 监听器。测试框架还会编译一个与 ABI 匹配的 root 探测程序，通过 /proc/<pid>/mem 在 Frida 自身进程视图之外扫描已映射的 agent 与 Gadget 镜像。退出时会清理其进程、转发和远程测试目录。/proc 门禁同样拒绝旧版 linjector 文件描述符名称以及非零的 TracerPid。

Frida Gadget 配置必须与库同目录命名，即 lib<name>-gadget.config.so；测试框架会生成并部署该文件。

开发检查

python -m pip install --requirement requirements-dev.txt
npm ci --ignore-scripts
python -m pytest
ruff check .
ruff format --check .
mypy build.py patches.py namegen.py scripts
node --check test_comprehensive.js
bash -n build-wsl.sh
go run github.com/rhysd/actionlint/cmd/[email protected]

完整的证据要求参见 CONTRIBUTING.md。

仓库结构

build.py                 Clone, patch, compile, verify, and collect artifacts
patches.py               Source and same-length binary transformations
namegen.py               Seeded build-name and port generation
scripts/android_smoke.py Rooted Android Server/Gadget acceptance harness
test_comprehensive.js    Structured Frida 17 Java bridge assertions
tests/                   Unit, contract, fixture, and workflow tests
.github/workflows/       CI, CodeQL, reusable build, and release isolation

已知边界

• 目前仅以 Frida 17.16.4 作为验证目标；不推断对所有 17.x 或 16.x 版本的支持。
• --temp-fixes 会改变运行时行为，仍为可选启用。
• 标记缺失并不证明能抵御行为、完整性、时序或特定于应用的检测。
• 原版客户端兼容性保留公开的 ABI/协议行为。主动协议探测与代码完整性检查仍可能识别出插桩。
• 本构建器不会隐藏 root、自动化应用启动、Interceptor 代码改动、用户脚本字符串，或远程证明所报告的任何失败。
• --strict-wx 将 Android injector 的可执行代码与可写数据和栈页分离，禁用 Gum 的持久 RWX 代码池，将 GumJS NativeCallback 闭包代码置于专用 RX 页上，同时保持 libffi 存储为 RW，并将新生成的代码最终确定为 RX。如果找不到匹配的远程 libc，Android injector 会失败关闭（fail closed），而不是使用其上游的 RWX 回退方案。它会保留原本就是 RWX 的页面，并且不会拒绝用户脚本显式请求的 RWX 内存。运行时 /proc/maps 样本并不能证明在修补可执行代码期间不会发生瞬时的 RWX 权限变化。
• 外部内存门禁针对其显式标记集合扫描已映射的 agent/Gadget 镜像；它并非对每个匿名堆页的通用扫描。
• Frida 17 原始 agent 需要显式导入或捆绑 bridge。该测试框架使用 frida.Compiler；Frida REPL 与 tracer 自带捆绑的 bridge。

致谢与许可

• Frida：Ole André Ravnas 及贡献者
• ajeossida：hackcatml

构建器代码采用 MIT 许可。生成的二进制文件保留上游许可；参见 THIRD_PARTY_NOTICES.md。