Skip to content

README.md

Latest commit

 

History

History
216 lines (175 loc) · 12.3 KB

README.md

File metadata and controls

216 lines (175 loc) · 12.3 KB
Raw

HuntMemory (HMem) 🔍⚡

Documentation CI Build License: GPL v3 Platform Architecture Rust Kotlin Jetpack Compose

HuntMemory (HMem) is a high-performance process memory editor and scanner designed exclusively for Android 10+ (API 29+) on ARM64 (arm64-v8a / aarch64-linux-android).

The project pairs a modern Jetpack Compose floating overlay UI with an ultra-fast Rust 2024 scanning core accelerated by ARM NEON SIMD, interfacing directly with the Linux kernel via the HMKPM (KernelPatch Module).

📱 Target Device Requirements

To run HuntMemory on your device:

  1. Architecture: Physical 64-bit ARM device (arm64-v8a / aarch64).
  2. Android Version: Android 10.0+ (API level 29 or higher).
  3. Kernel Version: Kernel Linux (4.14+).
  4. Root Environment:
  • Magisk 26+, KernelSU, or APatch with root granted.
  1. KernelPatch & HuntMemory-KPM(HMKPM):
  • Device kernel patched with KernelPatch.
  • Or Device kernel patched with KPM-Manager.
  • HMKPM loaded to enable direct MMU memory manipulation via the SYS_GETRESUID syscall hook.
  1. Overlay Permission:
  • Grant "Display over other apps" (SYSTEM_ALERT_WINDOW) when prompted on the initial launch.

🏛️ System Architecture

HuntMemory isolates presentation, privileged operations, and native computation across distinct security domains:

graph TD
    subgraph UI_Space ["Android App (Userspace - App Process)"]
        UI["Overlay UI (Jetpack Compose)"]
        VK["Virtual Keyboard (QWERTY / NUM / HEX)"]
        Canvas_UI["LuaCanvasOverlay (GPU / DrawScope)"]
        Tabs["Tabs (Process / Scan / Table / Lua / Settings)"]
        Conn["HMemServiceConnection (IPC Client)"]
    end

    subgraph Root_Space ["Root Service (Userspace - UID 0 via libsu)"]
        RS["HMemService (RootService AIDL)"]
        NB["NativeBridge (JNI @FastNative)"]
        subgraph Rust_Engine ["Rust Engine (libhmem_jni.so)"]
            SCAN["Scanner (ARM NEON SIMD)"]
            EDIT["Editor & FreezeEngine (Worker Thread)"]
            SCRIPT["Lua 5.4 Engine (mlua + gg.* API)"]
            MAPS["Maps & Pagemap Streaming Parser"]
            KPMC["HMKPM Client (mlock + Syscall Hook)"]
        end
    end

    subgraph Kernel_Space ["Kernel Space (KernelPatch Module)"]
        KPM["HMKPM (KernelPatch Module)"]
        PGD["MMU Page Table Walking (task->mm->pgd)"]
        MEM["Target Process Physical RAM"]
    end

    UI --> Conn
    VK --> UI
    Tabs --> UI
    Conn -- "AIDL / Binder IPC" --> RS
    RS --> NB
    NB --> Rust_Engine
    SCRIPT -. "Canvas & UI Callbacks" .-> Canvas_UI
    KPMC -- "Syscall getresuid (Magic 0x00484D4B504D)" --> KPM
    KPM --> PGD
    PGD --> MEM
Loading

For complete technical specifications, see the System Architecture Documentation.

✨ Key Features

  • 🎯 SIMD-Accelerated Memory Scanning:

    • ARM NEON Intrinsics: Vectorized memory evaluation processing up to 16 bytes per cycle.
    • Multi-Type & Auto Scan: Search across multiple integer and floating-point types (Byte, Short, Int, Long, Float, Double, Float16) simultaneously.
    • Array of Bytes (AoB) Signature Scan: Discover complex byte sequences with wildcard masks (?, ??, *).
    • Range & Group Scanning: Locate values within bounds or discover structured variables grouped closely in memory (spec:distance).
    • Unknown & Differential Scans: Track dynamic values with Increased, Decreased, Changed, Unchanged, and delta filters.

  • 📜 Lua 5.4 Scripting & GameGuardian Compatibility:

    • Native hmem.* & gg.* Support: Direct compatibility for running existing GameGuardian scripts.
    • Dynamic Overlay Menus & Event Loop: Create custom floating cheat menus, prompts, and responsive button/toggle handlers directly in Lua.
    • On-Screen Canvas Overlay (ESP/HUD): Hardware-accelerated 2D lines, bounding boxes, circles, and text rendering overlaying target games.

  • 🔐 Obscured & Scientific Number Support:

    • XOR-Keypair Decryption: Native detection and editing for Anti-Cheat Toolkit (ACTk) obscured types (ObscuredInt, ObscuredFloat, ObscuredDouble, ObscuredLong).
    • BigDouble / Scientific Structs: Parse and modify scientific mantissa/exponent structures used by incremental engines (BreakInfinity / Decimal).

  • 🗺️ Comprehensive Memory Region Filtering:

    • Automatically classifies memory mappings: Anonymous [A], C++ Alloc [CA], C++ BSS [CB], C++ Data [CD], C++ Heap [CH], Java Heap [JH], Stack [S], Ashmem [AS], and Libraries [XA].
    • Pagemap residency verification (PM_PRESENT / PM_SWAP) and zram swap awareness.

  • ✏️ Real-Time Memory Editing & Freeze Engine:

    • Single and batch memory writing with physical RAM page validation.
    • Low-overhead native background thread maintaining locked values at configurable intervals (default: 100ms).

  • 📱 Modern Floating Overlay UI:

    • Fully resizable and movable overlay built with Jetpack Compose Material 3.
    • Integrated Contextual Virtual Keyboard: Custom QWERTY, Numeric, and Hexadecimal input without triggering system IME displacements.

