Skip to content

About

A python tool to execute binary on devices running with harmony os.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

🚀 BinRunner — 鸿蒙OS二进制执行器

在 鸿蒙NEXT 零售机上,App 沙箱内 一切 execve 都被 SELinux 禁止(libs 目录、files 目录、 memfd + /proc/self/fd 全部实测 EACCES)。本工程采用与 Termony 同源的内存 ELF loader 方案:fork 子进程后在进程内把目标 ELF 读入匿名内存、用 HarmonyOS 特有的 jit prctl 放开匿名页可执行权限(debug 签名应用可用)、直接跳转入口 —— 完全不经过 execve。

已在零售版真机(非 root)验证:参数传递、stdout/stderr 捕获、退出码透传全部正常。

工作原理

PC: hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "hello foo bar"
        │
        ▼
EntryAbility (onCreate/onNewWant 解析 want.parameters.cmd)
        │
        ▼
napi_init.cpp: runBin → fork 子进程
        │  execv(libhello.so)                    ← 零售机必然 EACCES
        │  ↓ 失败回退
        │  memfd_create + 顺序复制 ELF            ← 关键:bundle libs 目录的文件
        │  │                                        随机读(lseek+read)会拿到坏数据,
        │  │                                        必须先顺序读进 memfd(实测坑)
        │  ↓
        │  z_entry(伪造初始栈)                     ← app/third_party/elf(MikhailProg/elf,
        │  │   mmap 匿名页 ← 读 ELF 段               已打 jit prctl 补丁 + "@fd" 直传补丁)
        │  │   prctl(0x6a6974) + mprotect PROT_EXEC ← debug 应用专属 jit 开关
        │  │   修正 auxv (AT_PHDR/AT_ENTRY/...)
        │  ↓
        │  z_trampo 跳转到目标入口                  ← 目标二进制开始运行
        ▼
父进程 poll 捕获 stdout/stderr,超时 SIGKILL
        │
        ▼
hilog (tag=BinRunner, 900 字符分段防截断)  →  PC: hdc shell hilog | grep BinRunner

使用步骤

0. 前置依赖

方案 A — DevEco Studio(推荐,含签名 + 全套工具链):

从 HarmonyOS 开发者官网 下载安装。 默认路径 /Applications/DevEco-Studio.app,自带 hdc / hvigor / ohpm / OHOS NDK。

方案 B — 仅 Command Line Tools(不需要 IDE,仅 CLI 操作):

从 HarmonyOS SDK 下载页 获取 Command Line Tools 压缩包,解压后配置环境变量:

# 以 macOS 为例,Linux/Windows 路径略有不同
export DEVECO_SDK_HOME="$HOME/harmonyos/sdk"
export PATH="$DEVECO_SDK_HOME/default/openharmony/toolchains:$DEVECO_SDK_HOME/default/openharmony/toolchains/hdc:$PATH"

验证:

hdc version     # 设备连接工具
which ohpm      # 包管理器
which hvigorw   # 构建工具

注意:仅 CLI 使用时只需要 hdc(br push/run/ls/logs 均通过 hdc 通信)。 如需构建安装 HAP,还需要 ohpm + hvigorw + OHOS NDK(或直接用 DevEco Studio)。

1. 签名

DevEco Studio 打开工程,File → Project Structure → Signing Configs → 自动签名。 必须是 debug 签名(jit prctl 只对 debug 应用开放)。

debug 签名 profile(.p7b)里内嵌了允许安装的设备 UDID 白名单:只有登记过的 手机才能安装本 HAP。DevEco 自动签名会把当前连接的设备 UDID 自动登记进 profile, 所以换新手机后必须重新自动签名 + 重新构建,详见 docs/device-onboarding.md。

仅 CLI 使用(不重新构建 App)时无需自己签名 —— 直接安装预编译的 binrunner/data/binrunner.hap 即可;但它同样受 profile 白名单限制, 只能装在与构建时同一批 UDID 已登记的设备上。

