### Common RustFrida Workflows

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Examples of common RustFrida workflows, including injecting into running processes, spawning applications, and entering an interactive session.

```bash
# 已运行的进程
./rustfrida --pid <pid> -l script.js

# 从启动阶段注入，适合抓 Application / ClassLoader 初始化
./rustfrida --spawn com.example.app -l script.js

# 先进入交互，再手动 loadjs / jseval
./rustfrida --pid <pid>
```

--------------------------------

### Remote Call Example with curl

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Demonstrates how to forward a local port and use `curl` to make RPC calls to a RustFrida script running with `--rpc-port`. This is a common way to interact with persistent agents.

```bash
adb forward tcp:9191 tcp:9191
./rustfrida --pid <pid> -l script.js --rpc-port 9191
curl -X POST http://127.0.0.1:9191/rpc/0/ping
```

--------------------------------

### Successful Validation Output Example

Source: https://github.com/kkkbbb/rustfrida/blob/master/doc/managed-dsl.md

Example of successful route stats output indicating zero orig-bypass hits and no failures. The exact counts may vary.

```text
managed=354184,orig=0,set=0,fail=0,active=0,backup=0

```

--------------------------------

### Documentation Structure Hierarchy

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/COMPLETION-REPORT.md

Illustrates the hierarchical organization of the generated rustfrida documentation, starting from the main README.md and branching out to specific module documentation files.

```markdown
README.md（总览）
├── api-architecture.md（架构）
├── command-line-interface.md（CLI）
├── javascript-api.md（JS API）
├── java-hook-api.md（Java 操作）
├── jni-api.md（JNI 访问）
├── http-rpc-api.md（RPC 服务）
├── process-and-injection.md（注入机制）
├── types-and-structures.md（类型定义）
└── build-and-configuration.md（构建）
```

--------------------------------

### Hook Java Method and Call Original Implementation

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of hooking a Java method, logging its arguments, and then calling the original implementation using `$orig()`. This is useful for observing behavior while maintaining original functionality.

```javascript
Java.ready(function() {
    var Log = Java.use("android.util.Log");

    Log.i.overload("java.lang.String", "java.lang.String").impl = function(tag, msg) {
        console.log("[Log.i]", tag, msg);
        return this.$orig(tag, msg);
    };
});
```

--------------------------------

### Basic HashMap put Hook with Managed DSL

Source: https://github.com/kkkbbb/rustfrida/blob/master/doc/managed-dsl.md

Demonstrates hooking the `put` method of `java.util.HashMap` using the Managed DSL. It compiles the hook logic into a dex helper for high-frequency scenarios. Ensure `Java.ready` is used to wrap the hook setup.

```javascript
Java.ready(function () {
  Java.compileMethod(
    "java.util.HashMap",
    "put",
    "(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;",
    "auto"
  );

  Java._resetArtRouteStats();

  Java.managedHookDsl({
    className: "java.util.HashMap",
    methodName: "put",
    signature: "(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;",
    dsl:
      "let n: int = this.size();" +
      "let plus: int = n + 1;" +
      "let sb: java.lang.StringBuilder = java.lang.StringBuilder.$new(\"seed\");" +
      "if (arg0 instanceof java.lang.String) {" +
      "  let keyLen: int = (arg0 as java.lang.String).length();" +
      "  sb.append(arg0);" +
      "}" +
      "new int[](3);" +
      "let a: int[] = last;" +
      "a[0] = plus;" +
      "if (plus > 0) {" +
      "  return orig(arg0, arg1);" +
      "} else {" +
      "  return orig(arg0, arg1);" +
      "}"
  });
});
```

--------------------------------

### GET /sessions

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Lists all active sessions. The response format differs slightly between legacy and server modes.

```APIDOC
## GET /sessions

### Description
Lists all active sessions. The response format may vary depending on the operating mode (legacy vs. server).

### Method
GET

### Endpoint
/sessions

### Response
#### Success Response (200)
- **id** (integer) - The session identifier.
- **pid** (integer) - The Process ID (PID) of the target process.
- **label** (string) - A display label for the session (e.g., "PID:1234" or package name).
- **status** (string) - The connection status of the session (e.g., "connected", "disconnected").

#### Response Example (Legacy Mode)
```json
[
  {
    "id": 0,
    "pid": 1234,
    "label": "PID:1234",
    "status": "connected"
  }
]
```

#### Response Example (Server Mode)
```json
[
  { "id": 0, "pid": 2000, "label": "...", "status": "connected" },
  { "id": 1, "pid": 2001, "label": "...", "status": "connected" },
  { "id": 2, "pid": 2002, "label": "...", "status": "disconnected" }
]
```
```

--------------------------------

### Get Java Class Reference

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Use `Java.use` to obtain a wrapper for a Java class. This wrapper allows access to static methods, fields, and constructors.

```javascript
var Activity = Java.use("android.app.Activity");
var Log = Java.use("android.util.Log");
var String = Java.use("java.lang.String");
```

--------------------------------

### Call RPC Exported Method (No Arguments)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Invoke an exported RPC method on a specific session using POST /rpc/<session>/<method>. This example shows calling a method without any arguments.

