项目介绍

ARM64 Android 内核级内存扫描器 + 调试器，类 Cheat Engine。

零 ptrace、零 /proc/pid/mem、零 process_vm_readv。所有内存访问通过内核模块页表 walk 完成。

架构


┌─ Python Client (PyQt6) ────────────────────────────────────┐
│  main_window.py → memory_view.py → scanner.py              │
│  ce_client.py (TCP) → mcp_server.py (AI tools)             │
└──────────────────┬──────────────────────────────────────────┘
                   │ TCP (CE 7.x compatible protocol)
┌──────────────────▼──────────────────────────────────────────┐
│  ce_server (static aarch64 binary)                          │
│  CE protocol dispatch + HW breakpoint manager               │
└──────────────────┬──────────────────────────────────────────┘
                   │ ioctl(/dev/cx_xxxxxx)
┌──────────────────▼──────────────────────────────────────────┐
│  shadow_ce.ko (kernel module)                               │
│  page-table walk + kmap R/W + kernel-side scan              │
│  PTE breakpoints + LL/SC emulation + step handler           │
│  Extreme HWBP engine (VBAR-patched, ~12 ticks/hit)          │
└─────────────────────────────────────────────────────────────┘

项目布局


shadow_ce/
├── client/             # Python PyQt6 UI + MCP server
├── server/             # Kernel module + userland ce_server
│   ├── kern_*.c/.h     # Kernel module sources (single-file library style)
│   │   ├── kern_shadow_ce.c       # Thin module shell: ioctl dispatch + init
│   │   ├── kern_kpatch.h          # ARM64 B-detour hook infrastructure
│   │   ├── kern_mem.h             # Page-table walk + R/W + scan + rescan
│   │   ├── kern_ptrscan.h         # Collect-sort-BFS pointer scanner
│   │   ├── kern_ptebp.h           # PTE breakpoint engine
│   │   └── kern_extreme_hwbp.h    # VBAR+0x400 ultra-low-latency HWBP
│   ├── usr_*.c/.h      # Userland sources
│   │   ├── usr_server.c           # TCP server (CE protocol)
│   │   ├── usr_hwbp.h             # perf_event_open HWBP
│   │   ├── usr_extreme_hwbp_cmd.h # VBAR HWBP command dispatch
│   │   └── usr_unload.c           # Forced-unload helper
│   ├── shadow_ce.h     # Shared ioctl interface (both sides include)
│   ├── build.sh        # One-shot build + deploy script
│   ├── Makefile        # Kernel module Makefile
│   ├── build/          # Intermediate objects (gitignored)
│   └── dist/           # Final products: shadow_ce.ko, ce_server, unload
├── tests/              # Standalone test programs
├── markdown/           # Additional docs (CLAUDE.md, PTEBP_ISSUES.md)
└── README.md

构建

内核模块 + 用户态二进制 + 一键部署


cd server
./build.sh          # build ko + server + unload, push to device, reload, start
./build.sh ko       # kernel module only
./build.sh server   # ce_server binary only
./build.sh deploy   # push pre-built dist/ and reload (no rebuild)
./build.sh unload   # rmmod on device
./build.sh clean    # wipe build/ and dist/

Requirements:

Kernel source tree at /root/kernel_build/kernel_workspace/kernel_platform/common
AOSP Clang at /root/aosp-clang-r510928/bin
aarch64-linux-gnu-gcc for userland binaries
adb.exe in PATH (WSL2 uses Windows ADB)

Python 客户端


# WSL2 (with GPU passthrough)
GALLIUM_DRIVER=d3d12 python3 client/shadow_ce.py
 
# Windows native
python client/shadow_ce.py

内核模块分层

每个 kern_*.h 都是 self-contained 单文件库，任何 ko #include 即用。依赖方向：


               kern_shadow_ce.c  (ioctl dispatch + init)
                      │
       ┌──────────────┼──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
  kern_mem.h     kern_ptrscan.h  kern_ptebp.h  kern_extreme_hwbp.h
       │              │              │              │
       │              └──► kern_mem  │              │
       │                             ▼              ▼
       │                       kern_kpatch.h ◄──────┘
       │                             ▲
       └────(ptebp trap fallback)────┘

kern_kpatch.h — 最底层，0 依赖。kallsyms 解析 + CFI-safe indirect call + make_b + B-detour hook 基础设施
kern_mem.h — 0 强依赖。页表 walk + 进程内存 R/W + scan/rescan。如果 PTEBP_H 已定义，R/W 会自动回退 ptebp_find_trapped_page 读 trap 过的原页
kern_ptrscan.h — 依赖 kern_mem.h（用 mem_walk_pte + mem_read8）
kern_ptebp.h — 依赖 kern_kpatch.h（hook do_page_fault / syscall_trace_exit）
kern_extreme_hwbp.h — 依赖 kern_kpatch.h + kern_ptebp.h（通过 ptebp_set_change_cb 联动 VBAR 噪音过滤）
kern_shadow_ce.c — 只做 miscdevice 注册 + ioctl 分发 + init/exit (~350 行)

核心技术

1. 内存读写 (kern_mem.h)

不用 ptrace，内核态页表 walk + kmap：

pgd_offset → p4d → pud → pmd → pte_offset_map 取目标进程 PTE
vm_normal_page 排除 VM_IO / VM_PFNMAP / special / devmap
kmap_local_page 映射物理页到内核虚拟地址
copy_to_user / copy_from_user 交换数据