📚 Technical Documentation

Deep-dive documentation for all core subsystems is available online at yervant7.github.io/HuntMemory or in the docs/ directory:

📂 Repository Structure

HuntMemory/
├── AGENTS.md                                   # Project rules and architectural guidelines
├── LICENSE                                     # GNU General Public License v3.0
├── README.md                                   # Project overview and quick start
├── docs/                                       # In-depth technical documentation
│   ├── architecture.md                         # System architecture and multi-tier design
│   ├── building.md                             # Toolchain prerequisites and build guide
│   ├── index.md                                # Documentation homepage & portal
│   ├── kernel-protocol.md                      # HMKPM kernel communication protocol
│   ├── lua-scripting.md                        # Lua 5.4 scripting & Canvas overlay API
│   ├── memory-scanning.md                      # SIMD scanning engine and data types
│   └── requirements.txt                        # MkDocs documentation build requirements
├── app/
│   ├── build.gradle.kts                        # Android build script & cargo-ndk automation
│   ├── src/main/
│   │   ├── AndroidManifest.xml                 # App manifest & permissions
│   │   ├── aidl/com/yervant/huntmem/
│   │   │   └── IHMemService.aidl               # RootService AIDL IPC contract
│   │   ├── hmem/                               # Rust core workspace
│   │   │   ├── Cargo.toml                      # Workspace configuration
│   │   │   └── hmem_jni/
│   │   │       ├── Cargo.toml                  # Native dependencies
│   │   │       └── src/
│   │   │           ├── lib.rs                  # JNI boundary & session manager
│   │   │           ├── kpm.rs                  # HMKPM kernel client (syscall 148)
│   │   │           ├── scanner.rs              # NEON SIMD memory scanner
│   │   │           ├── editor.rs               # Memory editor & freeze engine
│   │   │           ├── script.rs               # Lua 5.4 engine & GameGuardian bridge
│   │   │           ├── maps.rs                 # /proc/[pid]/maps parser & classifier
│   │   │           ├── pagemap.rs              # /proc/[pid]/pagemap resident page reader
│   │   │           ├── types.rs                # C-ABI structs and supported data types
│   │   │           └── logger.rs               # Android logcat bridge
│   │   └── kotlin/com/yervant/huntmem/
│   │       ├── HuntMemApp.kt                   # Application entry point
│   │       ├── backend/                        # Root service, IPC & native bridge
│   │       │   ├── NativeBridge.kt             # @FastNative JNI wrappers
│   │       │   ├── HMemService.kt              # libsu RootService implementation
│   │       │   ├── HMemServiceConnection.kt    # Service lifecycle manager
│   │       │   ├── MemoryEngine.kt             # High-level memory scan orchestrator
│   │       │   ├── MemoryScanManager.kt        # Scan session manager
│   │       │   └── ShellProcessProvider.kt     # Process discovery & enumeration
│   │       └── ui/                             # Jetpack Compose UI
│   │           ├── MainActivity.kt             # Setup & permission verification
│   │           ├── OverlayService.kt           # Floating overlay lifecycle service
│   │           ├── OverlayUI.kt                # Main Compose overlay container
│   │           ├── keyboard/                   # Integrated virtual keyboard
│   │           ├── overlay/
│   │           │   ├── LuaCanvasOverlay.kt     # Real-time GPU Canvas overlay renderer
│   │           │   └── tabs/                   # UI tabs (Process, Scan, Table, Lua, Settings)
│   │           │       ├── AddressTableTab.kt  # Frozen & saved address manager
│   │           │       ├── LuaScriptTab.kt     # Lua script editor & console
│   │           │       ├── LuaUiBridge.kt      # Dynamic UI & Canvas dispatcher
│   │           │       ├── MemoryScanTab.kt    # Memory scanner & filter UI
│   │           │       └── ProcessSelectionTab.kt # Process selector
│   │           └── theme/                      # Material 3 styling & typography

🛠️ Quick Build Guide

Prerequisites

  • Android SDK: compileSdk = 37, minSdk = 29, NDK 29.0.14206865
  • JDK: Java 21 LTS
  • Rust: Rust 2024 Edition (rustup target add aarch64-linux-android)
  • cargo-ndk: cargo install cargo-ndk

Compiling the APK

Gradle automatically builds the Rust native shared library (libhmem_jni.so) during the build lifecycle:

# Debug build
.\gradlew assembleDebug

# Release build
.\gradlew assembleRelease

For detailed instructions, refer to the Building Guide.

📜 License

HuntMemory is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.