DOCSEARCHbyAlgolia
Submit Docs

Damru Android-Native Stealth Browser Automation Framework

repository·main·Indexed 42 days ago

https://github.com/akwin1234/damru

An Android-native stealth browser automation framework (version 0.1.0) using Redroid, Playwright, and CDP for web scraping, mobile QA testing, and anti-bot research. It employs a "Zero JS Injection" philosophy, spoofing fingerprints at the OS and binary levels rather than using detectable JavaScript. Features include a database of 155 real Android device profiles, custom WSL2 kernel support, and tools for baking Chrome APKs into Redroid images.

Tokens
57.4K
Snippets
193
Records
261
Agent score
56%

What's inside Damru

  1. What is Damru?

    main

    Damru is an open-source, Android-native stealth browser automation framework. Unlike desktop-based tools (like undetected-chromedriver) or JavaScript-injection plugins (like playwright-stealth), Damru runs a real Android OS via Redroid in Docker and applies fingerprint spoofing at the OS, binary, and Chrome DevTools Protocol (CDP) layers.

    This approach ensures that hardware profiles, GPU renderers, TLS stacks, and network behaviors match an authentic physical Android device without leaving any detectable JavaScript traces in the page context.

  2. Overview of Damru Python API entry points

    main

    Damru provides different entry points depending on your automation requirements:

    • AsyncDamru: The primary entry point for asynchronous automation.
    • Damru: A synchronous wrapper for standard blocking scripts.
    • DamruPool: Used for orchestration of high-throughput multi-container scraping.
    • damru.bypass: Provides advanced TLS/JA3 impersonation for bypassing edge-layer protections.

    For detailed class references and managed pooling, refer to the Damru Python API Reference. For available Android identities, see the Damru Device Profile Reference.

  3. Use Damru for Android-Native Stealth Automation

    main

    Damru is a native Android automation stack designed for containerized environments (specifically Redroid). Unlike standard tools that use JavaScript injection for stealth, Damru operates at the OS, Binary, and Protocol levels to remain invisible to anti-bot scripts.

    Key Constraints:

    • No Physical Devices: Damru is optimized for Redroid (Docker) and does not support physical Android phones. Attempting to use physical devices is unsupported and will be refused by auto-detection unless DAMRU_ALLOW_PHYSICAL=1 is set (use at your own risk).
    • Platform Support: The only officially supported native Linux target is Ubuntu 24.04 LTS. Other distributions may work with Docker, but reliability depends on kernel binderfs support.
    • MuMu Player: Support for MuMu Player is currently an experimental, non-functional beta. Use Redroid (Docker) for production or research.

  4. Understand Damru's Licensing and Commercial Use Policy

    main

    Damru is published under the PolyForm Noncommercial License 1.0.0. This means the project is free for personal, educational, and noncommercial research purposes, but requires a commercial license for any activity directed toward monetary compensation.

    Allowed (No Commercial License Required)

    • Personal noncommercial research.
    • Educational use.
    • Noncommercial security testing on systems you own or have authorization to test.
    • Noncommercial forks and pull requests that preserve license and attribution.

    Prohibited (Requires Written Permission/Commercial License)

    • Commercial Services: Selling Damru, hosted Damru access, managed scraping, botting, fingerprinting bypass, or automation services based on Damru.
    • Monetized Activity: Using Damru for customer work, SaaS, paid tools, paid consulting, or paid traffic operations.
    • Rebranding: Presenting Damru or derived works as an unrelated original project or removing original attribution/licenses.
    • Misleading Branding: Publishing repositories or assets that confuse users into believing they are official Damru releases.

    Commercial Licensing

    If you intend to use Damru for business use, SaaS, hosted services, enterprise deployments, or paid consulting, you must obtain a commercial license by contacting contact@damru.dev.

  5. Research Report: Android Virtualization Alternatives for Browser Fingerprint Stealth

    main

    This research report explores various Android virtualization methods for the purpose of achieving browser fingerprint stealth in automation. It evaluates how different virtualization approaches handle GPU fingerprinting, which is a critical factor for avoiding detection in web scraping and bot-detection research.

    Current Research Context:

    • Goal: Finding alternatives to redroid that provide better GPU fingerprint stealth.
    • Current Setup: redroid 14.0.0_64only-latest running in Docker/WSL2 using SwiftShader GPU, which causes detectable fingerprint anomalies.
    • Hardware Environment: NVIDIA RTX 3070 Ti Laptop GPU, Windows 11, WSL2 Ubuntu.

  6. Overview of Damru Core Modules

    main

    The damru/ core library is composed of several specialized modules that handle different stages of the automation lifecycle:

    • async_core.py & core.py: Main entry points using Async and Sync context managers to manage the connection flow.
    • devices.py: A database of 155 real Android devices containing hardware specs, screen resolutions, GPU renderers, and build fingerprints.
    • root.py: Executes Layer 1 (OS) and Layer 2 (Binary) stealth patches via ADB shell (e.g., modifying build.prop, pushing GPU .so files, managing iptables).
    • cdp.py: Manages the Chrome DevTools Protocol connection and port forwarding from the Android emulator to localhost.
    • chrome.py: Manages the Chrome lifecycle, including clearing app data, dismissing the First Run Experience (FRE), and applying Layer 4 stealth patches to the Preferences JSON file.
    • proxy.py: Maps Timezones, Geolocation, and Locales to match the physical origin of a provided proxy.
    • pool.py: Provides DamruPool and DamruPoolSync for scaling concurrent operations across multiple Docker containers.
    • cli.py: Provides user-facing commands for setup, preflight checks, image/APK management, and media capture (screenshots/video).
    • profile_apply.py: A helper for forcing a specific device identity onto an existing rooted ADB worker.
    • playwright_patch/: Contains crPage.js modifications to neutralize Playwright's default behavior and prevent CDP target discovery leaks.

  7. The GPU Fingerprinting Challenge in Android Virtualization

    main

    A core challenge in Android-native stealth browser automation is that no current virtualization solution provides true mobile GPU hardware emulation (such as Adreno or Mali) on x86_64 architecture.

    When running Android on x86_64 hardware, developers face three primary GPU fingerprinting scenarios:

    1. Software Rendering: Using SwiftShader or llvmpipe. These produce desktop-like fingerprints that are easily detectable as non-mobile.
    2. Host GPU Passthrough: Passing through the host GPU (e.g., NVIDIA, Intel, or AMD). This exposes the desktop GPU identity, which is a major fingerprinting signal.
    3. Native ARM Hardware: Requires actual ARM-based hardware to support native mobile GPU (Adreno/Mali) signatures.

    Key Finding: Because mobile GPUs are ARM-specific SoCs, x86_64 virtualization cannot hardware-emulate them without extreme performance penalties. Cuttlefish with gfxstream is noted as a marginal improvement over redroid, but it still does not solve the core mobile GPU fingerprint challenge on x86_64 hardware.

  8. How Damru achieves stealth without JavaScript injection

    main

    Most stealth plugins use JavaScript Object.defineProperty overrides, which are easily detected by inspecting .toString() outputs or prototype chains.

    Damru avoids this by patching at lower levels:

    • OS Level: System properties via resetprop.
    • Binary Level: GPU drivers (Vulkan/GLES .so).
    • Syscall Level: Using libfakemem.so via LD_PRELOAD.
    • Protocol Level: Chrome DevTools Protocol (CDP).

    This results in zero JavaScript fingerprinting in the browser context.

  9. Detect WSL and Netfilter capabilities

    main

    When building a framework to manage Redroid, use the following logic to detect if the environment is constrained by WSL2 or missing NAT capabilities. This allows the framework to automatically switch to a 'safe' single-worker mode.

    1. Detect WSL: Check uname -r or /proc/version for microsoft-standard-WSL.
    2. Probe NAT: Attempt to list NAT rules. If it fails, the environment is no-NAT.
    3. Probe Kernel Modules: Check /proc/config.gz for CONFIG_IP_NF_FILTER, CONFIG_IP_NF_NAT, CONFIG_NETFILTER_XT_MATCH_ADDRTYPE, and CONFIG_BRIDGE_NETFILTER.

    If these checks fail, set an internal flag kernel_nat_supported = false and enforce single-worker mode with host networking.

    # Detect if NAT is available
