Android Recovery

Android Recovery is a read-only command-line tool for acquiring recoverable Trash items and extracting deleted-media previews from Android devices over ADB. It runs as Android's shell account, writes only to the host computer, and does not use root or UI automation.

    _              _           _     _   ____
   / \   _ __   __| |_ __ ___ (_) __| | |  _ \ ___  ___ _____   _____ _ __ _   _
  / _ \ | '_ \ / _` | '__/ _ \| |/ _` | | |_) / _ \/ __/ _ \ \ / / _ \ '__| | | |
 / ___ \| | | | (_| | | | (_) | | (_| | |  _ <  __/ (_| (_) \ V /  __/ |  | |_| |
/_/   \_\_| |_|\__,_|_|  \___/|_|\__,_| |_| \_\___|\___\___/ \_/ \___|_|   \__, |
                                                                            |___/

What it recovers

• Files still present in MediaStore Trash
• Files in common Gallery and File Manager Trash directories
• Trash databases and marker files as separate artifacts
• Orphaned previews from Gallery2-compatible BlobCache files
• OEM BlobCache records with nonstandard index headers
• Classic MediaStore thumbnails whose source ID is gone
• Validated images from legacy .thumbdata containers

Recovered cache files are previews, not guaranteed copies of the original media. Their dimensions and compression may differ from the deleted source.

Requirements

• Python 3.9 or newer
• Android Platform Tools with adb available in PATH
• At least one unlocked and authorized Android device
• USB debugging enabled

No third-party Python packages are required.

Quick start

Clone the repository, connect the phone, accept the debugging prompt, and run:

python3 -B run.py

The default run performs the complete workflow and creates cases-01 in the current directory. Later runs create cases-02, cases-03, and so on.

To install the command locally:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .
android-recovery

Common options

Show all options:

python3 -B run.py --help

Choose a device and output directory:

python3 -B run.py --serial R58M123456A --output ./evidence

Acquire Trash without scanning media caches:

python3 -B run.py --trash-only

Recover previews without copying Trash payloads:

python3 -B run.py --previews-only

Limit the amount of output during a test run:

python3 -B run.py --max-trash 20 --max-previews 50

Use an exact case name:

python3 -B run.py --output ./evidence --case-name phone-2026-08-13

Existing case directories are never overwritten.

Configuration file

Create a complete JSON template:

python3 -B run.py --init-config recovery.json

The repository also includes config.example.json as a reference.

Review it, then run:

python3 -B run.py --config recovery.json

Command-line options override values loaded from the JSON file. Print the final configuration without connecting to a device:

python3 -B run.py --config recovery.json --show-config

The JSON file exposes the complete configuration, including timeouts, Android user ID, case numbering, scan sources, cache limits, thumbnail layout, known Gallery cache paths, Trash directory names, removable storage handling, and error policy. See docs/configuration.md for every field.

Case layout

cases-01/
  logs/
    recovery.log
  metadata/
    case.json
    device.json
    errors.json
    mediastore-index.txt
    mounts.txt
    summary.json
  trash/
    artifacts/
    files/
    metadata/
      acquisition.json
      candidates.csv
      candidates.json
      mediastore-trash.txt
  recovery/
    cache/
    metadata/
      recovery.csv
      recovery.json
    previews/

Each captured payload and cache source is hashed with SHA-256. The case metadata records the effective configuration, device profile, source code hashes, acquisition methods, timestamps, failures, and recovery classification.

Safety model

The program requires ADB UID 2000. It stops if the connected session is root or another account. Remote operations are limited to reads from shared storage and MediaStore. No file is restored, renamed, deleted, or created on the Android device.

Modern Android devices normally combine file-based encryption, flash discard, and filesystem garbage collection. A non-root ADB process cannot read the userdata block device or unallocated filesystem space. Android Recovery therefore performs logical recovery from still-readable Trash and cache data. It does not claim raw undelete capability.

Supported devices

The scanner is based on Android storage conventions rather than a manufacturer allowlist. It includes known layouts used by AOSP Gallery, Google Gallery, Samsung Gallery, ColorOS/Oppo, OnePlus, Transsion Gallery, and common File Manager recyclers. Vendor updates can change storage paths or block ADB access, so support cannot be guaranteed for every model or firmware release.

Testing

python3 -B -m unittest discover -s tests -v

Contributing

Bug reports and tested vendor adapters are welcome. Read CONTRIBUTING.md before opening a pull request. Security issues should follow SECURITY.md.

License

Released under the MIT License.