```bash
# 无参数
curl -X POST http://127.0.0.1:9191/rpc/0/ping
```

--------------------------------

### GET /

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Health check endpoint for the RPC API. Returns a simple JSON object indicating the service is running.

```APIDOC
## GET /

### Description
Health check endpoint. Returns a JSON object indicating the service is operational.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is healthy.
- **message** (string) - A message from the service, typically "rustfrida-rpc".

#### Response Example
```json
{
  "ok": true,
  "message": "rustfrida-rpc"
}
```
```

--------------------------------

### Hook Native Function and Modify Arguments

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of hooking the native 'open' function in libc.so. It reads the path argument, logs it, and replaces it with a fake path if it matches '/proc/self/maps'. This demonstrates modifying arguments before the original function is called.

```javascript
var open = Module.findExportByName("libc.so", "open");

Interceptor.attach(open, {
    onEnter(args) {
        var path = args[0].readCString();
        console.log("open", path);

        if (path.indexOf("/proc/self/maps") >= 0) {
            args[0] = Memory.allocUtf8String("/data/local/tmp/fake_maps");
        }
    }
});
```

--------------------------------

### List Sessions Endpoint

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Use the GET /sessions endpoint to retrieve a list of all active and disconnected sessions. The response format differs between legacy and server modes.

```bash
curl http://127.0.0.1:9191/sessions
```

--------------------------------

### Environment Variables for Android NDK and Clang

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Set environment variables for the Android NDK and clang toolchain. Ensure ANDROID_NDK_HOME points to your NDK installation and add the clang binary path to your system's PATH.

```bash
export ANDROID_NDK_HOME=~/Android/Sdk/ndk/25.1.8937393

export CLANG_PATH=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin
export PATH=$CLANG_PATH:$PATH

```

--------------------------------

### Expose Script Capabilities via RPC

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of defining exported functions using `rpc.exports` in a RustFrida script. These functions can be called remotely from a host process, enabling tools or UIs to trigger script functionality.

```javascript
rpc.exports = {
    ping: function() { return "pong"; },
    app: function() {
        var ActivityThread = Java.use("android.app.ActivityThread");
        var app = ActivityThread.currentApplication();
        return String(app.getPackageName());
    }
};

```

--------------------------------

### Hook Java Method and Modify Return Value

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of hooking a Java method to log arguments and directly return true, bypassing the original implementation. Ensure this code is placed within `Java.ready()` for spawn mode.

```javascript
Java.ready(function() {
    var Login = Java.use("com.example.LoginManager");

    Login.checkPassword.impl = function(user, pass) {
        console.log("checkPassword", user, pass);
        return true;              // 直接改返回值，不调原方法
    };
});
```

--------------------------------

### Cargo Configuration for Android Cross-Compilation

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Configure Cargo for aarch64-linux-android target, specifying the linker and archiver. This setup is crucial for cross-compiling Rust code for Android devices.

```toml
[target.aarch64-linux-android]
linker = "aarch64-linux-android-clang"
ar = "aarch64-linux-android-ar"
rustflags = [
    "-C", "link-arg=--target=aarch64-linux-android31",
]

[build]
target = "aarch64-linux-android"

```

--------------------------------

### Conditionally Call Original Native Function

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example using the `hook()` function to conditionally call the original native 'getpid' function or return a fixed value. This allows for dynamic control over whether the original function executes.

```javascript
var getpid = Module.findExportByName("libc.so", "getpid");

hook(getpid, function() {
    if (Date.now() & 1) {
        return this.$orig();    // 调原函数，参数默认来自当前寄存器
    }
    return 12345;               // 跳过原函数
});
```

--------------------------------

### GET /health

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Alias for the health check endpoint. Provides the same functionality as GET /.

```APIDOC
## GET /health

### Description
Health check endpoint (alias). Provides the same functionality as the GET / endpoint.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is healthy.
- **message** (string) - A message from the service, typically "rustfrida-rpc".

#### Response Example
```json
{
  "ok": true,
  "message": "rustfrida-rpc"
}
```
```

--------------------------------

### Build Agent with QBDI Support

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Build the agent library with QBDI support by first compiling the qbdi-helper and then building the agent with the 'qbd' feature flag enabled. This is necessary if QBDI functionality is required.

```bash
# 如需 QBDI 支持，先构建 qbdi-helper
cargo build -p qbdi-helper --release
cargo build -p agent --release --features qbdi

```

--------------------------------

### RustFrida Build Process with QBDI Enabled

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Build RustFrida with QBDI support. This requires building the qbdi-helper first, then compiling the agent and RustFrida with the 'qbdi' feature flag.

```bash
# 1. 构建 qbdi-helper
cargo build -p qbdi-helper --release

# 2. 构建 agent（带 qbdi）
cargo build -p agent --release --features qbdi

# 3. 构建 rustfrida（带 qbdi）
cargo build -p rust_fr_ida --release --features qbdi
```

--------------------------------