签名配置不入库:app/build-profile.json5 的 signingConfigs 含本机材料路径与 账号相关口令,仓库里只保留空数组,构建时注入:

  • DevEco Studio 自动签名会就地改写该文件 —— 那是你本机的配置,别提交;
  • 命令行用 ./build.sh:优先采用 .build/build-profile.local.json5(已 gitignore, 首次可从 DevEco 改写后的 app/build-profile.json5 复制一份存档),没有该文件时用 .build/keystore 的自签材料(p7b 为空,HAP 不可安装),构建结束自动还原受控文件;
  • CI/发布用 GitHub Secrets + hap-sign-tool 签名,不读本机配置。

2. 构建安装

# DevEco Studio 用户
export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH"
export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"

# Command Line Tools 用户(路径按实际安装位置调整)
# export DEVECO_SDK_HOME="$HOME/harmonyos/sdk"
# export PATH="$DEVECO_SDK_HOME/default/openharmony/toolchains:$DEVECO_SDK_HOME/default/openharmony/toolchains/hdc:$PATH"

ohpm install --all
hvigorw assembleApp --mode project -p product=default -p buildMode=debug --no-daemon
hdc install app/entry/build/default/outputs/default/entry-default-signed.hap

App 版本与 Python 包版本联动:HAP 的 versionName/versionCode 取自 binrunner/__init__.py 的 __version__(同一处也是 wheel 版本号唯一来源)。 build.sh 构建 HAP 前自动同步;手动构建时执行 python3 scripts/sync_app_version.py。versionCode 按 major*1_000_000 + minor*1_000 + patch 映射(1.0.0 → 1000000), 单调递增保证已安装设备可覆盖升级。

3. hdc 触发执行

hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "hello foo bar"
hdc shell hilog | grep BinRunner

注意:本机 aa 用 --ps 传字符串参数(不是 --es,不同系统版本参数名不同,报错时看 aa start -h)。 规则:cmd 第一个词是二进制名或绝对路径,其余为参数。 路径约定:@ 展开为 App 沙箱 files 根目录(/data/storage/el2/base/haps/entry/files, 仿 shell tilde 语义但用 @,避免 host shell 抢先展开:词首或 --opt=@/x 等号后生效, @foo 和参数中间的 @ 不展开);run/ls 等所有命令统一生效。 二进制名解析顺序:绝对路径直通 → 推送目录 @/bin/<名> → libs 目录 lib<名>.so。

4. 推送二进制并执行(host CLI,推荐)

/data/local/tmp 对 App 不可见(SELinux 隐藏为 ENOENT)、hdc file send 进不了 App 沙箱(shell uid 无权限)——两条直推路径在零售机上均实测不可行。可用通道是 App 内置的 TCP 推送 server(PushServer.ets, App 启动即监听 :8888),配合 hdc fport 把文件写入 filesDir/bin/。

binrunner 把转发管理、推送、触发执行、日志收集封装成 一条命令(零依赖,hdc 不在 PATH 时自动找 DevEco 默认路径):

alias br="python3 binrunner"          # 简短别名,推荐

br devices                                      # 列出设备(多台时 -t UDID 指定)
br push ./benchmark                             # 推送二进制(自动建立 fport,幂等)
br push ./libmindspore-lite.so                  # 动态依赖库推进同一目录
br push ./mylibs/                               # 递归推送目录(保持子目录结构)
br run "benchmark --modelFile=@/mobilenetv2.ms --loopCount=5"
br run --timeout 1800 "benchmark --modelFile=@/mobilenetv2.ms --loopCount=1000"
# → stdout/stderr 直接打印到本地终端,二进制退出码透传为 CLI 退出码
br ls                                           # 列出 files 根目录(bin/ 子目录是推送区;加路径可列任意目录)
br rm "old-binary"                               # 删除已推送的文件或目录(递归)
br pull "hello"                                  # 从设备拉取文件到本地
br logs                                         # 持续跟踪设备日志