支持 huge page (PMD 2MB / PUD 1GB)，256KB 批次，跨页自动分段，写入可执行页自动 flush_icache_range。

2. 内存扫描 (kern_mem.h)

内核态扫描，不逐字节从用户态读：

首次扫描：遍历 VMA (VMA_ITERATOR)，kmap 全页 + 逐对齐地址比较
二次扫描：只检查上次结果
支持 exact / bigger / smaller / between / changed / unchanged / increased / decreased
Float 用 ULP 容差（整数位操作，不用 FPU）
Chunked mmap_read_lock：每 1024 页释放锁 + cond_resched，最大持锁 ~1ms

3. 指针扫描 (kern_ptrscan.h)

内核态 collect-then-BFS，一次 ioctl 完成全流程：

收集静态区域（file-backed RW VMA）
收集所有指针对（全 RW 页 8B 对齐值）→ 30M pairs in ~100ms
LSD Radix Sort (8-pass 8-bit) → 30M pairs <1s
BFS 图遍历 → 数千条链 in 2-13s

每 2048 页释放 mmap_read_lock，游戏渲染零阻塞。

4. PTE 断点 (kern_ptebp.h)

单文件可复用引擎。完整实现：

R/W/RW watchpoint — 通过 PTE 权限位触发 data abort
EXEC breakpoint — S1PIE 零 PIIndex 触发 instruction abort
Sub-page 过滤 — 每字节精确匹配 (watch_addr + watch_size)
自愈单步 — MDSCR.SS 跨 context switch 保持 (TIF_SINGLESTEP 驱动)
SVC 闪退修复 — hook syscall_trace_exit，暂时清 TIF 避免 kernel 发 SIGTRAP
LL/SC 模拟 — ldxr/stxr 在单步下会无限重试，fault handler 内直接模拟
Change callback — 与 VBAR HWBP 引擎解耦

对外 API：


#define KPATCH_TAG "[mymod] "
#define PTEBP_TAG  "[mymod] "
#include "kern_kpatch.h"
#include "kern_ptebp.h"
 
kpatch_init();
ptebp_init();
 
int slot;
ptebp_set(pid, addr, PTEBP_TYPE_EXEC, 4, &slot);
 
struct ptebp_hit hits[64];
unsigned int n;
ptebp_poll_user(user_buf, 64, &n);

5. Kernel patching 库 (kern_kpatch.h)

单文件 ARM64 内核 patching 基础设施。任何 ko 可直接 include：

kln(name) — kallsyms lookup via kprobe bootstrap
call_module_alloc / call_set_memory_x / call_patch_text_nosync — CFI-safe 间接调用
call_enable_debug_monitors / call_register_user_step_hook 等
make_b(from, to) — ARM64 B 指令编码
kpatch_hook_install(&hook, "symbol", handler) — B-detour hook with trampoline
kpatch_hook_remove(&hook) — RCU-safe 卸载（synchronize_rcu + 50ms margin）

6. Extreme HWBP (kern_extreme_hwbp.h)

VBAR+0x400 补丁，~12 ticks/hit vs perf_event_open 的 ~163 ticks：

汇编写的中断处理程序直接存 33 寄存器到 ring buffer
EC=0x30 (BP) / EC=0x34 (WP) / EC=0x32 (SS) 分发
自带 PTE 噪音过滤路径（用 ptebp_set_change_cb 联动）
零内核态调度，全在 VBAR 完成

7. HW 断点（用户态 perf_event_open）

usr_hwbp.h：用户态 perf_event_open 方案，利用内核自带的单步恢复。

不用内核态 perf_event_create_kernel_counter：uses_default_overflow_handler() 返回 FALSE 时框架不做单步，Execute BP 会无限重触发。

CE 协议 CMD 编号

CMD	Hex	用途
GET_VERSION	0x00	握手
OPEN_PROCESS	0x03	打开进程
READ_MEMORY	0x09	读内存
WRITE_MEMORY	0x0A	写内存
VQE	0x1F	枚举 VMA
SCAN	0xC8	首次扫描
RESCAN	0xC9	二次扫描
MODULE_LIST	0xCA	批量模块列表
READ_BATCH	0xCB	批量读
HWBP_SET/CLEAR/POLL	0xCC-0xCF	硬件断点
PTRSCAN	0xD0	指针扫描
CHAIN_WALK	0xD1	批量链走查
PTEBP_SET/CLEAR/POLL/QUERY	0xD2-0xD5	PTE 断点
EHWBP_*	0xE0-0xE3	VBAR extreme HWBP

MCP 工具

client/mcp_server.py 暴露 18 个 AI 工具给 Claude Code：

ping · list_processes · connect_process · read_memory · write_memory · scan_all · next_scan · get_scan_results · get_memory_regions · enum_modules · disassemble · read_pointer_chain · aob_scan · generate_aob_signature · read_integer · write_integer · set_data_breakpoint · clear_breakpoints · query_breakpoints · get_breakpoint_hits · get_process_info

配置 ~/.mcp.json：


{
  "mcpServers": {
    "shadow-ce": {
      "command": "python3",
      "args": ["/root/shadow/shadow_ce/client/mcp_server.py"]
    }
  }
}

已验证设备

OnePlus Ace 5 Pro (SM8750 Cortex-X925 @ 4.32GHz, kernel 6.6.89, Android 16, KernelSU)

许可证

GPL-2.0（内核模块继承 Linux 许可）