### Build RustFrida with QBDI Support

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Compile the main rustfrida program with QBDI support enabled by using the '--features qbdi' flag during the Cargo build process.

```bash
# 带 QBDI
cargo build -p rust_frida --release --features qbdi

```

--------------------------------

### Build and Push Agent and Rust Frida

Source: https://github.com/kkkbbb/rustfrida/blob/master/doc/managed-dsl.md

Builds the agent and rust_frida binaries in release mode and pushes the rustfrida binary to the device. Ensures the pushed binary has execute permissions.

```bash
cargo build --release -p agent
cargo build --release -p rust_frida

```

```bash
adb -s <device> push target/aarch64-linux-android/release/rustfrida /data/local/tmp/rustfrida

```

```bash
adb -s <device> shell "su -c 'sh -c "chmod 755 /data/local/tmp/rustfrida"'"

```

--------------------------------

### Build Agent Library (libagent.so)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Compile the agent library for Android using Cargo. This command builds the libagent.so file, which includes QuickJS, the Hook engine, and Java JNI interfaces.

```bash
cargo build -p agent --release
# 输出：target/aarch64-linux-android/release/libagent.so

```

--------------------------------

### Feature Compilation for Agent

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Demonstrates how to build the agent library with and without QBDI support using Cargo feature flags. The default build does not include QBDI.

```bash
# 不带 QBDI（默认）
cargo build -p agent --release

# 启用 QBDI（需 qbdi-helper.so）
cargo build -p agent --release --features qbdi

```

--------------------------------

### Health Check Endpoint

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Use the GET / endpoint for a basic health check of the RPC server. It returns a JSON object indicating the server's status.

```bash
curl http://127.0.0.1:9191/
```

--------------------------------

### Push and Run RustFrida Commands

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Commands to push the RustFrida binary to the device and inject into running processes or spawn new ones. Use the -l flag to load a JavaScript script.

```bash
adb push target/aarch64-linux-android/release/rustfrida /data/local/tmp/

# PID 注入
./rustfrida --pid <pid>
./rustfrida --pid <pid> -l script.js

# Spawn 模式（启动时注入）
./rustfrida --spawn com.example.app
./rustfrida --spawn com.example.app -l script.js

# 等待 SO 加载后注入（eBPF）
./rustfrida --watch-so libnative.so

# 详细日志
./rustfrida --pid <pid> --verbose

# 同步输出日志到文件（终端仍正常输出，文件为纯文本）
./rustfrida --pid <pid> -l script.js -o /data/local/tmp/rustfrida.log
```

--------------------------------

### Standard RustFrida Build Process

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Build RustFrida without QBDI. This involves updating submodules, building the loader shellcode, and then compiling the agent and RustFrida itself in release mode.

```bash
# 1. 更新子仓库（首次）
git submodule update --init --recursive

# 2. 构建 loader shellcode
cd loader && python3 build_helpers.py && cd ..

# 3. 构建 agent
cargo build -p agent --release

# 4. 构建 rustfrida
cargo build -p rust_fr_ida --release

# 验证
ls -la target/aarch64-linux-android/release/rustfrida
```

--------------------------------

### RustFrida Build and Deployment Commands

Source: https://github.com/kkkbbb/rustfrida/blob/master/WALKSTACK_ROOT_CAUSE.md

Commands to build the agent and rust_frida crates, deploy the rustfrida binary to an Android device, and run it with a specific JavaScript hook. This is used to test the fix for the 'StackMap not found' error.

```bash
cd /home/wwb/RustroverProjects/rustFrida/.claude/worktrees/agent-a78f9f0b
cargo build -p agent --release
cargo build -p rust_frida --release
adb -s 10.0.0.44:5556 push target/aarch64-linux-android/release/rustfrida /data/local/tmp/
# 在 Pixel 6 (API 36) 上:
./rustfrida --name com.example -l test_hashmap_put_hook.js
# 触发 HashMap.put 大量调用 + Throwable.fillInStackTrace
# 预期: 不再 LOG(FATAL) "StackMap not found for 0 in HashMap.put"
```

--------------------------------

### RustFrida Compilation Dependencies

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Illustrates the compilation dependencies between the bootstrapper, rustfrida-loader, and the main rustfrida executable, showing how they are linked together.

```text
bootstrapper.bin (ARM64 bare-metal) ┐
                                     ├─→ rustfrida-loader.bin ┐
                                     │                          ├─→ rustfrida (主程序)
                                     agent/libagent.so (QuickJS + Hook)  ┘────────────────────────┘
```

--------------------------------

### Monitor JNI RegisterNatives Calls

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of hooking the JNI `RegisterNatives` function to log class names and the details of native methods being registered. This helps in identifying the mapping between Java methods and their native implementations.

```javascript
Interceptor.attach(Jni.addr("RegisterNatives"), {
    onEnter(args) {
        var cls = Jni.env.getClassName(args[1]);
        var methods = Jni.structs.JNINativeMethod.readArray(args[2], Number(args[3]));

        console.log("RegisterNatives:", cls);
        methods.forEach(function(m) {
            var mod = Module.findByAddress(m.fnPtr);
            var where = mod ? mod.name + "+" + m.fnPtr.sub(mod.base) : m.fnPtr.toString();
            console.log("  " + m.name + " " + m.sig + " -> " + where);
        });
    }
});
```