br run --timeout 设置设备端执行期限(默认 60 秒,范围 1–2147483647 整数秒); 主机从启动请求返回后最多等待该期限加 30 秒,用于启动、调度和报告回传。 例如 --timeout 1800 允许设备执行 1800 秒,主机等待上限为 1830 秒。 报告包含实际执行期限,如 exit=-1 timedOut=true timeoutSec=1800。 主机等待报告超时只表示未收到完整报告。v1.4.1 起 CLI 会先探测设备是否已结束:能确定时直接报 「输出数据不完整(收到连续 X/Y 块):设备已结束,缺失部分无法通过 hilog 补齐」, 不确定时才提示设备状态未知。 此修复需要同时更新 CLI 和设备 HAP;仅更新 CLI 时,旧 v1.2.0 HAP 仍会在 30 秒终止任务。 从源码构建后请安装新 HAP(使用打包的 CLI 时执行 br setup --reinstall)。 直接使用 aa start 时可加 --ps timeout_sec 1800;未传入时(包括页面执行)保留 30 秒默认值。

持久化(追加到 ~/.zshrc 或 ~/.bashrc):

echo 'alias br="python3 '"$(pwd)"'/binrunner"' >> ~/.zshrc
  • @ 统一展开为沙箱 files 根目录(run/ls 均生效);命令名给绝对路径也可直接执行, 如 br run "@/bin/hello a b"
  • 名字解析顺序:绝对路径直通 → @/bin/<name>(推送目录优先) → libs 目录 lib<name>.so
  • 推送支持子目录(PushServer 自动创建父目录),目录推送示例:
    br push ./mylibs/                  # 保持子目录结构,如 mylibs/sub/dep.so → bin/sub/dep.so
    用 br ls "@/bin" 查看已推送的文件树。
  • 注意:LD_LIBRARY_PATH 仅含 filesDir/bin/ 根目录(不递归搜索子目录),.so 依赖 请直接放在根层级;子目录适合放数据文件(模型、配置等)
  • 推送目录的文件是普通文件,没有 bundle libs 目录的随机读坏数据问题;loader 同样先过 memfd
  • 数据文件也可通过子目录组织:@/bin/models/xxx.ms、@/bin/configs/yy.json
  • 断点续传:≥4MiB 的文件中断后重跑同一条 br push 会自动续传,只发剩余部分 (靠头部 4KiB 探针确认同一文件;传输期间用 .part 临时名,收满才改成正式名, 所以正式文件名不会指向半成品)。已实测 32MiB 传到 69% 强杀后续传,哈希与源文件一致。
  • 长传保活:br push 期间自动点亮屏幕 + 巡检 fport 隧道,熄屏挂起 / 隧道被回收 导致的中断会自动自愈续传(详见 §7.2 与 docs/transfer-spec.md §传输可靠性)
  • 不想用 CLI 时等价的手工步骤:hdc fport tcp:8888 tcp:8888 + python3 binrunner push <file或目录> + aa start --ps cmd ... + hilog | grep BinRunner

已实测:推送静态 hello 执行 exit=42 正常;推送 benchmark + libmindspore-lite.so 免打包 完成 MobileNetV2 推理(AvgRunTime ≈35ms,与打包版一致);CLI 推送/执行/日志重组/退出码 透传全部验证通过。

5. 多终端并发执行

BinRunner 支持多个终端同时 br run,各次执行互不干扰:

终端1: br run "hello"           ──→ 子进程 456
终端2: br run "benchmark ..."   ──→ 子进程 789
终端3: br push ./data/          ──→ PushServer TCP 连接

