[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82794":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":42,"readmeContent":43,"aiSummary":44,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":45,"discoverSource":46},82794,"damru","akwin1234\u002Fdamru","akwin1234","Damru is the ultimate stealth Android browser automation framework. Unlike tools that use detectable JS injections,   Damru achieves true undetectability via native C++ overrides, OS-level root prop spoofing, and GPU binary patching.   Designed to bypass ALL CDNs, and score 100% on CreepJS using Redroid and Playwright. ","",null,"Python",140,20,3,1,0,2,55,83,33,3.97,"Other",false,"main",[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"android-automation","android-automation-bot","anti-bot","bot-detection","browser-automation","browser-automation-studio","browser-automation-toolkit","fingerprinting","mobile-automation","playwright","playwright-python","stealth","stealth-automation","stealth-bot","stealth-browser","web-scraping","2026-06-12 02:04:28","\u003Cdiv align=\"center\">\n  \u003Cimg src=\"logo.svg\" alt=\"Damru Logo\" width=\"200\" height=\"200\">\n  \u003Ch1>Damru\u003C\u002Fh1>\n  \u003Cp>\u003Cstrong>The Apex Predator of Android Browser Automation\u003C\u002Fstrong>\u003C\u002Fp>\n  \u003Cp>\u003Cem>The world's first open-source framework for natively modded Android browser automation.\u003C\u002Fem>\u003C\u002Fp>\n  \u003Cp>High-performance, ultra-stealth browser automation framework designed for web scraping and botting at scale.\u003C\u002Fp>\n\n  [![Python Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10%2B-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https:\u002F\u002Fpython.org)\n  [![Playwright](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplaywright-1.40--1.59-green.svg?style=for-the-badge&logo=playwright&logoColor=white)](https:\u002F\u002Fplaywright.dev\u002Fpython\u002F)\n  [![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPlatform-WSL2%20%7C%20Linux-lightgrey.svg?style=for-the-badge&logo=linux&logoColor=white)]()\n  [![License: PolyForm Noncommercial 1.0.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-PolyForm%20Noncommercial%201.0.0-red.svg?style=for-the-badge)](https:\u002F\u002Fpolyformproject.org\u002Flicenses\u002Fnoncommercial\u002F1.0.0)\n\n  \u003Cp>\n    \u003Cstrong>Community:\u003C\u002Fstrong>\n    \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FGsxFdjdrT\">Discord server\u003C\u002Fa> recommended\n    · \u003Ca href=\"https:\u002F\u002Ft.me\u002FTheCPAElite\">Telegram personal\u003C\u002Fa>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n\u003Cbr\u002F>\n\n> **Damru** leverages rooted Android emulators (like Redroid in Docker) via ADB to achieve undetectable automation. Whether you are bypassing modern WAFs (like Cloudflare Turnstile) or scoring 100% on CreepJS, Damru provides an impenetrable disguise.\n\n> [!WARNING]\n> **Project Status: Beta**\n> This project is currently in a **Beta** state. While it has been verified as 100% stable and fully functional on the local systems of the developers who built it, it requires further testing across diverse environments and hardware configurations. We welcome feedback and issue reports!\n\n---\n\n## Table of Contents\n\n- [Core Features](#core-features)\n- [Why Damru is Better](#why-damru-is-better-than-the-rest)\n- [Proof of Stealth: Benchmarks](#proof-of-stealth-benchmark-comparisons)\n- [Verification Proof](docs\u002FPROOF.md)\n- [Architecture: The 8 Layers of Stealth](#architecture-the-8-layers-of-zero-js-stealth)\n- [Project Structure](#project-structure)\n- [Python API Documentation](docs\u002FPYTHON_API.md)\n- [Device Profiles](docs\u002FDEVICE_PROFILES.md)\n- [Viewer, Screenshots, and Video](docs\u002FVIEWER.md)\n- [WSL2 Kernel Requirements](docs\u002FWSL_KERNEL.md)\n- [Download Custom OS Image](#download-custom-os-image)\n- [Quickstart Guide](#first-time-user-deployment-guide-wsl2--linux)\n- [Usage & Examples](#usage--examples)\n- [Redroid vs MuMu Player](#platform-recommendation-redroid-vs-mumu)\n- [Testing](#testing-your-setup)\n- [Roadmap](#the-big-plan-roadmap)\n- [FAQ](#frequently-asked-questions)\n- [Legal Disclaimer](#mandatory-legal-disclaimer--ethical-use-notice)\n\n---\n\n## Platform Recommendation: Redroid vs MuMu\n\nWhile Damru technically lists multiple environments, **Redroid (Docker)** is the only officially supported and functional path.\n\n| Platform | Status | Stealth Level | Stability | Recommendation |\n| :--- | :--- | :--- | :--- | :--- |\n| **Redroid (Docker)** | **Production-Ready** | **Absolute** | **High** | **Highly Recommended** |\n| **MuMu Player** | **Unfinished \u002F Beta** | Moderate | Low | **Non-functional \u002F Not Recommended** |\n| **Physical Devices** | **NOT SUPPORTED** | N\u002FA | N\u002FA | **DO NOT USE** |\n\n> [!CAUTION]\n> **Physical Device Warning**\n> Damru is designed strictly for containerized environments (Redroid). **It does not support physical Android devices.** Do not attempt to run Damru against your personal phone. If you choose to use a spare rooted device, you do so at your own risk. Damru's low-level OS patches and binary injections may brick or destabilize physical hardware.\n\n**Why Redroid?**\nDamru's most advanced stealth layers - including native GPU binary patching and OS-level `iptables` hooks-are optimized for the Redroid kernel. It provides a more stable environment for multi-container pools and is significantly more undetectable by modern anti-bot heuristics. MuMu Player support is currently an experimental, unfinished, and non-functional beta feature.\n\n---\n\n## Core Features\n\n*   **Zero JS Injection**: All spoofing is executed at the OS, Binary, and CDP levels. No brittle `Object.defineProperty` hacks.\n*   **Massive Device Database**: Built-in profiles for 49 real Android devices (Samsung, Pixel, Xiaomi, OnePlus, Nothing, Honor, Vivo, POCO, etc.) with realistic hardware specifications.\n*    **Display & Resolution Spoofing**: Natively overrides screen dimensions and DPI via Android's Window Manager (`wm size\u002Fdensity`) for physical accuracy.\n*    **Browser Version & Client Hints Randomization**: Dynamically selects from a database of verified Chrome versions and generates perfectly accurate `sec-ch-ua` Client Hints, including Chromium GREASE brand permutations.\n*    **TLS\u002FJA3 Randomization**: Generates ~184 unique TLS fingerprints from a single binary by dynamically toggling cipher suites and experimental flags.\n\n*   **Auto Image Management**: Automatically pulls and tags the required Redroid Docker images if the custom baked image is missing.\n*   **Font & Voice Randomization**: Installs custom TTS engines and extra system fonts, randomizing them per session.\n*   **Hardware Status Spoofing**: Fakes battery levels, charging status, and even audio sample rates (48kHz) to mirror real mobile hardware behavior.\n*   **Hardware Overrides**: Spoofs CPU cores, RAM (via syscall hooks), and touch points (e.g., 5-point touch) directly via native OS patching and CDP.\n*   **Network & DNS Stealth**: Faithfully fakes mobile network conditions and forces resolution through proxy-level ISP DNS to pass \"DNS Leak\" and \"Targeted DNS\" checks.\n*   **CDN & Anti-Bot Bypass**: Out-of-the-box native bypass for modern WAFs (like Cloudflare Turnstile, CDN TLS) and advanced behavioral detection systems.\n\n---\n\n## Why Damru is Better Than the Rest\n\nWe spent significant time modifying and testing popular desktop-first solutions like **Camoufox**, **Fingerprinting Chromium**, and various Playwright stealth patches to work on mobile - but nothing reached the level of stability and undetectability achieved by this project. \n\nThe botting landscape is littered with tools that *used* to work: `puppeteer-stealth`, `undetected-chromedriver`, and various anti-detect browsers. Here is why they fail today, and why Damru succeeds:\n\n| Feature | Legacy Tools (`puppeteer-stealth`, etc.) | Damru |\n| :--- | :--- | :--- |\n| **Spoofing Method** | **JavaScript Injection** (`Object.defineProperty`). Leaves massive detectable traces. | **Native Overrides**. Modifies C++ engine via CDP, patches binaries, edits OS props. |\n| **JS Leakage** | Anti-bots check `.toString()` on functions. Injected JS is caught instantly. | **Zero JS Injected**. Functions remain entirely native. |\n| **Hardware Emulation** | Fakes `navigator.hardwareConcurrency` via JS. Fails worker tests. | **C++ CDP Override**. Changes the main-page value at the Chromium engine level; worker targets are handled best-effort through CDP auto-attach. |\n| **GPU Fingerprint** | WebGL spoofing via JS wrapping. Leaks real GPU via extensions. | **Binary Patching**. Physically patches the `.so` Vulkan\u002FGLES driver files on Android. |\n| **Physical Memory** | Fakes `deviceMemory` via JS. Easily caught by timing or syscall checks. | **Syscall Hooks**. Uses `libfakemem.so` to intercept `sysinfo` calls via `LD_PRELOAD`. |\n| **Worker Stealth** | Workers often leak the real hardware concurrency of the host. | **Worker Interception**. Uses CDP `Target.setAutoAttach` to force overrides on all Threads\u002FWorkers. |\n| **TLS\u002FJA3 Hash** | Fixed TLS fingerprint based on the Chrome binary version. | **TLS Randomization**. Produces ~184 unique JA3 hashes via dynamic cipher blacklisting. |\n| **Screen Dimensions** | Viewing desktop Chrome as mobile via viewport scaling (leaks real screen size). | **OS-Level Display**. Modifies Android `wm size\u002Fdensity` natively. |\n| **Network Identity** | Frequently leaks WebRTC private IPs and IPv6 fingerprints. | **OS-Level IP Tables**. Blocks WebRTC leaks and IPv6 at the Android kernel level. |\n| **Mobile Emulation** | Desktop Chrome pretending to be mobile via viewport scaling. | **Real Android OS**. Runs inside Redroid (Android 14) or MuMu Player. It *is* mobile. |\n\n### Proof of Stealth: Benchmark Comparisons\n\nWe regularly test Damru against the hardest anti-bot systems in the industry. These results are reproducible using the built-in benchmark suite (`python -m damru benchmark`) or the comprehensive functional test suite (`python example.py`).\n\nFresh Ubuntu\u002FWSL verification proof is tracked in [docs\u002FPROOF.md](docs\u002FPROOF.md). The current sanitized Ubuntu VPS proof assets include:\n\n- [Summary screenshot](docs\u002Fassets\u002Fproof\u002Fubuntu-proof-summary.png)\n- [Android screen recording](docs\u002Fassets\u002Fproof\u002Fubuntu-redroid-proof.mp4)\n- Individual site proof screenshots: [Amazon](docs\u002Fassets\u002Fproof\u002Fsites\u002Famazon.png), [Foot Locker \u002F DataDome target](docs\u002Fassets\u002Fproof\u002Fsites\u002Fdatadome-footlocker.png), [Fingerprint Pro](docs\u002Fassets\u002Fproof\u002Fsites\u002Ffingerprint-pro.png), [Sannysoft](docs\u002Fassets\u002Fproof\u002Fsites\u002Fsannysoft.png), and [CreepJS](docs\u002Fassets\u002Fproof\u002Fsites\u002Fcreepjs.png)\n- [Sanitized site proof metadata](docs\u002Fassets\u002Fproof\u002Fsites\u002Fproof-sites.json)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fubuntu-proof-summary.png\" alt=\"Damru Ubuntu VPS proof\" width=\"720\">\n\u003C\u002Fp>\n\n#### Screenshot Proof Gallery\n\n| Fingerprint Pro | CreepJS |\n| :---: | :---: |\n| \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fsites\u002Ffingerprint-pro.png\" alt=\"Fingerprint Pro proof\" width=\"360\"> | \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fsites\u002Fcreepjs.png\" alt=\"CreepJS proof\" width=\"360\"> |\n\n| Sannysoft | Foot Locker \u002F DataDome target |\n| :---: | :---: |\n| \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fsites\u002Fsannysoft.png\" alt=\"Sannysoft proof\" width=\"360\"> | \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fsites\u002Fdatadome-footlocker.png\" alt=\"Foot Locker DataDome proof\" width=\"360\"> |\n\n| Amazon |\n| :---: |\n| \u003Cimg src=\"docs\u002Fassets\u002Fproof\u002Fsites\u002Famazon.png\" alt=\"Amazon proof\" width=\"520\"> |\n\n| Target Anti-Bot | Standard Playwright | Typical Stealth Plugins | Damru |\n| :--- | :--- | :--- | :--- |\n| **CreepJS (Trust)** | 0% (Trash) | ~45% (High Lies) | **85%+ (0% Lies, Top Stealth)** |\n| **BrowserScan** | Fails Hardware\u002FOS | Fails WebGL\u002FFonts | **Passes 100% OS\u002FHardware\u002FWebRTC** |\n| **Sannysoft** | Fails | Passes | **Passes 100%** |\n| **Cloudflare Turnstile**| Blocked (\"Just a moment\")| Frequently Blocked | **Bypassed Natively** |\n| **Other Enterprise WAFs**| Blocked | Frequently Blocked | **Bypassed Natively** |\n\n*Note: Damru is capable of bypassing many other advanced detection systems not listed here. As an educational project, we focus on demonstrating these core industry-standard benchmarks.*\n\n---\n\n## Architecture: The 8 Layers of \"Zero JS\" Stealth\n\nDamru's core philosophy is **Zero JavaScript Injection**. Instead of trying to outsmart anti-bot JavaScript *with* more JavaScript, Damru lies from the outside in.\n\n1.  **Layer 1: Android System Props (Root `resetprop`)**\n    Damru connects via ADB and uses root access to modify `build.prop` values dynamically. It changes `ro.product.model`, `ro.build.fingerprint`, and the Android SDK version at the OS level. The browser sees a genuine Pixel 8 Pro or Samsung S24.\n2.  **Layer 2: GPU Binary Patching**\n    Anti-bots actively check your GPU. Generic Docker containers show \"SwiftShader\" (an instant ban). Damru physically patches the Vulkan\u002FGLES `.so` binaries on the filesystem *before* Chrome launches, reading as an `Adreno (TM) 640` or `Mali-G710`.\n3.  **Layer 3: Syscall Interception (`LD_PRELOAD`)**\n    Damru uses a custom C shared library (`libfakemem.so`) to intercept the `sysinfo` and `sysconf` system calls. This ensures that even low-level system checks see the spoofed RAM and CPU specifications of the targeted device.\n4.  **Layer 4: Deep CDP Protocol Overrides**\n    Damru uses low-level Chrome DevTools Protocol (CDP) commands (`Emulation.setHardwareConcurrencyOverride`, `Emulation.setTouchEmulationEnabled`) to spoof CPU cores and touch points directly inside Chromium's C++ engine.\n5.  **Layer 5: Thread & Worker Interception**\n    Using `Target.setAutoAttach`, Damru ensures that every Worker (Dedicated, Shared, and Service) created by the browser inherits the same hardware overrides as the main thread, closing a common leakage vector for advanced anti-bots.\n6.  **Layer 6: Chrome Preferences & Flag Patching**\n    Damru modifies Chrome's underlying `Preferences` JSON and launch flags to force specific Locales, randomize TLS cipher suites (~184 JA3 variants), and disable DNS-over-HTTPS to force resolution through proxy ISP DNS.\n7.  **Layer 7: OS-Level Evasions**\n    Using Android `iptables`, Damru blocks WebRTC private IP leaks and completely disables IPv6. It also neutralizes DevTools timing detection by bypassing `debugger` pauses natively via CDP.\n8.  **Layer 8: Display & Density Spoofing (`wm size\u002Fdensity`)**\n    To avoid \"Resolution Mismatch\" detections, Damru modifies the Android Window Manager natively. It uses `wm size` and `wm density` to force the OS to report physically accurate screen dimensions and pixel densities for the targeted device (e.g., Pixel 8's 1344x2992 @560dpi).\n\n---\n\n## Project Structure\n\nDamru is organized into specialized modules to maintain the separation between high-level Python automation and low-level system spoofing.\n\n```text\ndamru-project\u002F\n+-- damru\u002F                 # Core Framework (Python)\n|   +-- async_core.py      # Async entry points (AsyncDamru)\n|   +-- core.py            # Sync entry points (Damru)\n|   +-- root.py            # OS\u002FBinary patching logic (resetprop\u002Fiptables\u002Fdisplay)\n|   +-- devices.py         # 49 Real Device Specifications Database\n|   +-- chrome.py          # Browser lifecycle & Preferences patching\n|   +-- bypass.py          # CDN TLS\u002FWAF edge-layer TLS impersonation\n|   +-- pool.py            # Multi-container orchestration (DamruPool)\n+-- native\u002F                # Native Binary Hooks (C source)\n|   +-- vulkan_layer.c     # Vulkan C++ string spoofing binary\n|   +-- libfakemem.c       # Physical RAM spoofing via sysconf hooks\n+-- tests\u002F                 # Stealth & Stability Benchmarks\n|   +-- benchmark_auto.py  # Automated Anti-Bot probe\n|   +-- test_stealth.py    # Unit tests for fingerprinting integrity\n+-- chrome-apks\u002F           # Pre-validated Mobile Assets\n|   +-- espeak.apk         # TTS engines for Voice fingerprinting\n|   +-- 145.x\u002F             # Specific Chrome\u002FWebView versions\n+-- docs\u002F                  # Roadmaps & Infrastructure Plans\n+-- scripts\u002F               # Maintenance & Image Baking Utils\n+-- tools\u002F                 # External Debugging Tools (Magisk.apk)\n```\n\n---\n\n## Python API Documentation\n\nFor detailed information on how to use the Damru library programmatically, including class references, managed pooling, and advanced configuration, please see the:\n\n**[Damru Python API Reference](docs\u002FPYTHON_API.md)**\n\nFor the full list of available Android identities, see the:\n\n**[Damru Device Profile Reference](docs\u002FDEVICE_PROFILES.md)**\n\n### Quick Summary:\n*   **`AsyncDamru`**: The primary entry point for asynchronous automation.\n*   **`Damru`**: Synchronous wrapper for standard blocking scripts.\n*   **`DamruPool`**: Orchestration for high-throughput multi-container scraping.\n*   **`damru.bypass`**: Advanced TLS\u002FJA3 impersonation for edge-layer bypasses.\n\n---\n\n## Download Custom OS Image\n\n> [!IMPORTANT]\n> The pre-baked Damru Redroid image is a large Docker tarball and is not tracked in Git. Redroid is Linux-only: load or bake this image inside native Linux or WSL2, never native Windows Docker.\n\nDownload the current pre-baked image:\n\n**[Download damru-redroid-latest.tar](https:\u002F\u002Fdrive.google.com\u002Ffile\u002Fd\u002F1AzSTOlGpSfqHB-F-Yty2JqbOEMlgFT5F\u002Fview?usp=sharing)**\n\nCurrent local artifact prepared for release testing:\n\n```bash\nsha256sum -c damru-redroid-latest.tar.sha256\ndocker load -i damru-redroid-latest.tar\n```\n\nIf the tarball is missing, rebuild it on Linux\u002FWSL:\n\n```bash\npython -m damru bake-image --image damru-redroid:latest\ndocker save damru-redroid:latest -o damru-redroid-latest.tar\nsha256sum damru-redroid-latest.tar > damru-redroid-latest.tar.sha256\n```\n\nOnce downloaded, follow **Step 3** in the Deployment Guide below to load it into Docker.\n\n---\n\n## First-Time User Deployment Guide (WSL2 \u002F Linux)\n\nReady to start? Damru uses **Redroid** (Android in Docker) to spin up headless mobile devices instantly. Follow this step-by-step guide to deploy Damru from scratch on Ubuntu\u002FDebian or WSL2 (Windows Subsystem for Linux).\n\n> [!IMPORTANT]\n> Redroid is Linux-only. On Windows, Docker and Redroid must run inside WSL2; native Windows Docker is not a supported Redroid target.\n\n### Minimum System Requirements\n\nDamru runs one full Android container per worker. The default Redroid worker limit is `2` CPU cores and `2g` memory per container (`REDROID_CPUS = 2.0`, `REDROID_MEMORY = \"2g\"`). Use these numbers for capacity planning:\n\n| Workload | CPU | RAM | Disk | Notes |\n| :--- | :--- | :--- | :--- | :--- |\n| **Bare minimum, 1 worker** | 2 vCPU | 4 GB host RAM | 15 GB free | Enough for install, Docker, one Redroid worker, and basic smoke tests. |\n| **Recommended, 1 worker** | 4 vCPU | 8 GB host RAM | 30 GB free | Better for high-resolution pages, proof captures, and fewer Chrome startup races. |\n| **Each additional worker** | +2 vCPU | +2-3 GB RAM | +5-8 GB free | Matches the default Docker worker limit plus image\u002Fcontainer overhead. |\n| **Baking\u002Fexporting image** | 4 vCPU | 8 GB RAM | 20 GB temporary free | Needs room for base image, baked image layer, and exported `.tar`. |\n| **WSL2 recommended host** | 4+ vCPU | 8-16 GB RAM | 40+ GB free in WSL disk | WSL stores Docker layers inside the distro virtual disk unless you move Docker data-root. |\n\nFor large pools, start with `max_devices=1`, run `python -m damru check-env`, then increase workers gradually. Redroid is CPU and disk-I\u002FO heavy during boot; too many workers on a small VPS will look like browser instability.\n\n`DamruPool(max_devices > 1, mode=\"auto\")` requires real binderfs support, not only `\u002Fdev\u002Fbinder`, `\u002Fdev\u002Fhwbinder`, and `\u002Fdev\u002Fvndbinder` device nodes. If the kernel has `CONFIG_ANDROID_BINDERFS` disabled, one Redroid container may boot while a second container appears in ADB but fails Android userspace (`zygote`, `system_server`, WebView\u002FCDP). Current Damru checks this before starting a multi-worker pool and tells the user to run `max_devices=1` or boot a binderfs-enabled kernel.\n\n### Step 1: System Preparation (Linux \u002F WSL2)\n\nYou need a Linux environment. If you are on Windows, install WSL2 (Ubuntu). Ensure your system is up to date and install `adb`:\n\n```bash\nsudo apt update && sudo apt upgrade -y\nsudo apt install adb wget curl git jq -y\n```\n\nAfter Damru is installed, you can also let the CLI install the common Linux\u002FWSL dependencies:\n\n```bash\npython -m damru install-deps\npython -m damru check-env\n```\n\n`install-deps` is idempotent: on a fresh WSL\u002FLinux install it installs ADB, Docker, iptables, curl\u002Fwget\u002Fgit\u002Fjq, mounts binderfs, and starts Docker. On later runs it reuses installed packages and rehydrates Docker\u002Fbinderfs after WSL restarts.\n\nOn Windows\u002FWSL2, Damru runs Docker and Redroid inside WSL and routes Redroid ADB through WSL. When Docker-published ADB ports are unreliable, Damru uses host networking and remaps each Redroid worker's `adbd` to a unique port (`5600`, `5601`, ...), so multi-worker pools can still run without native Windows Docker. Native Linux uses Docker bridge\u002FNAT and Damru selects the nft iptables backend to match modern Docker daemons; WSL prefers legacy iptables where available because some WSL kernels reject Docker's `addrtype` NAT rule through nft. See [WSL kernel notes](docs\u002FWSL_KERNEL.md) and the latest [WSL fallback test results](docs\u002FWSL_FALLBACK_TEST_RESULTS.md).\n\nCurrent validation on June 2, 2026. Full sanitized notes are in [Verification Proof](docs\u002FPROOF.md):\n\n- WSL2 fresh-loop distro: `install-deps -y`, `fix-wsl`, `install-viewer -y`, `check-env --viewer`, single-worker browser smoke, and two-worker `DamruPool(mode=\"auto\", max_devices=2)` passed.\n- Native Ubuntu VPS reset loop: Docker packages\u002Fstate removed, fresh venv created, `install-deps -y`, `check-env --viewer`, unit tests, single-worker browser smoke, and two-worker pool smoke passed.\n- Both WSL and native Linux verified `https:\u002F\u002Fexample.com` in two concurrent Redroid workers with `navigator.hardwareConcurrency == 8`.\n\n### Step 2: Install Docker & Enable Binderfs (Crucial for Redroid)\n\nPrefer `python -m damru install-deps`; it performs these package, Docker, binderfs, iptables, and Playwright-patch steps automatically. The manual commands below are only for debugging or custom Linux images.\n\nRedroid requires Docker and Android's `binderfs` kernel modules. \n\n1.  **Install Docker**:\n    ```bash\n    curl -fsSL https:\u002F\u002Fget.docker.com -o get-docker.sh\n    sudo sh get-docker.sh\n    sudo usermod -aG docker $USER\n    ```\n    *(Log out and log back in, or run `newgrp docker` to apply permissions).*\n\n2.  **Mount Binderfs** (Required for Android inside Docker):\n    ```bash\n    sudo mkdir -p \u002Fdev\u002Fbinderfs\n    sudo mount -t binder binder \u002Fdev\u002Fbinderfs\n    ```\n    *(Note: To make this persistent across reboots, you will need to add it to `\u002Fetc\u002Ffstab`).*\n\n### The Instant Custom OS Image\n\nCompiling native C binaries, injecting them via ADB, applying `iptables` rules, and installing Chrome on every run is slow. The recommended path is a baked `damru-redroid:latest` Docker image exported as `damru-redroid-latest.tar`, where Chrome, native patches, fonts, TTS assets, and warm Chrome preferences are already installed. The tarball is intentionally ignored by Git because it is large; keep the checksum file with the release artifact.\n\n### Step 3: Instant Boot with the Custom OS (Recommended)\n\n1.  **Load the pre-baked image**:\n    \n    **For WSL2 Users:** copy or mount the tarball inside your WSL distro, then run Docker from WSL:\n    ```bash\n    sha256sum -c damru-redroid-latest.tar.sha256\n    docker load -i damru-redroid-latest.tar\n    ```\n    \n    **For Native Linux Users:**\n    ```bash\n    sha256sum -c damru-redroid-latest.tar.sha256\n    docker load -i damru-redroid-latest.tar\n    ```\n\n2.  **Start the custom Damru container**:\n    ```bash\n    docker run -itd --rm --privileged \\\n        -v ~\u002Fdata:\u002Fdata \\\n        -p 5555:5555 \\\n        damru-redroid:latest \\\n        androidboot.redroid_width=1080 \\\n        androidboot.redroid_height=2400 \\\n        androidboot.redroid_dpi=480\n    ```\n\n3.  Wait 30 seconds for Android to boot, then connect via ADB:\n    ```bash\n    adb connect localhost:5555\n    adb devices\n    # You should see: localhost:5555 device\n    ```\n\n#### Troubleshooting Common WSL2 Errors\n\nIf your Redroid container fails to boot or Docker won't start in WSL, run these mandatory \"Fix-it\" commands:\n\n*   **Binderfs Error** (`docker: Error... no such device`):\n    ```bash\n    sudo mkdir -p \u002Fdev\u002Fbinderfs\n    sudo mount -t binder binder \u002Fdev\u002Fbinderfs\n    ```\n*   **Docker Network Error** (`iptables` failure):\n    ```bash\n    python -m damru fix-wsl\n    ```\n    Damru selects a Docker-compatible iptables backend automatically. On some WSL kernels, Docker's `addrtype` NAT rule works with `iptables-legacy` but fails with `iptables-nft`.\n*   **Missing WSL Kernel Module** (`xt_addrtype not found`):\n    ```bash\n    python -m damru fix-wsl\n    ```\n    If the module is still missing, Damru tries its no-iptables\u002Fno-bridge Docker fallback. Windows auto mode uses WSL host networking with per-worker ADB port remapping for Redroid workers. For classic Docker bridge\u002FNAT mode, boot a WSL2 kernel with Docker bridge\u002FNAT and binderfs support.\n*   **Permission Denied**:\n    ```bash\n    sudo usermod -aG docker $USER\n    # Restart WSL after running this\n    ```\n\n> [!TIP]\n> **What is an ADB Serial?**\n\n> An ADB serial is a unique identifier for your Android device. \n> - For **Redroid\u002FDocker**, it is usually the network address: `localhost:5555` or an internal IP.\n> - Physical-device serials may appear in `adb devices`, but Damru does not support physical phones as automation targets.\n\n### Step 4: Install Damru\n\n**Option A: Direct Pip Install (Fastest)**\n```bash\npip install git+https:\u002F\u002Fgithub.com\u002Fakwin1234\u002Fdamru.git\nplaywright install\n```\n\nVerify the local environment:\n\n```bash\npython -m damru setup\npython -m damru check-env\n```\n\nIf Docker still fails inside WSL, run the safe repair\u002Fdiagnostic pass:\n\n```bash\npython -m damru fix-wsl\n```\n\nIf it reports a missing kernel module such as `xt_addrtype`, the active WSL2 kernel lacks Docker bridge\u002FNAT support. See [WSL2 Kernel Requirements](docs\u002FWSL_KERNEL.md).\n\nFor scripted setup with a custom WSL distro\u002Fuser, pass them explicitly:\n\n```bash\npython -m damru setup -y --wsl-distro Ubuntu --wsl-username your-wsl-user\n```\n\n#### Windows Installation Fix (Important)\n\nIf you are using an older Windows Python\u002Fsetuptools combination and encounter an `AssertionError: ...distutils\\core.py` during `pip install`, upgrade packaging tools first:\n\n```powershell\npython -m pip install -U pip setuptools wheel\npip install git+https:\u002F\u002Fgithub.com\u002Fakwin1234\u002Fdamru.git\n```\n\nDo not set `SETUPTOOLS_USE_DISTUTILS=stdlib` globally on modern Python. It can break editable builds on Python 3.14 and newer.\n\n**Option B: Clone & Install (For Developers)**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fakwin1234\u002Fdamru.git\ncd damru\npython3 -m venv venv\nsource venv\u002Fbin\u002Factivate\npip install -e .\nplaywright install\npython -m damru setup --skip-deps\n```\n\nWhen you import Damru, it verifies and applies the bundled Playwright `crPage.js` patch used to reduce CDP target discovery leaks.\n\n### CLI Commands\n\n```bash\npython -m damru setup           # guided first-run setup and config writer\npython -m damru check-env       # validate Linux\u002FWSL dependencies and assets\npython -m damru install-deps    # install common Linux\u002FWSL dependencies\npython -m damru fix-wsl         # retry safe WSL Docker\u002Fbinderfs\u002Fnetfilter fixes\npython -m damru wsl-kernel status # inspect bundled\u002Factive WSL kernel state\npython -m damru benchmark       # run the benchmark command\npython -m damru bake-image      # bake a warm Redroid image\npython -m damru devices         # list ADB devices from Linux\u002FWSL\npython -m damru screenshot      # capture Android display PNG through ADB\npython -m damru record          # capture Android display MP4 through ADB\npython -m damru view            # open optional scrcpy live viewer\npython -m damru install-viewer  # check\u002Finstall optional scrcpy tooling\n```\n\nFor testing a separate WSL distro without changing `config.py`, set `DAMRU_WSL_DISTRO`, for example: `$env:DAMRU_WSL_DISTRO=\"DamruFreshKernelTest\"`. Do not run host-network Redroid workers in multiple WSL distros at the same time; `check-env` reports this conflict.\n\n> **WSL custom kernel safety:** On Windows, Damru recommends using a fresh\u002Fdedicated WSL distro for Redroid. The bundled kernel installer edits `%USERPROFILE%\\.wslconfig`, which changes how WSL boots. Damru backs up `.wslconfig`, but a custom WSL kernel can still break Docker\u002Fnetworking\u002Fmodules or other WSL workloads. Interactive installs require typing the full warning phrase; scripted installs require `--confirm-wsl-kernel-risk` in addition to `--yes`. Native Linux\u002FUbuntu does not use this WSL kernel installer.\n\nOn Windows, `install-deps` runs inside WSL as root and does not use native Windows Docker. On native Linux scripted setup where sudo cannot prompt interactively, pass one password line on stdin:\n\n```bash\nprintf '%s\\n' 'your-sudo-password' | python -m damru install-deps -y --sudo-password-stdin\n```\n\nFor visual inspection or manual browser operation, see [Viewer, Screenshots, and Video](docs\u002FVIEWER.md). Viewer support is optional and never starts automatically during `AsyncDamru`, `Damru`, or pool sessions.\n\n---\n\n## Global Configuration\n\nDamru uses a centralized configuration file located at `damru\u002Fconfig.py`. If you clone the repository or install it locally, you should modify these settings before running large pools or automated scripts.\n\n> [!TIP]\n> **Pre-made Configurations Available!**\n> We have provided OS-specific configuration templates in the `damru\u002F` directory to get you started faster:\n> - **Windows \u002F WSL2**: Copy `damru\u002Fconfig.py.windows` and rename it to `config.py`.\n> - **Native Linux**: Copy `damru\u002Fconfig.py.linux` and rename it to `config.py`.\n\n### Essential Configurations\n\n1. **WSL2 Settings (Windows Auto-Mode)**:\n   If you are running Python on Windows, Docker and Redroid still run inside WSL2. Damru uses `wsl -u root` for Linux setup and Docker preparation, so a WSL sudo password is not required for the CLI setup path.\n   ```python\n   # damru\u002Fconfig.py\n   WSL_DISTRO = \"Ubuntu\"\n   WSL_USERNAME = \"your-wsl-user\"\n   WSL_PASSWORD = \"\"  # Kept for compatibility; current WSL setup uses wsl -u root\n   ```\n\n   Existing WSL installs are covered by `damru setup`: set `WSL_DISTRO` and `WSL_USERNAME`, then run `python -m damru check-env`. Damru's current Windows setup\u002Fruntime path uses `wsl -u root` for privileged WSL commands, so it does not need to store a sudo password in `config.py`.\n\n2. **Chrome APK Path**:\n   When not using the pre-baked `.tar` image, Damru will dynamically install Chrome onto raw Redroid instances. Point it to your APK directory.\n   ```python\n   # None = auto-searches the 'chrome-apks\u002F' directory in the project root\n   CHROME_APK = None  \n   # Or specify an absolute path:\n   # CHROME_APK = \"\u002Fmnt\u002Fc\u002Fpath\u002Fto\u002Fdamru\u002Fchrome-apks\u002F145.0.7632.75\"\n   ```\n\n3. **Pool Settings (`NUM_DEVICES` & `MODE`)**:\n   ```python\n   MODE = \"auto\"          # \"auto\" = manages Docker containers; \"mumu\" = local VMs; \"manual\" = ADB\n   NUM_DEVICES = 10       # How many concurrent containers to spin up\u002Fmaintain\n   REDROID_IMAGE = \"damru-redroid:latest\"  # The Docker image to use\n   ```\n\n4. **Proxy, Timezone, and Locale**:\nLeave `TIMEZONE` and `LOCALE` as `None` unless you intentionally need fixed values. Damru resolves the active proxy exit at session start, then applies matching Android timezone, Chrome timezone, `Accept-Language`, and `Intl` locale. Rotating residential proxies are rechecked through Chrome after CDP connects so the browser does not keep a stale timezone from a previous exit.\n\nAuto locale selection covers standard ISO country codes plus CLDR exceptional territory codes. Countries with more than one realistic phone\u002Fbrowser language can rotate between valid local variants, for example `en-PH` \u002F `fil-PH` or `en-IN` \u002F `hi-IN`.\n   ```python\n   PROXY = None        # Optional: SOCKS5\u002FHTTP proxy URL for Python-side checks\n   HTTP_PROXY = None   # Optional: Android system HTTP proxy as host:port\n   TIMEZONE = None     # Auto from proxy exit when unset\n   LOCALE = None       # Auto from proxy country when unset\n   ```\n\n   If your upstream proxy is SOCKS5 but Android needs an HTTP CONNECT proxy, run or provide a local HTTP bridge and pass it as `http_proxy` in code or `HTTP_PROXY` in config.\n\n### Docker Storage Location (Crucial for Windows Users)\nRedroid containers consume significant disk space. If you are using WSL2 Docker, it saves data to your `ext4.vhdx` virtual drive on the `C:` drive by default, which can quickly fill up your primary SSD.\n\n**To save Docker images to a secondary HDD:**\nYou must configure the Docker daemon inside WSL to use a different data-root.\n1. Open WSL (`wsl -d Ubuntu`).\n2. Stop docker: `sudo service docker stop`.\n3. Move existing data to your HDD: `sudo mv \u002Fvar\u002Flib\u002Fdocker \u002Fmnt\u002Fd\u002Fdocker-data`.\n4. Symlink it back: `sudo ln -s \u002Fmnt\u002Fd\u002Fdocker-data \u002Fvar\u002Flib\u002Fdocker`.\n5. Start docker: `sudo service docker start`.\n\n*(Note: Native `DOCKER_STORAGE_PATH` configuration via Python is on the upcoming roadmap).*\n\n---\n\n## Usage & Examples\n\nDamru handles the heavy lifting: it connects to ADB, gains root, applies system patches, spoofs the GPU, launches Chrome, and attaches via CDP-all automatically.\n\n### Example 1: Basic Async Usage (The Standard Way)\n\n```python\nimport asyncio\nfrom damru import AsyncDamru\n\nasync def main():\n    print(\"Launching Damru...\")\n    \n    # device=\"random\" picks from 49 real Android device profiles.\n    # Leave timezone\u002Flocale unset so Damru follows the active proxy exit.\n    async with AsyncDamru(\n        device=\"random\", \n        proxy=\"socks5:\u002F\u002Fyour.proxy.ip:1080\",\n        debug=True\n    ) as browser:\n        \n        # 'browser' is a standard Playwright BrowserContext!\n        page = await browser.new_page()\n        \n        print(\"Navigating to CreepJS to test stealth...\")\n        await page.goto(\"https:\u002F\u002Fabrahamjuliot.github.io\u002Fcreepjs\u002F\")\n        await page.wait_for_timeout(10000)\n        await page.screenshot(path=\"creepjs_score.png\")\n        print(\"Done! Check creepjs_score.png\")\n\nasyncio.run(main())\n```\n\n### Example 1b: Authenticated Proxy with Android HTTP Bridge\n\nAndroid system proxy supports HTTP CONNECT. If your provider gives SOCKS5 for Python-side checks but Android Chrome must use a local HTTP bridge, pass both values:\n\n```python\nfrom damru import AsyncDamru\n\nasync with AsyncDamru(\n    device=\"pixel_8_pro\",\n    proxy=\"socks5:\u002F\u002Fuser:pass@proxy.example:824\",\n    http_proxy=\"172.17.0.1:18888\",\n) as browser:\n    page = await browser.new_page()\n    await page.goto(\"https:\u002F\u002Fdemo.fingerprint.com\u002Fplayground\")\n```\n\nDamru resolves timezone and locale through `http_proxy` because that is the route Chrome actually uses. Do not set `timezone` or `locale` manually unless they match the current proxy exit.\n\n### Example 2: Synchronous Usage\n\nIf you prefer synchronous code, Damru provides a blocking wrapper:\n\n```python\nfrom damru import Damru\n\ndef run_sync():\n    with Damru(device=\"pixel_8_pro\") as browser:\n        page = browser.new_page()\n        page.goto(\"https:\u002F\u002Fbot.sannysoft.com\u002F\")\n        page.wait_for_timeout(5000)\n        page.screenshot(path=\"sannysoft.png\")\n        print(\"Passed Sannysoft!\")\n\nif __name__ == \"__main__\":\n    run_sync()\n```\n\n### Example 3: Scaling Up with Connection Pooling\n\nScraping thousands of pages? Damru provides a native Pool manager to run operations concurrently across multiple Docker containers.\n\n```python\nfrom damru import DamruPoolSync\n\nproxies = [\n    \"socks5:\u002F\u002Fproxy1:1080\",\n    \"socks5:\u002F\u002Fproxy2:1080\",\n    \"socks5:\u002F\u002Fproxy3:1080\"\n]\n\nwith DamruPoolSync(mode=\"auto\", max_devices=3, proxies=proxies) as pool:\n    for i in range(3):\n        with pool.session() as context:\n            page = context.new_page()\n            page.goto(\"https:\u002F\u002Fexample.com\u002Fapi\u002Fscrape_target\")\n            print(f\"Worker {i} finished scraping: {page.title()}\")\n```\n\n---\n\n## Testing Your Setup\n\nDamru ships with a comprehensive benchmark suite. Run it to ensure your setup is truly undetectable.\n\n```bash\n# Run all benchmark tests on a random device\npython -m damru benchmark --device random\n\n# Run specific tests with a proxy\npython -m damru benchmark --device samsung_galaxy_s24_ultra --proxy socks5:\u002F\u002Fip:port --tests creepjs cloudflare\n```\n\n---\n\n## The \"Big Plan\" (Roadmap)\n\nWe are aggressively building Damru into a fully autonomous infrastructure tool. Check `docs\u002FAUTOMATION_GAPS_PLAN.md` for details.\n\n*   [x] **`damru setup` CLI**: Single-command configuration plus Linux\u002FWSL dependency setup.\n*   [x] **Automated Health Checks**: Verification of ADB, Docker, binderfs, Chrome APKs, and Playwright patches.\n*   [x] **Manual Viewer Tools**: Optional screenshots, video recording, and scrcpy live viewer.\n*   [ ] **Auto Image Management**: Damru will dynamically bake \"Damru-Ready\" Docker images natively.\n*   [ ] **Mass Orchestration**: Expanding `DamruPool` for Kubernetes\u002FSwarm deployment.\n\n---\n\n## Frequently Asked Questions\n\n### 1. Does Damru support physical Android devices?\n**No.** Damru is designed strictly for containerized environments (Redroid). Its low-level OS patches, `resetprop` logic, and binary driver injections are optimized for Redroid's kernel and filesystem. **Do not attempt to use Damru on your personal phone.** If you use a spare rooted device, you do so entirely at your own risk.\n\n### 2. Can I use MuMu Player instead of Docker?\nMuMu Player support is currently an **experimental, unfinished, and non-functional beta feature**. While the code structure for it exists, we highly recommend using **Redroid (Docker)** for any production or serious research work.\n\n### 3. Why is the .tar image so large?\nThe `damru-redroid-latest.tar` image is a full Android 14 operating system export. The current test artifact is about 915 MB as a Docker tarball and expands to a larger Docker image after `docker load`. It includes pre-installed Chrome, TTS assets, custom fonts, and pre-patched binary drivers for faster deployment.\n\n### 4. Does Damru work on native Linux?\n**Yes.** Any Docker image built in WSL2 is a standard Linux image. Damru works perfectly on native Linux (Ubuntu, Debian, etc.), provided the `binder` kernel modules are loaded.\n\n### 5. Why \"Zero JS Injection\"?\nStandard stealth tools are caught by anti-bots because their JavaScript injections leave traces (timing, prototype pollution). Damru lies from the outside-in (OS, Binary, and Protocol levels), making it mathematically invisible to scripts.\n\n---\n\n## 🙏 Acknowledgments & Credits\n\nDamru is built on the shoulders of giants. We would like to credit the following projects and technologies that make this framework possible:\n\n*   **[redroid](https:\u002F\u002Fgithub.com\u002Fremote-android\u002Fredroid-doc)**: The core GPU-accelerated Android-in-Container solution that provides our high-performance mobile environment.\n*   **[Playwright](https:\u002F\u002Fplaywright.dev\u002F)**: The incredible browser automation library that serves as our high-level API.\n*   **[Chromium](https:\u002F\u002Fwww.chromium.org\u002FHome)**: The world-class browser engine we patch and automate.\n*   **[Android Open Source Project (AOSP)](https:\u002F\u002Fsource.android.com\u002F)**: For the robust operating system foundation.\n*   **[Chrome DevTools Protocol (CDP)](https:\u002F\u002Fchromedevtools.github.io\u002Fdevtools-protocol\u002F)**: The low-level protocol that allows us to bypass JavaScript-based fingerprinting.\n*   **[Magisk](https:\u002F\u002Fgithub.com\u002Ftopjohnwu\u002FMagisk)**: For the inspiration behind the `resetprop` logic used in our system property spoofing.\n*   **[curl_cffi](https:\u002F\u002Fgithub.com\u002Fyifeikong\u002Fcurl_cffi)**: For providing the TLS impersonation capabilities used in our edge-layer bypasses.\n*   **[Docker](https:\u002F\u002Fwww.docker.com\u002F)**: For the containerization infrastructure that enables scalable automation pools.\n\n---\n\n## Mandatory Legal Disclaimer & Ethical Use Notice\n\n**IMPORTANT: READ CAREFULLY BEFORE PROCEEDING**\n\nDamru (the \"Software\") is developed and distributed strictly for **educational purposes, ethical security research, and authorized academic study**. By using this Software, you acknowledge and agree to the following terms:\n\n### 1. Educational and Research Intent\nAny examples provided within this repository-including but not limited to the bypassing of **Cloudflare, CreepJS, or BrowserScan**-are presented solely as theoretical demonstrations of browser fingerprinting vulnerabilities. These \"bypasses\" are intended for use against systems you own or have explicit, written permission to test. They are designed to help security professionals and developers understand how to improve their own defensive measures.\n\n### 2. No Warranty and Limitation of Liability\nThe Software is provided **\"AS IS\"**, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors, contributors, or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Software or the use or other dealings in the Software.\n\n### 3. Compliance with Laws and Terms of Service (ToS)\nThe user assumes **full and sole responsibility** for ensuring that their use of Damru complies with all applicable local, state, national, and international laws, including but not limited to the **Computer Fraud and Abuse Act (CFAA)**. \n*   **Terms of Service:** Bypassing security measures or anti-bot protections often violates the target website's Terms of Service. \n*   **Unauthorized Access:** Unauthorized scraping or automated interaction with third-party systems may result in civil or criminal penalties.\n*   **Ethics:** Users must not use this tool to facilitate malicious activity, data theft, credential stuffing, or any form of service disruption.\n\n### 4. Risk Acknowledgment\nUsing automation frameworks against high-security systems carries inherent risks, including IP blacklisting, account termination, and potential legal action from service providers. **The authors do not condone, support, or encourage the illegal or unethical use of this Software.**\n\n### 5. Commercial and Business Use Restriction\nIn accordance with the **PolyForm Noncommercial License 1.0.0**, all commercial and business use of this Software is strictly prohibited. This includes, but is not limited to, use by for-profit entities, use in support of commercial services, or any activity directed toward monetary compensation. The Software is licensed exclusively for personal, educational, and non-commercial research purposes.\n","Damru 是一款专为安卓浏览器设计的高度隐蔽自动化框架。它通过本地C++重写、操作系统级别的根属性伪装以及GPU二进制修补等技术，实现了真正的无痕操作，能够绕过所有CDN，并在使用Redroid和Playwright时于CreepJS测试中获得100%的得分。该框架适用于需要大规模进行网页抓取或模拟用户行为而不被检测到的场景。项目基于Python开发，支持最新的Playwright版本，推荐运行环境为WSL2或Linux系统下的Redroid Docker容器。","2026-06-11 04:09:16","CREATED_QUERY"]