memagent

In-kernel physical memory acquisition agent for Android — a KernelPatch module (KPM) that serves physical memory reads over TCP to a PC client. Conceptually an Android equivalent of leechagent (PCILeech), requiring no PCIe hardware: it runs inside the target device's kernel.

Typical uses: security research, memory forensics (DFIR), reverse engineering, OS/toolchain development — on devices you own or are authorized to analyze.

┌────────── PC ──────────┐         USB (adb forward) / TCP        ┌──────── Android ────────┐
│  memagent-cli / python ─┼──────────────────────────────────────▶│  memagent.kpm (kernel)  │
│  client library         │◀────────────── physical memory ───────│  127.0.0.1:9847 (def.)  │
└─────────────────────────┘                                       └─────────────────────────┘

• Physical memory read via memremap + copy_from_kernel_nofault
  • fault-safe: invalid/hole pages return zeros, never panics the kernel
  • no physvirt_offset dependency (works on Linux 6.4+ where it was removed), KASLR-safe
• Fast: pipelined double-buffered reader thread; large-region reads stream at ~59 MB/s over adb forward (measured on a 6.12 GKI tablet)
• Batch API: pipelined multi-request batch for thousands of small reads
• PSK authentication, constant-time key comparison
• Safe defaults (v0.5): binds 127.0.0.1 only; open-network mode requires an explicit key or the module refuses to load
• Boot-embeddable: can be embedded into boot.img/init_boot.img with kptools so it loads at every boot, no manager app needed

kpm/        memagent.c source + Makefile (builds memagent.kpm)
client/     python client library (memagent.py) + CLI (memagent-cli.py)
tools/      patch_boot.sh — embed the KPM into a boot image
docs/       SECURITY.md (threat model), PROTOCOL.md (wire format), BOOT.md (flashing guide)

1. Root your device with a KernelPatch-based solution (APatch / KPatch-Next / SukiSU-Ultra).
2. Build or download memagent.kpm (see kpm/Makefile).
3. Load it with a unique key:

   kpatch <superkey> kpm load memagent.kpm "key=YOUR-UNIQUE-KEY"
   

   (exact loader command depends on your KernelPatch distribution)
4. Connect from the PC over USB:

   adb forward tcp:9847 tcp:9847
   python3 client/memagent-cli.py --key YOUR-UNIQUE-KEY ping
   python3 client/memagent-cli.py --key YOUR-UNIQUE-KEY info
   python3 client/memagent-cli.py --key YOUR-UNIQUE-KEY read 0x80000000 256
   python3 client/memagent-cli.py --key YOUR-UNIQUE-KEY dump 0x80000000 0x100000000 -o ram.bin
   

tools/patch_boot.sh -i boot.img -k kpimg -s <superkey> \
    -a "key=YOUR-UNIQUE-KEY" -o boot_patched.img
fastboot boot boot_patched.img     # test first, no flashing!

See docs/BOOT.md for the full safety workflow.

Read docs/SECURITY.md before deploying. Short version: this is a kernel memory backdoor by design; the default configuration (localhost bind + adb forward + unique key) keeps it reachable only via a physical USB connection you initiate. Never expose it to a network with the default key.

• Kernel: designed for GKI kernels; verified on Linux 6.12 (GKI). All symbols are resolved at load time via kallsyms_lookup_name, so it generally works across versions where the symbols exist (requires CONFIG_KALLSYMS=y, CONFIG_KALLSYMS_ALL=y recommended).
• Loader: any KernelPatch-compatible loader (APatch, KPatch-Next, SukiSU-Ultra).
• PC client: Python 3.8+, no dependencies.

GPL-2.0-or-later. Built on the KernelPatch KPM ABI (https://github.com/bmax121/KernelPatch, GPL-2.0).

This repository was generated by the KIMI K3 model, which read the maintainer's existing local project and produced this public release. The code was split out and reorganized from that existing project by KIMI K3, then hardened and documented for publication.

本仓库由 KIMI K3 模型读取本地已有项目后生成。代码由 KIMI K3 从已有 项目中拆分、整理而来，并在拆分过程中完成了面向公开发布的安全加固与 文档编写。