--------------------------------

### agent Package Configuration

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Configures the agent package, specifying its name, version, edition, features (defaulting to quickjs), and dependencies. It also defines the crate type as a dynamic library.

```toml
[package]
name = "agent"
version = "0.1.0"
edition = "2021"

[features]
default = ["quickjs"]
quickjs = []                 # QuickJS 引擎
qbdi = []                    # QBDI 支持（可选）

[dependencies]
quickjs-hook = { path = "../quickjs-hook" }
frida-gum = { path = "../frida-gum" }
libc = "0.2"

[[lib]]
name = "agent"
crate-type = ["cdylib"]      # 编译成动态库

```

--------------------------------

### Build Loader Shellcode

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Navigate to the loader directory and execute the build_helpers.py script to compile the bootstrapper and loader into binary files. This step generates bootstrapper.bin and rustfrida-loader.bin.

```bash
cd loader
python3 build_helpers.py
# 输出：build/bootstrapper.bin, build/rustfrida-loader.bin

```

--------------------------------

### quickjs-hook Package Configuration

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Configures the quickjs-hook package, including its name, version, edition, features, dependencies, and build dependencies for C code compilation and binding generation.

```toml
[package]
name = "quickjs-hook"
version = "0.1.0"
edition = "2021"

[features]
default = []
std = []                     # 标准库支持
qbdi = []                    # QBDI 支持

[dependencies]
libc = "0.2"

[build-dependencies]
cc = "1"                     # C 代码编译
bindgen = "0.70"            # 生成 C 绑定

```

--------------------------------

### rustfrida Core Module Structure

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Illustrates the directory layout and primary components of the rustfrida project, including the main program, agent library, and bindings to external frameworks.

```tree
rustfrida/
├── rust_frida/          # 主程序：命令行工具，注入器，REPL
│   └── src/
│       ├── main.rs      # 主函数，参数解析，生命周期管理
│       ├── args.rs      # 命令行参数定义
│       ├── injection.rs # ptrace 注入流程
│       ├── process.rs   # 进程操作（attach、call、wait）
│       ├── server.rs    # 多 session daemon 模式
│       ├── http_rpc.rs  # HTTP RPC 服务器
│       └── repl.rs      # 交互式 REPL 和命令处理
│
├── agent/               # 注入到目标进程的动态库
│   └── src/
│       ├── lib.rs       # agent 入口、命令处理、生命周期
│       ├── quickjs_loader.rs  # QuickJS 引擎初始化
│       ├── exec_mem.rs  # 可执行内存管理
│       ├── linker.rs    # 目标进程 linker 操作
│       └── [其他功能模块]
│
├── quickjs-hook/        # QuickJS JavaScript 引擎 + Hook API
│   └── src/
│       ├── lib.rs       # 导出的公共 API
│       ├── jsapi/       # JavaScript API（Hook、Java、JNI、Memory 等）
│       ├── runtime.rs   # JS 运行时
│       ├── context.rs   # JS 上下文
│       └── value.rs     # JS 值表示
│
├── frida-gum/           # Frida Gum 库的 Rust 绑定
│   └── src/
│       ├── lib.rs       # Gum 核心
│       ├── interceptor.rs  # Hook 拦截器
│       ├── stalker.rs   # 指令跟踪
│       ├── module.rs    # 模块信息
│       └── [其他工具模块]
│
├── qbdi/                # QBDI DBI 框架的 Rust 绑定
├── ldmonitor/           # eBPF SO 加载监控
└── loader/              # Bare-metal ARM64 bootstrap 代码
```

--------------------------------

### JavaClassWrapper.$new(...args)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Creates a new instance of a Java class by calling its constructor.

```APIDOC
## JavaClassWrapper.$new(...args)

### Description
Creates an object instance (calls the constructor).

### Method Signature
```javascript
function $new(...args: any[]): JavaObjectProxy
```

### Parameters
* `...args` (any[]) - Arguments are marshalled according to the Java constructor signature.

### Returns
* `JavaObjectProxy` - An instance proxy.

### Example
```javascript
var String = Java.use("java.lang.String");
var s = String.$new("hello");

var ArrayList = Java.use("java.util.ArrayList");
var list = ArrayList.$new();
```
```

--------------------------------

### Hook Native Function and Modify Return Value

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Example of hooking the native 'getuid' function in libc.so. It logs the original return value and then replaces it with 0 using `retval.replace(0)`. This is useful for altering the outcome of a native function call.

```javascript
var getuid = Module.findExportByName("libc.so", "getuid");

Interceptor.attach(getuid, {
    onLeave(retval) {
        console.log("getuid =>", retval.toUInt32());
        retval.replace(0);
    }
});
```

--------------------------------

### API Quick Reference

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/process-and-injection.md

A quick reference table for the available API functions, their parameters, return values, and descriptions.

