Android eBPF Monitor is an observe-only monitoring toolkit for researching how Android apps access device and environment information through Binder, bionic system properties, file reads, and raw syscalls.
The project is designed around a simple rule: monitor, do not interfere. It records events for a target app UID/package, but it does not block calls, rewrite parameters, spoof values, or modify return values.
The current implementation was developed and tested on a rooted Pixel 6-class device running Android 16 / Linux 6.1, but the monitors are generic and are not tied to a specific app.
| Monitor | Coverage | Output |
|---|---|---|
| Binder | Binder transaction tracepoint plus Parcel head parsing | Interface descriptor, transaction code, flags, Parcel strings |
| SystemProperty | bionic __system_property_get, __system_property_find, and __system_property_read_callback uprobes |
Property function and property name |
| File/Open | kernel-side do_sys_openat2, ksys_read, do_readlinkat probes |
open path, fd, read path/count, readlink target |
| Syscall | raw_syscalls/sys_enter and raw_syscalls/sys_exit tracepoints |
syscall name, number, args, return value |
Syscall capture also supports rough filtering for practical triage:
- emit only the first occurrence of each syscall number
- include or exclude syscall numbers
- limit capture to one or more process PIDs (
Tgid)
.
├── include/ # shared event structs and lightweight BPF compatibility headers
├── src/
│ ├── bpf/ # eBPF programs
│ └── user/ # Android-side readers, attach helpers, and config tools
├── tools/
│ ├── linux/ # Linux/macOS shell scripts
│ └── windows/ # Windows cmd/bat scripts
├── docs/
│ ├── usage/ # current user-facing runbooks
│ └── monitoring/ # design notes by monitoring surface
├── configs/
├── samples/
└── Makefile
Start with docs/usage/current_tools.md for the up-to-date command flow.
Host:
adbclangwith BPF target support- Android NDK for building Android userspace binaries
make
Device:
- rooted Android device
/sys/fs/bpf/sys/kernel/tracingbpftoolon device- Binder tracepoints
- uprobe and kprobe support
- raw syscall tracepoints for syscall monitoring
Run the environment checker first:
tools/linux/check_android_ebpf_env.sh com.example.appWindows:
tools\windows\check_android_ebpf_env.bat com.example.appSet your Android NDK path if it differs from the default in the Makefile:
export ANDROID_NDK="$HOME/Library/Android/sdk/ndk/26.0.10792818"
make clean && make allIf your NDK toolchain path differs, override ANDROID_CC directly:
make ANDROID_CC=/path/to/aarch64-linux-android34-clang allBuild outputs are written to build/.
Push the BPF objects and Android helper binaries:
adb push build/binder_monitor.bpf.o /data/local/tmp/binder_monitor.bpf.o
adb push build/property_monitor.bpf.o /data/local/tmp/property_monitor.bpf.o
adb push build/file_monitor.bpf.o /data/local/tmp/file_monitor.bpf.o
adb push build/syscall_monitor.bpf.o /data/local/tmp/syscall_monitor.bpf.o
adb push build/fp_configure /data/local/tmp/fp_configure
adb push build/fp_syscall_configure /data/local/tmp/fp_syscall_configure
adb push build/fp_binder_reader /data/local/tmp/fp_binder_reader
adb push build/fp_property_reader /data/local/tmp/fp_property_reader
adb push build/fp_file_reader /data/local/tmp/fp_file_reader
adb push build/fp_syscall_reader /data/local/tmp/fp_syscall_reader
adb push build/fp_attach_kprobe /data/local/tmp/fp_attach_kprobe
adb push build/fp_attach_uprobe /data/local/tmp/fp_attach_uprobe
adb shell chmod 755 /data/local/tmp/fp_*Each monitor has its own pinned bpffs namespace:
/sys/fs/bpf/fpmon_binder
/sys/fs/bpf/fpmon_property
/sys/fs/bpf/fpmon_file
/sys/fs/bpf/fpmon_syscall
Load commands are documented in docs/usage/current_tools.md.
Replace com.example.app with the target package.
Linux/macOS:
tools/linux/start_binder_capture.sh com.example.app
tools/linux/start_property_capture.sh com.example.app
tools/linux/start_file_capture.sh com.example.app
tools/linux/start_syscall_capture.sh --unique-nr --enter-only com.example.appWindows:
tools\windows\start_binder_capture.bat com.example.app
tools\windows\start_property_capture.bat com.example.app
tools\windows\start_file_capture.bat com.example.app
tools\windows\start_syscall_capture.bat --unique-nr --enter-only com.example.appLogs are written under:
logs/<package>/binder/
logs/<package>/property/
logs/<package>/file/
logs/<package>/syscall/
The combined script starts Binder, SystemProperty, and File/Open capture together. Syscall capture is intentionally disabled by default because raw syscall volume can be very high.
Linux/macOS:
tools/linux/start_combined_capture.sh com.example.app
tools/linux/start_combined_capture.sh --with-syscall com.example.appWindows:
tools\windows\start_combined_capture.bat com.example.app
tools\windows\start_combined_capture.bat --with-syscall com.example.appTo limit syscall capture to known process PIDs:
adb shell pidof com.example.app
tools/linux/start_syscall_capture.sh --pid 12345,12346 com.example.app- Current tools and commands
- Binder monitor usage
- SystemProperty monitor usage
- File/Open monitor usage
- Syscall monitor usage
- Filtering model
- Startup capture notes
- Roadmap
This project is intended for defensive research, observability, and debugging on devices you own or are authorized to test.
The tools:
- require a rooted/debuggable Android environment
- require an explicit target package/UID for normal capture
- do not bypass app permissions
- do not modify app behavior
- do not spoof device identifiers
- do not block, deny, or rewrite observed calls
Issues and pull requests are welcome, especially for:
- additional Android kernel symbol fallbacks
- more Android version/device compatibility notes
- improved readers and log parsers
- safer deployment and cleanup tooling
- documentation updates for real devices
Please include the Android version, kernel version, device model, and the relevant monitor logs when reporting compatibility issues.
This project is licensed under the Apache License 2.0. See LICENSE for details.