每个 br run 生成唯一 8 位 run_id(如 a1b2c3d4),所有 hilog 输出
带 [a1b2c3d4] 前缀,CLI 只认自己的 ID,输出互不混杂。
PushServer(TCP :8888)天然支持多连接并发。
  • 进程隔离:每条 br run 独立 fork 子进程,各自运行目标二进制,互不影响
  • 流式输出:新版 CLI 与 App 配合使用时,br run 在任务执行期间持续显示 stdout/stderr, 分别写入 Host 的标准输出/标准错误并立即刷新;启动后按 0.5 秒间隔轮询(另加 hdc 耗时), 轮询只读本 App tag 下本次执行的行(hilog -x -T BinRunner -e '\[run_id\]'), 设备整体日志量和历史执行都不会拖慢本轮。 结束时仅在 stderr 打印退出状态,不重复打印日志。目标程序需主动刷新自身缓冲区 (例如 C 的 fflush(stdout) 或 Python 的 -u);BinRunner 无法读取尚未写入管道的数据。 旧版 App 仍使用执行结束后的完整报告。协议与限制见 CLI 文档。
  • 输出隔离:自动生成的 run_id 标记所有日志行,CLI 自动过滤
  • Push 并发:多个 br push 可同时进行,同名文件后写覆盖
  • 详见 docs/concurrency-spec.md

6. 接入自己的二进制(打包方式,静态 / 动态均可)

# 静态(最简单):OHOS NDK 交叉编译时加 -static,参考 examples/hello/build.sh
# 动态(已实测 mindspore benchmark):二进制和它的 .so 依赖一起放进 libs 目录
  • 目标二进制重命名为 lib<名字>.so 放入 app/entry/libs/arm64-v8a/
  • 动态二进制的依赖库(如 libmindspore-lite.so)放入同一目录;子进程已自动设置 LD_LIBRARY_PATH 指向该目录,musl ld.so 会沿它解析 NEEDED 依赖
  • 动态链接器 /lib/ld-musl-aarch64.so.1 由 loader 自动加载(App 可读系统 ld-musl,已实测)
  • 重新打包安装即可

7. 数据文件(模型等)通路

/data/local/tmp App 读不到(SELinux),数据文件三条路。

7.1 rawfile 打包(本工程示范)

放 app/entry/src/main/resources/rawfile/,App 启动时自动释放到 filesDir, cmd 里用 @/xxx 引用。

7.2 推送通道(适合大文件/频繁更换)

br push model.ms,用 @/bin/model.ms 引用。

单文件上限 4GiB(策略护栏,双端常量一致;决策见 ADR-0001), 设备剩余空间不足会在写盘中报错并清理 .part。

⚠️ 已知坑:屏幕熄灭后 App 进后台,PushServer 的 8888 监听会被系统挂起, br push 表现为「连接建立但无响应 / 中途 Connection refused」;hdc fport 隧道 也可能被系统回收但本地端口仍被残留进程占用。已由 CLI 保活线程 + App 前台常亮 双保险缓解,详见 docs/transfer-spec.md §传输可靠性。

7.3 自建 socket 交互

App 起 server,hdc fport 后 PC 直连(见扩展方向)。

8. 实测:MindSpore Lite 模型推理(已跑通)

br run "benchmark --modelFile=@/mobilenetv2.ms --loopCount=5 --warmUpLoopCount=1"

真机输出(零售版非 root 手机,CPU 2 线程):

Model = mobilenetv2.ms, NumThreads = 2, MinRunTime = 24.259 ms,
MaxRuntime = 40.460 ms, AvgRunTime = 29.849 ms
Run Benchmark mobilenetv2.ms Success.

集成方式:benchmark 重命名为 libbenchmark.so + libmindspore-lite.so 直接放入 app/entry/libs/arm64-v8a/,模型 mobilenetv2.ms 放 rawfile(本仓库均已内置)。

真机实测结论(都是踩坑换来的)