```APIDOC
## API Quick Reference

| Function | Parameters | Returns | Description |
|---|---|---|---|
| `attach_to_process(tid)` | i32 | Result<()> | ptrace attach |
| `detach_from_process(tid, sig)` | i32, i32 | Result<()> | ptrace detach |
| `call_target_function(tid, func, args, timeout)` | i32, usize, &[usize], Option<u64> | Result<u64> | Remote function call |
| `find_pid_by_name(name)` | &str | Result<i32> | Process name lookup |
| `inject_via_bootstrapper(pid, args)` | i32, &InjectionArgs | Result<InjectionResult> | Main injection function |
| `choose_injection_thread(pid)` | i32 | Result<i32> | Choose injection thread |
| `watch_and_inject(so, args)` | &str, &InjectionArgs | Result<()> | SO load monitoring |
```

--------------------------------

### Fix: Loader Build Directory Not Found

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Addresses the error 'failed to read file: ./loader/build/bootstrapper.bin' by ensuring the loader build directory is created. Navigate to the loader directory and run the build script, then rebuild RustFrida.

```bash
cd loader
python3 build_helpers.py
cd ..
cargo build -p rust_fr_ida --release
```

--------------------------------

### Output File Locations

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/COMPLETION-REPORT.md

Lists the generated documentation files and their corresponding purposes within the output directory.

```text
/workspace/home/output/
├── README.md                        # 导航和概述
├── api-architecture.md              # 架构参考
├── build-and-configuration.md       # 构建配置
├── command-line-interface.md        # CLI 参考
├── http-rpc-api.md                  # HTTP RPC
├── java-hook-api.md                 # Java Hook
├── javascript-api.md                # JavaScript API
├── jni-api.md                       # JNI API
├── process-and-injection.md         # 注入流程
├── types-and-structures.md          # 类型定义
├── 00-CONTENTS.txt                  # 内容清单
└── COMPLETION-REPORT.md             # 本报告
```

--------------------------------

### RustFrida Injection Flow

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Outlines the steps involved in injecting the RustFrida agent into a target process using ptrace and a bootstrap shellcode.

```text
rustfrida(主程序)
  ├─ 解析命令行参数
  ├─ 查找目标进程 PID
  ├─ Attach to process (ptrace)
  ├─ 注入 bootstrap shellcode（arm64 bare-metal）
  │   └─ Bootstrap 在目标进程加载 rustfrida-loader
  │       └─ Loader 在目标进程加载 libagent.so
  ├─ 调用 agent 的 hello_entry(args)
  │   └─ Agent 初始化 QuickJS、Hook 引擎、JNI 环境
  ├─ 启动 socketpair 通信（host ↔ agent）
  ├─ 加载脚本（可选）
  └─ 进入 REPL 或 HTTP 服务模式
```

--------------------------------

### Python Build Helper Script Logic

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

The build_helpers.py script orchestrates the compilation and linking of assembly and C source files into executable binaries, followed by stripping and copying bootstrap code.

```python
def main():
    # 1. 编译 bootstrapper.S → bootstrapper.o
    # 2. 编译 loader.c → loader.o
    # 3. 链接 → rustfrida-loader.elf
    # 4. Strip → rustfrida-loader.bin
    # 5. 复制 bootstrap 部分到 bootstrapper.bin

```

--------------------------------

### rust_frida Package Configuration

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Configures the rust_frida package, including its name, version, edition, description, features, dependencies, and binary path.

```toml
[package]
name = "rust_frida"
version = "0.1.0"
edition = "2021"
description = "ARM64 Android 动态插桩工具"

[features]
# 暂未使用，预留用于条件编译

[dependencies]
ldmonitor = { path = "../ldmonitor" }
clap = { version = "4.5", features = ["derive"] }
nix = { version = "0.30.1", features = ["ptrace", "socket", "uio"] }
goblin = "0.9"                # ELF 解析
once_cell = "1.21"           # 全局单例
rustyline = "15"             # REPL 编辑

[[bin]]
name = "rustfrida"
path = "src/main.rs"

```

--------------------------------

### Build ldmonitor Command-Line Tool

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Independently build the ldmonitor command-line tool. ldmonitor is a dependency of rust_frida, but this command allows for its separate compilation.

```bash
# ldmonitor 已在 rust_frida 依赖中，无需单独编译
# 但可独立构建 ldmonitor 命令行工具
cargo build -p ldmonitor --release
```

--------------------------------

### RustFrida REPL Commands

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

Commands available within the RustFrida interactive REPL for managing the JavaScript engine and executing scripts.

```bash
jsinit              # 初始化 JS 引擎
jseval <expr>       # 求值表达式
loadjs <script>     # 执行脚本
jsrepl              # 交互式 REPL（Tab 补全）
exit                # 退出
```

--------------------------------

### Rust Build Script for Embedding Binaries

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Illustrates how the build.rs script in the rust_frida crate uses `include_bytes!()` to embed the compiled loader shellcode and agent library into the final rustfrida binary.

```rust
// src/main.rs
const BOOTSTRAPPER_BIN: &[u8] = include_bytes!("../loader/build/bootstrapper.bin");
const RUSTFRIDA_LOADER_BIN: &[u8] = include_bytes!("../loader/build/rustfrida-loader.bin");
const LIBAGENT_SO: &[u8] = include_bytes!("../target/aarch64-linux-android/release/libagent.so");

```

--------------------------------

### Build Main RustFrida Executable

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Compile the main rustfrida program for Android using Cargo. This command produces the rustfrida executable, which is self-contained and can be pushed directly to the device.

```bash
cargo build -p rust_frida --release
# 输出：target/aarch64-linux-android/release/rustfrida

```

--------------------------------

### Java.use(className).$new(overload)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Allows specifying a constructor overload when creating a new object instance.

```APIDOC
## Java.use(className).$new(overload)

### Description
`$new` also supports `overload` when there are multiple constructors.

### Example
```javascript
var String = Java.use("java.lang.String");

// String(String) constructor
var s1 = String.$new.overload("java.lang.String")("hello");

// String(byte[]) constructor
var bytes = [72, 101, 108, 108, 111];  // "Hello"
var s2 = String.$new.overload("[B")(bytes);
```
```

--------------------------------

### Hook Instance Method Implementation

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Hook an instance method by assigning an implementation to `Class.method.impl`. The `this` object within the implementation refers to the instance proxy. Use `$orig` to call the original method.

```javascript
// Hook 实例方法
var Activity = Java.use("android.app.Activity");
Activity.onCreate.impl = function(savedInstanceState) {
    console.log("onCreate:", this.$className);
    return this.$orig(savedInstanceState);  // 调原方法
};

// 不调原方法，直接返回
var LoginManager = Java.use("com.example.LoginManager");
LoginManager.checkPassword.impl = function(user, pass) {
    console.log("checkPassword:", user, pass);
    return true;  // 直接返回 true，跳过原方法
};

// Hook 构造函数（$init）
var MyClass = Java.use("com.example.MyClass");
MyClass.$init.impl = function(a, b) {
    console.log("new MyClass(", a, ",", b, ")");
    return this.$orig(a, b);
};
```

--------------------------------

### Java.use(className)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Retrieves a wrapper for a Java class, allowing access to its static methods, fields, and constructors.

```APIDOC
## Java.use(className)

### Description
Gets a reference to a Java class.

### Method Signature
```javascript
function use(className: string): JavaClassWrapper
```

### Parameters
* `className` (string) - The fully qualified class name (e.g., "android.app.Activity").

### Returns
* `JavaClassWrapper` - A class object proxy that supports static methods, static fields, and constructors.

### Example
```javascript
var Activity = Java.use("android.app.Activity");
var Log = Java.use("android.util.Log");
var String = Java.use("java.lang.String");
```
```

--------------------------------

### Fix: NDK Not Found Error

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Resolves the 'failed to run custom build command' error when the Android NDK is not found. Set the ANDROID_NDK_HOME environment variable and update the PATH.

```bash
export ANDROID_NDK_HOME=~/Android/Sdk/ndk/25.1.8937393
export PATH=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
```

--------------------------------

### Jni.env.ptr

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/jni-api.md

Accesses the native pointer for the JNI environment.

```APIDOC
## Jni.env.ptr

### Description
Returns the native pointer to the current JNI environment.

### Returns
- **NativePointer** - The pointer to the JNI environment.
```

--------------------------------

### Create Java Object Instance

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

Use the `$new` method on a `JavaClassWrapper` to create a new instance of a Java class by calling its constructor.

```javascript
var String = Java.use("java.lang.String");
var s = String.$new("hello");

var ArrayList = Java.use("java.util.ArrayList");
var list = ArrayList.$new();
```

--------------------------------

### Fix: include_bytes! File Not Found

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Troubleshoots the 'could not read file' error with the include_bytes!() macro. The path for include_bytes!() is relative to the source file, not the working directory. Ensure 'cargo build' is run from the rust_frida root directory.

```bash
# Ensure 'cargo build' is run from the rust_frida root directory
```

--------------------------------

### RustFrida Embedded Binaries

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Explains how RustFrida embeds binary components like bootstrapper, loader, and agent using the `include_bytes!` macro for a self-contained executable.

```rust
rustfrida 通过 `include_bytes!` 宏在编译时内嵌这三个二进制文件，构成自包含的单文件可执行程序。
```

--------------------------------

### Minimal RustFrida JavaScript Agent

Source: https://github.com/kkkbbb/rustfrida/blob/master/README.md

A basic JavaScript agent for RustFrida that logs messages upon loading and when the Java environment is ready.

```javascript
console.log("agent loaded");

Java.ready(function() {
    console.log("Java is ready");
});
```

--------------------------------

### Workspace Configuration (Root Cargo.toml)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Defines the workspace, resolver, members, and default members for the project. It also sets common package metadata and dependencies.

