stackplz Plus
stackplz
Wbstack/Watch Breakpoint Stack/stackplz Plus
stackplz is an eBPF-based stack tracing tool currently available only for the Android platform.
Features
- Supports arm64 syscall tracing, printing parameters (including detailed struct info), call stacks, and registers.
- Supports uprobes on 64-bit user-space libraries, printing parameters, call stacks, and registers.
- Supports hardware breakpoints, printing call stacks and registers, and providing Frida RPC interaction.
- Supports blacklist/whitelist filtering for process IDs, thread IDs, and thread names.
- Supports tracking forked child processes.
Requirements
- Root privileges and kernel version 5.10+ (
uname -rto check). - For 4.1x kernels, if
CONFIG_HAVE_HW_BREAKPOINTis enabled, hardware breakpoints can also be used.
Supported Environments (not just physical devices)
- ARM development boards running Android images
- ARM boards/cloud servers + Docker + ReDroid
- Apple M-series devices + Android official ARM64 emulator
- Cloud-based Android instances with root and kernel 5.10+
Usage
Download the latest precompiled binary from Releases or GitHub Actions.
- Push it to
/data/local/tmpon your device and make it executable:
adb push stackplz /data/local/tmp
adb shell
su
chmod +x /data/local/tmp/stackplz
Note: For versions before v3.0.1, when switching versions, release library files with:
cd /data/local/tmp && ./stackplz --prepare
2. Options Overview
All available options can be viewed via:
./stackplz --help
2.1 Target Filtering Options
Use commas to separate multiple targets; --no-xxx indicates a blacklist.
| Option | Blacklist Option | Description |
|---|---|---|
| -n / –name | App package name or group name (root/system/shell/app/iso) | |
| -u / –uid | –no-uid | Target UID |
| -p / –pid | –no-pid | Target PID |
| -t / –tid | –no-tid | Target TID |
| –tname | –no-tname | Target thread name (max 16 bytes) |
2.2 Syscall / Uprobe Hook Options
- -s / –syscall name/group
Hook syscalls by name or group. Blacklist counterpart:--no-syscall. - -w / –point symbol/offset[type,type,…]
Uprobe hook (requires-l/--lib). See examples below.
2.3 Hardware Breakpoint Options
| Option | Default | Description |
|---|---|---|
| –pid | Target process PID (used with –brk-lib) | |
| –brk | Target breakpoint address | |
| –brk-len | 4 | Breakpoint length |
| –brk-lib | Target library (when set, –brk is treated as offset) | |
| –brk-pid | -1 | PID of the process where the breakpoint applies |
2.4 Signal Sending
Send signals (SIGSTOP, SIGABRT, SIGTRAP, etc.) when a hook is hit:
--kill SIGSTOP
Note: For syscalls, the signal is sent after execution, so for exit or exit_group this may not behave as expected.
2.5 Parameter Filtering
-f/--filter defines filtering rules.
| Rule | Example | Description |
|---|---|---|
| w / white | w:/sbin/su | Whitelist strings starting with /sbin/su |
| b / black | b:/sbin/su | Blacklist strings starting with /sbin/su |
| bx / bufhex | bx:73ea68 | Whitelist buffers starting with 73ea68 (hex) |
| eq / equal | eq:0x748a484d2c | Whitelist register values equal to given hex |
2.6 Boolean Options
| Option | Description |
|---|---|
| –auto | Auto-resume process when used with --kill SIGSTOP |
| –btf | Explicitly declare kernel with CONFIG_DEBUG_INFO_BTF |
| –color | Enable colored terminal output (with --dumphex) |
| –dumphex | Output buffers as hexdump (CyberChef style) |
| –getoff | Print PC/LR offsets (slower) |
| –json | Output logs in JSON |
| –jstack | Parse jar/vdex from stack (requires --kill SIGSTOP) |
| –mstack | Simplified stack tracing without symbols |
| –nocheck | Disable BPF feature check |
| –quiet | Suppress terminal output |
| –regs | Show all registers |
| –showpc | Show raw PC values in stack |
| –showtime | Show time since boot (ns) |
| –showuid | Output UID |
| –stack | Print call stacks |
2.7 RPC Options (Frida Integration)
Used for remotely setting hardware breakpoints via Frida RPC.
- Server:
./stackplz --rpc --stack - Client: See frida_hw_brk.js
- Default port:
127.0.0.1:41718(change with--rpc-path) - You can also implement your own socket connection.
2.8 Miscellaneous
-a/--arch: Target architecture (default: aarch64)-b/--buffer: Perf buffer size (default: 8M)-c/--config: Load from config file (see CONFIG.md)--full-tname: Unmask high-frequency system threads-l/--lib: Library name/path (used with-w/--point)-o/--out: Output log file name--dump: Dump mode (raw data, no parsing)--parse: Parse dumped files--stack-size: Stack size (default 8192 bytes, max 65528)
3. Command Examples
3.1 Trace Syscalls
./stackplz -n com.starbucks.cn --syscall connect,sendto,recvfrom -o tmp.log --dumphex
For syscall names, refer to Linux kernel syscall tables
3.2 Trace libc’s open
./stackplz -n com.starbucks.cn --point strstr[str,str] --point open[str,int] -o tmp.log
3.3 Send Signal on Hook
./stackplz -n com.sfx.ebpf --lib libnative-lib.so -w _Z5func1v --stack --kill SIGSTOP
Resume process:
kill -SIGCONT 4326
From v3.0.0, you can press c + Enter in the terminal to resume.
3.4 Hardware Breakpoints
./stackplz --pid `pidof com.sfx.ebpf` --brk 0x70ddfd63f0:x --stack
Or with library offset:
./stackplz --pid `pidof com.sfx.ebpf` --brk 0xf3a4:x --brk-lib libnative-lib.so --stack
⚠️ Warning: Kernel function breakpoints may cause device reboots.
3.5 Read Data Using Register or Fixed Size
./stackplz --name com.sfx.ebpf -w write[int,buf:x2,int]
Advanced usage and examples for offsets and return hooks are provided in the original document.
4. Compilation
See workflow or Build Docs.
Q & A
1. How are the preload_libs built?
See unwinddaemon. Since v3.0.3, a new build method is used.
2. “perf event ring buffer full” error
Increase buffer size (-b) until data loss stops:
./stackplz -n com.starbucks.cn -b 32 --syscall all -o tmp.log
3. Hooking symbols but no output?
Use the actual implementation name (e.g., __strchr_aarch64 instead of strchr).
Related Articles
- eBPF on Android: stackplz from 0 to 1
- eBPF on Android (Supplement): Why the Phone Reboots
- eBPF-based Android Reverse Engineering Tool: stackplz
References
wbstack
./wbstack_arm64 -p `pidof com.sfx.ebpf` --brk 0x6dd9d563a4:x --stack
./wbstack_arm64 -p `pidof com.sfx.ebpf` --brk 0x6dd9d563a4:x -w 0x0[str,ptr,buf:32:x0] --color --dumphex
./wbstack_arm64 -p `pidof com.sfx.ebpf` --brk 0xF3A4:x --brk-lib libnative-lib.so -w 0x0[str,ptr,buf:32:x0] --color --dumphex --stack
./wbstack_arm64 -p `pidof com.sfx.ebpf` --brk 0xF3A4:x --brk-lib libnative-lib.so -w 0x0[str,ptr,buf:32:x0] --color --dumphex --stack --jstack --kill SIGSTOP