路径 结果
hdc shell 执行 /data/local/tmp 二进制 ❌ SELinux 拒绝(shell 域)
App execv libs 目录的 .so ❌ EACCES(noexec)
App execv files 沙箱目录 ❌ EACCES(noexec)
App execv memfd + /proc/self/fd ❌ EACCES(SELinux 拒匿名 inode exec)
App 读 /data/local/tmp ❌ SELinux(对 App 隐藏,opendir 报 ENOENT)
hdc file send 到 App 沙箱 files 目录 ❌ permission denied(shell uid 无权限,dir 0700 属 App uid)
hdc fport + PushServer 推送二进制到 filesDir/bin 执行 ✅ 已实测(静态 hello、动态 benchmark + libmindspore-lite.so 免打包跑通)
App 读 /lib/ld-musl-aarch64.so.1 ✅ 可读(动态链接前提)
App 对任意文件 mmap PROT_EXEC ❌ EACCES(dlopen 能工作是系统加载器的特权通道)
hnp 包安装(module.json5 hnpPackages) ❌ 手机零售版无效:App 命名空间里根本没有 /data/app、/data/service/hnp(该机制只在鸿蒙 PC 有效)
内存 ELF loader + jit prctl(debug 签名) ✅ 唯一可行
静态链接二进制(musl -static) ✅ 稳定
动态链接二进制 + ld.so 加载 .so 依赖 ✅ 已实测(mindspore benchmark + libmindspore-lite.so)
模型推理(MobileNetV2) ✅ 已实测(AvgRunTime 29.8ms)
bundle libs 目录文件随机读(lseek+read) ⚠️ 拿到坏数据导致 SIGSEGV;顺序读正常 → 必须先复制进 memfd
App 内访问 /proc/self/fd/N ❌ 不可访问 → loader 打补丁支持 "@fd" 直传已打开 fd
伪造栈贴近映射段底部 ⚠️ ld.so 压栈越界,无规律 SIGSEGV(.bss 布局随构建漂移)→ 栈块必须放大缓冲区高位
auxv 缺 AT_BASE / AT_EXECFN ⚠️ musl ld.so 误判为"被直接调用"走错路径 → 必须给占位项让 loader 改写

调试命令

# probe:枚举关键目录到 hilog,排查路径问题
hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "probe"

# probe2:动态链接可行性检测(/data/local/tmp 可读性、ld-musl 可读性、各目录 exec-mmap)
hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "probe2"

已知限制

  • hilog 通道带宽:stdout/stderr 通过 hilog 回传,单条日志约 1000 字符上限。流式数据每块最多 400 字节, 十六进制编码后发送(2.2 倍膨胀),块间加微延迟降低 socket 溢出风险。真机实测 USB 链路约 325KB/s, 持续高速输出(单次 ≥ 约 1MB)会超过该上限;CLI 检查序号与总块数,确认设备已结束且缺块不可补齐后 立即报错并给出收到/应有块数(不再空等到 --timeout),已经显示的输出保留。 大输出场景建议拆小单次输出量,或等后续版本扩展 TCP/文件回传
  • CPU 推理正常;GPU/NPU 推理未实测——限制在 MindSpore Lite 尚未适配鸿蒙 OS 的 GPU/NPU 驱动(benchmark 只能走 CPU),而非 BinRunner:沙箱内二进制可 dlopen 系统 GPU/NPU 驱动库,BinRunner 不限制驱动访问
  • 熄屏挂起 PushServer:屏幕熄灭后 App 进后台,8888 监听被系统挂起,长传会中断。 br push 已内置保活 + 自愈(见 §7.2),App 前台也保持常亮,双保险
  • 二进制以 App uid 运行,受 App 沙箱约束(访问不了其他应用数据等)
  • seccomp 存在(Termony 实测 setuid/setgid 会被杀),避免在用例里调用特权 syscall

扩展方向

  • TCP 回传:App 起 socket server,hdc fport tcp:8889 tcp:8889(8888 已被 PushServer 占用),适合大输出/交互式用例
  • 批量用例:cmd 传用例名,App 内查表执行并汇总 exit code;PC 脚本批量驱动
  • busybox 整套工具:静态编译 busybox 为 libbusybox.so,cmd 形式 busybox ls -l (libbusybox.so 内部按 argv[0]/argv[1] 分发 applet)
  • br shell:交互式 shell,持续输入命令到同一 App 实例
  • LD_LIBRARY_PATH 递归子目录:动态链接器自动搜索 filesDir/bin/ 的子目录
  • LD_LIBRARY_PATH 递归子目录:动态链接器自动搜索 filesDir/bin/ 的子目录

About

A python tool to execute binary on devices running with harmony os.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages