DOCSEARCHbyAlgolia
Submit Docs

eDBG Documentation

repository·main·Indexed 21 days ago

https://github.com/shinoleah/edbg

A lightweight, eBPF-based CLI debugger for Android ARM64 systems (kernel 5.10+). It provides a GDB-like interface for attaching to running processes with high anti-detection capabilities by avoiding ptrace. Key features include software, hardware, and virtual offset breakpoints, memory inspection, register viewing, and a specialized MCP (Model Context Protocol) mode for programmatic interaction with AI agents or external controllers.

Tokens
11.1K
Snippets
28
Records
51
Agent score
69%

What's inside eDBG

  1. Understand eDBG MCP runtime behavior

    main

    When running in MCP mode, eDBG follows specific operational rules:

    • Mode Flags: The --mcp flag automatically forces -prefer upprobe -show-vertual.
    • Lifecycle:
      • eDBG starts in standby mode and does not launch the target app automatically.
      • There is no automatic startup breakpoint.
      • The first required step is to call attach(package, library) to select a target.
    • Tool Constraints:
      • Once a target is selected but before the app is launched, you can only use: attach, break, info_break, info_file, breakpoint management, and run.
      • The break tool always treats the offset as a virtual offset (mapping internally to vbreak).
    • Execution:
      • run launches the attached target app using am start.
      • continue blocks execution until a breakpoint is hit.
      • quit resets the MCP context to the initial standby state but does not stop the MCP server.

  2. Understand eDBG MCP mode behavior

    main

    When running with the --mcp flag, eDBG operates in a specialized mode optimized for AI interaction.

    Key Characteristics

    • Debugging Constraints: It forces -prefer uprobe -show-vertual mode. This means hardware breakpoints and single-step functionality are disabled.
    • Lifecycle:
      • It starts in a standby state without a target app or pre-set breakpoints.
      • It does not automatically start the target application.
      • run executes am start to launch the currently attached target.
      • quit clears the current MCP context and returns to the standby state but does not exit the MCP server process.
    • Target Selection: In the initial standby state, you must call attach(package, library) to select a target.
    • Available Operations (Standby/Pre-launch): While a target is selected but the app is not yet running, only the following are permitted: attach, break, info_break, info_file, breakpoint management, and run.
    • Breakpoint Logic: The break command exposed to the AI always uses virtual offsets (equivalent to vbreak).
    • Execution: continue will block and wait until a breakpoint is actually hit before returning.

  3. Run eDBG with initial breakpoints

    main

    To start the debugger and immediately set breakpoints at specific offsets, use the following command structure:

    ./eDBG -p <package_name> -l <library_name.so> -b <offset_list>

    Arguments:

    • -p: Target application package name.
    • -l: Target dynamic library name.
    • -b: Initial breakpoint offset list (comma-separated).

    Example: Starting debugging for a package with a breakpoint at offset 0x123456 in libnative.so:

    ./eDBG -p com.example.app -l libnative.so -b 0x123456
    ./eDBG -p com.pakcage.name -l libname.so -b 0x123456

  4. Build the edbg-mcp-install utility

    main

    The installer can be built from source using the provided Makefile. The build process generates binaries for several desktop architectures (darwin, linux, windows for both amd64 and arm64) and places them in the bin/ directory.

    Use the following commands to build:

    • make -f Makefile_installer current: Builds the current target.
    • make -f Makefile_installer all: Builds all supported targets.
    make -f Makefile_installer current
make -f Makefile_installer all

  5. Install and Setup eDBG on Android

    main

    eDBG is a lightweight eBPF-based CLI debugger for Android. It requires a ROOT environment (KernelSU is recommended) and an ARM64 architecture with a kernel version of 5.10+.

    To install:

    1. Download the latest release.
    2. Push the binary to /data/local/tmp on your device.
    3. Grant execution permissions via ADB.

    Note: eDBG does not actively launch the target app; it can only attach to an already running process. However, because it uses a file+offset breakpoint mechanism, you must use the -b flag to set initial breakpoints at valid locations during startup to ensure successful debugging.

    adb push eDBG /data/local/tmp
adb shell
su
chmod +x /data/local/tmp/eDBG

  6. Run eDBG in MCP mode on an Android device

    main

    To use eDBG as an MCP server, you must push the binary to your device, run it with the --mcp flag, and forward the port to your host.

    1. Push and execute eDBG:

      • Push the binary to /data/local/tmp.
      • Run with su privileges using the --mcp flag.
      • By default, it listens on port 19810. You can specify a different port using --mcp-port.

    2. Forward the port: Use adb forward to map the device port to your host so the AI client can reach the server.

    Default MCP URL: http://127.0.0.1:19810/mcp

    # Push and start eDBG
adb push eDBG /data/local/tmp
adb shell
su
chmod +x /data/local/tmp/eDBG
./data/local/tmp/eDBG --mcp

# Forward the port on the host
# (Run this from your host machine)
adb forward tcp:19810 tcp:19810

  7. Build the edbg-mcp-install tool

    main

    The edbg-mcp-install tool can be built from the repository using the provided Makefile_installer. The build process generates binaries for multiple desktop platforms.

    Build Commands

    To build the current version:

    make -f Makefile_installer current

    To build all supported versions:

    make -f Makefile_installer all

    Supported Platforms

    Output binaries are placed in the bin/ directory and include:

    • darwin_amd64 / darwin_arm64 (macOS)
    • linux_amd64 / linux_arm64 (Linux)
    • windows_amd64 / windows_arm64 (Windows)
    make -f Makefile_installer current

  8. Set up eDBG MCP for AI Clients

    main

    eDBG MCP allows AI clients to interact with a mobile device via an HTTP MCP service. The setup involves running eDBG on the mobile device in --mcp mode and using the edbg-mcp-install tool on your host machine to configure your AI client.

    Setup Steps

    1. Download: Get the latest release of eDBG and the corresponding platform installer from the Releases page.
    2. Install MCP Tool: Run the installer on your host machine:
      ./edbg-mcp-install --install
    3. Deploy to Mobile: Push eDBG to the device and run it in MCP mode:
      adb push eDBG /data/local/tmp
adb shell
su
chmod +x /data/local/tmp/eDBG
./data/local/tmp/eDBG --mcp
    4. Port Forwarding: Forward the default MCP port (19810) from the device to your host:
      adb forward tcp:19810 tcp:19810

    Note: If you use a custom port, specify it with --mcp-port on the device and update the installer using --url http://127.0.0.1:<PORT>/mcp.

    ./edbg-mcp-install --install

abd push eDBG /data/local/tmp
adb shell
su
chmod +x /data/local/tmp/eDBG
./data/local/tmp/eDBG --mcp

abd forward tcp:19810 tcp:19810

  9. Compile eDBG from Source

    main

    To build eDBG for ARM64 on an x86 Linux environment, follow these steps:

    1. Install Dependencies:
      sudo apt-get update
sudo apt-get install golang-1.18 clang-14
    2. **Set Environment Variables**:
   ```shell
export GOPROXY=https://goproxy.cn,direct
export GO111MODULE=on
    1. NDK Setup: Download the Android NDK and ensure NDK_ROOT is correctly set in build_arm.sh.
    2. Build:
      git clone --recursive https://github.com/ShinoLeah/eDBG.git
./build_env.sh
./build_arm.sh
    ./build_env.sh
./build_arm.sh

  10. Start the eDBG Debugger

    main

    To start debugging, run the eDBG binary with the target package name, shared library, and optional initial breakpoints. Note that eDBG can attach to running processes but does not automatically launch apps.

    Basic Command

    ./eDBG -p <package_name> -l <library_name.so> -b <breakpoint_addresses>

    CLI Options

    OptionDescription
    -pTarget app package name
    -lTarget shared library name
    -bInitial breakpoints (comma-separated list)
    -tThread name filter for eBPF (comma-separated)
    -iLoad configuration from a specified file
    -sSave configuration to an input file
    -oSave configuration to a specified file
    -mcpStart the HTTP MCP server on the device
    -mcp-portMCP listening port (default: 19810)
    -preferChoose between uprobe or hardware
    -hide-registerDisable register info display on breakpoints
    -hide-disassembleDisable assembly info display on breakpoints
    -disable-colorDisable colorful output
    -show-vertualShow virtual addresses by default
    ./eDBG -p com.package.name -l libname.so -b 0x123456

  11. Install the eDBG MCP tool on your host

    main

    To enable Model Context Protocol (MCP) support in your AI clients, you must install the edbg-mcp-install utility on your host machine. This utility writes the necessary MCP configurations into your AI clients' configuration files.

    1. Download the latest release from the eDBG Releases page.
    2. Run the installer with the --install flag.
    ./edbg-mcp-install --install

  12. Compile eDBG for Android

    main

    eDBG is cross-compiled on x86 Linux using the Android NDK.

    Linux Setup:

    1. Install dependencies:
      sudo apt-get update
sudo apt-get install golang-1.18 clang-14
export GOPROXY=https://goproxy.cn,direct
export GO111MODULE=on
    2. Configure `build_arm.sh` with your `NDK_ROOT` path.
3. Build:
   ```shell
git clone --recursive https://github.com/ShinoLeah/eDBG.git
./build_env.sh
./build_arm.sh

    macOS Setup: Use the provided Makefile_macOS, which uses Docker to run bpftool:

    make -f Makefile_macOS NDK_ROOT=$HOME/Library/Android/sdk/ndk/<version> clean all
    make -f Makefile_macOS NDK_ROOT=$HOME/Library/Android/sdk/ndk/27.0.12077973 clean all