```toml
[workspace]
resolver = "2"
members = [
    "frida-gum-sys",
    "frida-gum",
    "rust_frida",
    "agent",
    "qbdi-helper",
    "ldmonitor",
    "ldmonitor-common",
    "ldmonitor-ebpf",
    "qbdi",
    "quickjs-hook"
]

default-members = ["frida-gum-sys", "frida-gum", "rust_frida", "agent"]

[workspace.package]
version = "0.16.10"
edition = "2021"

[workspace.dependencies]
anyhow = "1"
clap = "4"
tokio = "1"
# ...

```

--------------------------------

### choose_injection_thread

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/process-and-injection.md

Selects the thread for injection based on specific strategies.

```APIDOC
## choose_injection_thread()

### Description
Selects the thread for injection when attaching to a process.

### Parameters
#### Path Parameters
- **pid** (i32) - Required - The process ID.

### Returns
- **Result<i32>** - The TID of the chosen thread or an error.

### Logic
1. Iterates through `/proc/[pid]/task`.
2. Selects the thread where `tid == pid` (main thread).
3. If the main thread doesn't exist, selects the first live thread.
```

--------------------------------

### RustFrida Script Execution Flow

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Details how user-provided JavaScript scripts interact with the RustFrida agent's components like the logging system, hook engine, JNI environment, and memory access.

```text
User script (JavaScript) 
  ├─ console.log()          → agent 日志系统
  ├─ hook(addr, callback)   → Hook 引擎（native hook）
  ├─ Interceptor.attach()   → Hook 引擎（attach hook）
  ├─ Java.use()             → JNI 环境 → ART 运行时
  ├─ Memory.readU32()       → 目标进程内存访问
  ├─ Module.findExportByName() → ELF 符号查找
  └─ rpc.exports = {...}    → HTTP RPC 导出
```

--------------------------------

### Jni.entries

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/jni-api.md

Retrieves all available JNI entries.

```APIDOC
## Jni.entries()

### Description
Returns an array of all JNI entries available in the current context.

### Returns
- **JniEntry[]** - An array of JniEntry objects.
```

--------------------------------

### Fix: TinyCC Submodule Not Initialized

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/build-and-configuration.md

Resolves the 'submodule path ... not initialized' error. This command initializes and updates all Git submodules, including the TinyCC submodule.

```bash
git submodule update --init --recursive
```

--------------------------------

### Choose Injection Thread Strategy

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/process-and-injection.md

Selects the thread for code injection. It prioritizes the main thread (tid == pid) for stability and a complete stack, falling back to the first available live thread if the main thread is not found.

```rust
pub fn choose_injection_thread(pid: i32) -> Result<i32> {
    // 遍历 /proc/[pid]/task 目录
    // 选择 tid == pid 的线程（主线程）
    // 如果不存在，选择第一个存活的线程
}
```

--------------------------------

### Managed DSL: Restricted Mixed Return Paths

Source: https://github.com/kkkbbb/rustfrida/blob/master/doc/managed-dsl.md

Illustrates a restricted DSL program that mixes direct returns with `orig()` calls, which is rejected by the compiler. All return paths must consistently use `return orig();` or `return orig(...)` when `orig()` is invoked.

```javascript
"if (arg0 == null) {" +
"  return null;" +
"} else {" +
"  return orig();" +
"}"
```

--------------------------------

### Stealth Mode Constants (Java)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/types-and-structures.md

Configure Java stealth mode using these constants. Set to 0 for Normal, 1 for WxShadow, and 2 for Recomp.

```javascript
Java.setStealth(0)    // Normal
Java.setStealth(1)    // WxShadow
Java.setStealth(2)    // Recomp
```

--------------------------------

### Hook Mode Constants

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/types-and-structures.md

These constants define different hook modes. Use NORMAL for direct mprotect writes, WXSHADOW for shadow pages, and RECOMP for code recompilation.

```javascript
Hook.NORMAL = 0       // mprotect 直写
Hook.WXSHADOW = 1     // shadow 页
Hook.RECOMP = 2       // 代码重编译
```

--------------------------------

### Create CModule from C Source

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/javascript-api.md

Instantiate a CModule object to dynamically compile C source code within the target process. Optionally provide a symbols map for imported functions. Ensure a reference is kept to the CModule to prevent garbage collection.

```javascript
var cm = new CModule(`
    #include <rfhook.h>    
    void on_getuid(HookContext *ctx, void *user_data) {
        uint64_t real = hook_invoke_trampoline(ctx, ctx->trampoline);
        ctx->x[0] = (real == 0 ? 0 : 1000);
    }
`);

globalThis.keep_getuid = cm;    // 保留引用，避免 GC 释放

var trampoline = hookNative(
    Module.findExportByName("libc.so", "getuid"),
    cm.on_getuid
);
```

--------------------------------

### AgentArgs C Struct Definition

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/api-architecture.md

Defines the entry arguments for the agent, passed to hello_entry. It contains a pointer to StringTable, a control file descriptor for communication, and the agent's memory file descriptor.

```rust
#[repr(C)]
pub struct AgentArgs {
    pub table: u64,
    pub ctrl_fd: i32,
    pub agent_memfd: i32,
}
```

--------------------------------

### Create Java Object with Overloaded Constructor

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/java-hook-api.md

