{"id":20602814,"url":"https://github.com/airbus-seclab/android_emuroot","last_synced_at":"2025-04-15T01:54:51.283Z","repository":{"id":42187566,"uuid":"156574433","full_name":"airbus-seclab/android_emuroot","owner":"airbus-seclab","description":"Android_Emuroot is a Python script that allows granting root privileges on the fly to shells running on Android virtual machines that use google-provided emulator images called Google API Playstore, to help reverse engineers to go deeper into their investigations.","archived":false,"fork":false,"pushed_at":"2021-01-28T19:03:14.000Z","size":7655,"stargazers_count":130,"open_issues_count":2,"forks_count":27,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-15T01:54:43.268Z","etag":null,"topics":["android","android-emuroot","emulator","python","reverse-engineering","root-privileges"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airbus-seclab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-07T16:17:51.000Z","updated_at":"2025-03-31T19:07:42.000Z","dependencies_parsed_at":"2022-09-13T09:50:36.359Z","dependency_job_id":null,"html_url":"https://github.com/airbus-seclab/android_emuroot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Fandroid_emuroot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Fandroid_emuroot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Fandroid_emuroot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Fandroid_emuroot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airbus-seclab","download_url":"https://codeload.github.com/airbus-seclab/android_emuroot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991540,"owners_count":21194894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-emuroot","emulator","python","reverse-engineering","root-privileges"],"created_at":"2024-11-16T09:14:52.230Z","updated_at":"2025-04-15T01:54:51.260Z","avatar_url":"https://github.com/airbus-seclab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Android_Emuroot\n\n## Introduction\n\nAndroid_Emuroot is a Python script that allows **granting root privileges** on\nthe fly to shells running on Android virtual machines that use google-provided\nemulator images called *Google API Playstore*, to help reverse engineers to\ngo deeper into their investigations.\n\nAndroid_Emuroot requires the *Google API Playstore* emulator to be launched\nwith the qemu gdb stub option enabled, and uses it to alter process metadata\nstored in memory in kernel task structures. The main idea\nis to start from a shell with the lowest privileges, then to find its\nassociated credential structure in kernel memory to replace it by another\nstructure having the highest privileges.\n\nImplementing this memory modification on a *Google API Playstore* emulator presents the\nfollowing two advantages:\n* to work with an environment very similar to a physical device (with production \n  build number, etc.) and with all Google Play and Google services packages \n  already installed. This is often required by the targeted applications\n* to have a very easily modifiable memory since a GDB debugger can be attached to \n  the device to fully control the kernel memory\n\n## Requirements\n\n### Prerequisites\n\nAndroid_Emuroot requires to already have a working [Android\nSDK](https://developer.android.com/studio). Installing the [command-line\ntools](https://developer.android.com/studio#command-tools) is recommended\n(downloadable via the Android Studio GUI: Tools \u003e Android \u003e SDK manager \u003e SDK\nTools).\n\n### Installing dependencies\n\nAndroid_Emuroot is a Python script that uses the ADB facilities as well as the\nGDB facilities from the two following Python's modules:\n\n* [pygdbmi](https://pypi.org/project/pygdbmi) (Parse GDB machine interface output with Python)\n* [pure-python-adb](https://pypi.org/project/pure-python-adb) (Pure Python implementation of the ADB client)\n\n**Be sure you have these modules or install them via pip:** `pip3 install -r requirements.txt`.\n\nN.B.: Android_Emuroot supports Python 2 and Python 3.\n\n### Supported *Google API Playstore* emulators\n\nDepending on the hardware architecture and the kernel version of the emulator,\nthe memory layout of the related qemu image varies. Thereby the location of\nthe memory patches implemented by Android_Emuroot varies as well. \n\nFor now, Android_Emuroot supports the following versions of emulators:\n\n| Android version | API | Architecture | Kernel | Build                |\n| --------------- | --- | ------------ | ------ | -------------------- |\n| Android 7.0     | 24  | x86          | 3.10   | google-api-playstore |\n| Android 7.1.1   | 25  | x86          | 3.10   | google-api-playstore |\n| Android 8.0     | 26  | x86          | 3.18   | google-api-playstore |\n| Android 8.1     | 27  | x86          | 3.18   | google-api-playstore |\n\n\n**Be sure the AVD you want to root is based on one emulator of this list.**\n\nN.B.: the emulators can be downloaded via\n[sdkmanager](https://developer.android.com/studio/command-line/sdkmanager), a\ntool from the Android Studio toolchain, with the GUI or in command line, for\nexample like this: ```sdkmanager --install \"system-images;android-27;google_apis_playstore;x86\"```. \nThen, create an Android Virtual Device (AVD) accordingly, via the AVD manager GUI or\nwith\n[avdmanager](https://developer.android.com/studio/command-line/avdmanager)\nlike this: `avdmanager create avd -n my_avd_name -k \"system-images;android-27;google_apis_playstore;x86\"`.\n\n\n### Working environment\n\nAndroid_Emuroot needs to interact with both:\n\n* the ADB server of to get information from the emulated device and spawn shells inside\n* the GDB server of QEMU to get information about the memory layout of the emulated device and patch values in memory\n\nThe scheme below shows the interactions between all the elements:\n\n![Android_Emuroot working environment](docs/android_emuroot_working_env.png)\n\n\n#### Launching the ADB server\n\nThe Android Debug Bridge\n([ADB](https://developer.android.com/studio/command-line/adb)) is a\ncommand line tool of the Android Studio toolchain that lets communicate with\nan Android device. The ADB server is the component that manages communication\nbetween Android_Emuroot and the ADB daemon launched on the device. By default,\nADB servers listen on *127.0.0.1* port *5037*. `adb start-server` lets you\nensure that there is a server running.\n\n*Be sure your ADB server is running.*\n\n\n#### Running the emulator with a GDB server\n\nThe other requirement to use Android_Emuroot is to attach a GDB server to your\nAVD when launching it.\n[emulator](https://developer.android.com/studio/run/emulator-commandline),\nanother command line tool of the Android Studio toolchain, allows to launch\nAVDs with a lot of options. Among them: `-qemu -s` (shorthang for `-qemu -gdb tcp::1234`) \n which opens a GDB server on TCP port 1234. \n\n*Use this option to get a GDB server available.*\n\nHere is an simple example of [emulator](https://developer.android.com/studio/run/emulator-commandline)'s usage:\n\n```emulator -avd my_avd_name [options] -qemu -s```\n\nThis way, a GDB server will be attached to the AVD `my_avd_name` and\nAndroid_Emuroot will be able to spawn its GDB client and perform the memory\npatches.\n\n*Once both ADB server and GDB server are operational, you are ready to use Android_Emuroot.*\n\n## Usage\n\n### Features \n\nAndroid_Emuroot has 3 modes:\n\n* `single --magic-name NAME`:  to give root privileges to only 1 shell given in parameter\n* `adbd [--stealth]`:  to give root privileges to the entire `adbd` server; each new shell will be spawned as root\n* `setuid --path NAME`:  to install a setuid root binary on the file system\n\n\nMore details on the usage and the tool internals: [Detailed Usage](Howto.md)\n\n\n## About\n\n### Authors\n\nAndroid_Emuroot has been written by Mouad Abouhali and Anaïs Gantet from\n[airbus-seclab](https://airbus-seclab.github.io).\n\n\n### License\n\nAndroid_Emuroot is released under\n[GPLv2](https://github.com/airbus-seclab/android_emuroot/blob/master/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbus-seclab%2Fandroid_emuroot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairbus-seclab%2Fandroid_emuroot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbus-seclab%2Fandroid_emuroot/lists"}