if ! iptables -t nat -L -n >/dev/null 2>&1; then
    # mark environment as no-NAT
fi

  11. How Damru achieves 'Zero JS' stealth

    main

    Unlike traditional tools that use JavaScript injection (e.g., Object.defineProperty) which are easily detected by checking .toString() on functions, Damru uses a multi-layered approach to spoof device identity at the OS, Binary, and CDP levels. This ensures that functions remain entirely native and leave no detectable traces.

    The 8 Layers of Stealth:

    1. Android System Props: Uses resetprop via ADB to modify build.prop (e.g., ro.product.model).
    2. GPU Binary Patching: Physically patches Vulkan/GLES .so binaries to replace generic drivers (like SwiftShader) with real ones (like Adreno).
    3. Syscall Interception: Uses libfakemem.so via LD_PRELOAD to intercept sysinfo and sysconf calls, spoofing RAM and CPU.
    4. Deep CDP Protocol Overrides: Uses Chrome DevTools Protocol to spoof hardware concurrency and touch points at the C++ engine level.
    5. Thread & Worker Interception: Uses Target.setAutoAttach to ensure all Workers (Dedicated, Shared, Service) inherit hardware overrides.
    6. Chrome Preferences & Flag Patching: Modifies Chrome Preferences and launch flags to randomize TLS cipher suites (~184 JA3 variants) and locales.
    7. OS-Level Evasions: Uses Android iptables to block WebRTC leaks and disable IPv6.
    8. Display & Density Spoofing: Uses Android Window Manager (wm size/density) to ensure physically accurate screen dimensions and DPI.

  12. Platform Support and Requirements

    main

    Damru requires specific kernel configurations to support Redroid multi-container pools and networking.

    • Supported OS: Ubuntu 24.04 LTS (Native Linux or WSL2 with Damru's bundled WSL kernel).
    • Unsupported OS: Debian 13 (The stock Debian kernel lacks CONFIG_ANDROID_BINDERFS, which prevents Redroid multi-container support).
    • Core Technology: Uses a "Zero JS Injection" approach. Spoofing is applied at the OS level (resetprop, iptables), binary level (Vulkan/GLES patching), and protocol level (CDP) rather than using Object.defineProperty hacks.