When a class has multiple constructors, use `$new.overload` with the constructor's signature to specify which constructor to call when creating a new instance.

```javascript
var String = Java.use("java.lang.String");

// String(String) 构造函数
var s1 = String.$new.overload("java.lang.String")("hello");

// String(byte[]) 构造函数
var bytes = [72, 101, 108, 108, 111];  // "Hello"
var s2 = String.$new.overload("[B")(bytes);
```

--------------------------------

### Call RPC Exported Method (Object Arguments)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

For methods expecting object arguments, send a JSON array containing the object. Ensure the Content-Type header is set to application/json for proper parsing.

```bash
# 对象参数
curl -X POST http://127.0.0.1:9191/rpc/0/echo -d '[{"foo": 1, "bar": "hi"}]'
```

--------------------------------

### Control Hook Stealth Level

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/javascript-api.md

Use the 'stealth' parameter to control the obfuscation level of hooks. Level 1 (WXSHADOW) uses kernel shadow pages for invisibility in /proc/mem. Level 2 (RECOMP) recompiles code pages for maximum stealth with 4-byte patches.

```javascript
hook(target, callback, 1);       // 用 WXSHADOW
hook(target, callback, true);    // true 等价 1（WXSHADOW）
```

--------------------------------

### Call RPC Exported Method (Positional Arguments)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Invoke an exported RPC method with positional arguments by sending a JSON array of arguments in the request body. The session ID is fixed to 0 in legacy mode.

```bash
# 位置参数（JSON 数组）
curl -X POST http://127.0.0.1:9191/rpc/0/add -d '[3, 4]'
```

--------------------------------

### Call RPC Exported Method (Empty Body)

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

An empty request body for a POST /rpc call is equivalent to sending an empty JSON array, suitable for methods that accept no arguments.

```bash
# 空 body 等价 []
curl -X POST http://127.0.0.1:9191/rpc/0/ping
```

--------------------------------

### POST /rpc/<session>/<method>

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/http-rpc-api.md

Invokes a remote procedure call (RPC) exported method on a specific session. Supports methods with no arguments, positional arguments, or object arguments.

```APIDOC
## POST /rpc/<session>/<method>

### Description
Invokes a remote procedure call (RPC) exported method on a specific session. Arguments can be passed as a JSON array or object in the request body.

### Method
POST

### Endpoint
/rpc/<session>/<method>

### Parameters
#### Path Parameters
- **session** (string) - The session ID. For legacy mode, this is fixed at 0.
- **method** (string) - The name of the exported method to call (key in `rpc.exports`).

#### Request Body
- **Arguments** (array or object) - Optional. The arguments to pass to the RPC method. Can be a JSON array for positional arguments, or a JSON object for named arguments. If omitted, it's treated as an empty array `[]`.

### Request Example
```bash
# No arguments
curl -X POST http://127.0.0.1:9191/rpc/0/ping

# Positional arguments (JSON array)
curl -X POST http://127.0.0.1:9191/rpc/0/add -d '[3, 4]'

# Object arguments
curl -X POST http://127.0.0.1:9191/rpc/0/echo -d '[{"foo": 1, "bar": "hi"}]'

# Empty body is equivalent to an empty array
curl -X POST http://127.0.0.1:9191/rpc/0/ping
```

### Request Headers
- **Content-Type** (string) - Optional. Should be `application/json` if sending a request body.

### Response
#### Success Response (200)
- **ok** (boolean) - True if the RPC call was successful, false otherwise.
- **result** (any) - The return value of the RPC method if `ok` is true.
- **error** (string) - An error message if `ok` is false.

#### Response Example (Success)
```json
// Example for ping method
{
  "ok": true,
  "result": "pong"
}

// Example for add(3, 4)
{
  "ok": true,
  "result": 7
}

// Example returning an object
{
  "ok": true,
  "result": {"device": "Pixel6", "model": "Google", "fingerprint": "..."}
}
```

#### Response Example (Error)
```json
{
  "ok": false,
  "error": "<error-message>"
}
```

### Error Handling
#### HTTP Status Codes
- **200**: Success (regardless of `ok` field in response body).
- **400**: Bad Request (e.g., invalid JSON, non-numeric session ID).
- **404**: Not Found (session or method does not exist).
- **503**: Service Unavailable (session not connected or agent unavailable).
- **500**: Internal Server Error (JavaScript execution error or timeout).

#### Error Messages
- `session not found`: The specified session ID does not exist.
- `method not found`: The specified method is not found in `rpc.exports`.
- `session not connected`: The target session is disconnected.
- `rpc call timed out`: The RPC call exceeded the 30-second timeout.
- `...`: JavaScript execution error, with the error message following.
```

--------------------------------

### Jni.env.exceptionOccurred

Source: https://github.com/kkkbbb/rustfrida/blob/master/_autodocs/jni-api.md

Retrieves the pending Java exception.

```APIDOC
## Jni.env.exceptionOccurred()

### Description
Returns a pointer to the pending Java exception object, if one has occurred.

### Returns
- **NativePointer | null** - A pointer to the exception object, or null if no exception is pending.
```