sukinject

sukinject 是一个面向 Linux / Android arm64 的跨进程 hook / 注入框架。 它通过内核模块和 /proc/sukinject transport 对目标进程安装 DBI hook， 公开语义是：

target -> replacement -> origin

• target：目标进程内的函数地址
• replacement：目标进程地址空间内的代码入口，或由 sukinject 生成的 ABI wrapper
• origin：目标进程内可回调原函数的 trampoline

调用方进程里的普通 C 函数指针不能直接作为跨进程 replacement。

当前版本是 0.1.2。项目依赖 root 权限和匹配目标内核的模块构建环境， 请只在你拥有授权的设备、进程和环境中使用。

• 跨进程 hook：通过 /proc/sukinject 下发 hook / unhook
• DBI 整页重编译：执行走 ghost / shadow 页，避免直接改写原始页字节
• origin 语义：generated wrapper 可调用原函数并改写返回值
• 符号解析：sukctl 支持 pid + module + symbol 或 pid + module + offset
• 公开 C API：include/sukinject.h（SukInject*，含 options.backend 扩展后端），产物 lib/libsukinject.a
• CLI：tools/sukctl（resolve / dbi-hook / dbi-unhook / status / dbi-check，以及实验性 bp-hook / ptr-hook / pfn-hook）
• Agent 入口替换：tools/sukagentctl 将受限 ELF / package 装入目标并绑定 hook

• 主线目标：arm64 / AArch64。Android compat32 会 fail closed。
• 不是 Dobby 兼容后端，也不是同进程 inline hook 库。
• replacement 必须位于目标进程地址空间，或使用当前支持的 generated ABI wrapper。
• 需要 root + 与设备内核匹配的 suk_step4.ko。
• 完整动态链接器 / C++ runtime / 任意语言 runtime 不在当前范围。

include/          公开头文件
lib/              sukinject 静态库
tools/            sukctl、sukagentctl 等用户态工具
runtime/dbi/      DBI 重编译核心
runtime/kmod/     内核模块
runtime/agent/    agent 示例源码
runtime/target/   示例目标程序
docs/             使用与 API 文档

静态库：

make -C lib clean all

命令行工具：

make -C tools clean all

内核模块（需要目标内核的 build 目录）：

make -C runtime/kmod KDIR=/path/to/kernel/build

加载内核模块后确认 proc 入口：

echo status | sudo tee /proc/sukinject >/dev/null
sudo cat /proc/sukinject

解析符号：

sudo tools/sukctl --allow \
  -p <pid> \
  --module <module-or-exe> \
  --symbol <symbol> \
  resolve

安装 generated wrapper（调用原函数后对整数返回值加 7）：

sudo tools/sukctl --allow \
  -P /proc/sukinject \
  -p <pid> \
  --module <module-or-exe> \
  --symbol <symbol> \
  --origin-add 7 \
  dbi-hook

查看状态：

sudo tools/sukctl -P /proc/sukinject status

卸载 hook（建议先停住目标线程）：

sudo tools/sukctl --allow \
  -P /proc/sukinject \
  --stop \
  -p <pid> \
  --module <module-or-exe> \
  --symbol <symbol> \
  dbi-unhook

tools/sukctl --abi int-origin-add:7 abi-plan

sudo tools/sukctl --allow -p <pid> -f <func_va> --ret-imm 1234 dbi-hook
sudo tools/sukctl --allow -p <pid> --module exe --symbol compute_value --origin-add 7 dbi-hook
sudo tools/sukctl --allow -p <pid> --module libtarget.so --offset 0x1234 --ret-imm 1 dbi-hook
sudo tools/sukctl --allow --stop -p <pid> -f <func_va> dbi-unhook

常见 ABI wrapper：

• int-ret-imm:<n>：直接返回小整数
• int-origin-add:<n>：调用 origin 后对整数返回值加 n
• write-origin-ret / write-ret / read-eof
• double-ret-zero / double-origin-add:<delta>

也可用 --abi-intent / --abi-signature 做签名校验后的计划选择。

接口总览：docs/public-interfaces.md
库用法：docs/library-guide.md · API 参考：docs/api-reference.md
Agent：docs/agent-guide.md · CLI：docs/cli-reference.md

#include <stdint.h>
#include "sukinject.h"

int install_hook(int pid, void *target, void **origin_out)
{
    SukInjectOptions options = SukInjectOptionsDefault();
    SukInjectInstallResult result;
    SukInjectRequest req;
    char reason[256];

    options.abi = "int-origin-add:7";

    req.pid = pid;
    req.target = target;
    req.replacement = 0;
    req.origin = origin_out;
    req.options = options;

    return SukInjectHook(&req, &result, reason, sizeof(reason));
}

SukInjectHook 默认走 /proc/sukinject。自定义 transport 可用 SukInjectHookWithTransport / SukInjectHookPlanWithTransport。

设备端需要：

• root / su
• 已构建并可加载的 suk_step4.ko（与设备内核匹配）
• adb
• 对应架构的 Android NDK clang

推荐阅读：

• docs/public-interfaces.md — 全部对外接口
• docs/agent-guide.md — agent 用法
• docs/agent-android-quickstart.md — Android 逐步命令
• docs/cli-reference.md — 命令行参考

从这里开始： docs/public-interfaces.md

GNU General Public License v2.0，见 LICENSE。