WhatsApp Forensic Tool

A powerful, cross-platform forensic tool designed to extract, decrypt, and analyze WhatsApp backups (msgstore.db.cryptXX) from Android devices. This tool works seamlessly on PC (Windows/Linux/macOS) via ADB and directly on Android devices using Termux.

Developed by Cedroid (developer@cedroid.com).

🚀 Features

• Zero-Config Installation: Automatically installs Python, sets up a virtual environment, downloads ADB, and installs dependencies.
• Cross-Platform Support: Run on your computer or directly on the target phone via Termux.
• Automated Extraction: Scans for WhatsApp and WhatsApp Business backups automatically.
• Decryption Engine: Supports crypt12, crypt14, and crypt15 databases using the 64-character hexadecimal key.
  • Note: This key is generated when you enable End-to-End Encrypted Backups in WhatsApp settings. You must save it manually at that time.
• Media Dumping: Extracts media files associated with chats.
• Chat Viewer & Export: View decrypted chats in a clean UI and export them to HTML, CSV, JSON, or TXT.
• No Root Required (PC Mode): Extracts non-protected backups via ADB (legacy storage).
• Termux Integration: Specialized mode for running directly on Android to access internal storage (requires appropriate permissions).

🛠️ Installation

Prerequisites

• None! The launcher scripts (start.bat for Windows, start.sh for Linux/Mac/Android) handle everything.
• They will automatically:
  • Check for Python and install it if missing.
  • Create a virtual environment to keep your system clean.
  • Download ADB (Android Debug Bridge) locally.
  • Install all required Python dependencies.

1. Clone the Repository

git clone https://github.com/cedroid/whatsapp-forensic-tool.git
cd whatsapp-forensic-tool

2. Run on PC (Windows/Linux/macOS)

Just double-click or run the launcher.

Windows:

start.bat

(If Python is not found, the script will guide you to the download page or attempt to install it.)

Linux / macOS:

bash start.sh

(Attempts to install Python 3 via apt or brew if missing.)

3. Run on Android (Termux)

You can deploy the tool from your PC to your phone easily:

1. Connect your phone to PC via USB.
2. Run the tool on PC and select "Deploy to Termux (Downloads)" from the main menu.
3. Open the Termux app on your phone and run:

   cp -r /sdcard/Download/whatsapp-forensic-tool $HOME
   cd $HOME/whatsapp-forensic-tool
   bash start.sh

📖 Usage Guide

Main Menu Options

1. Scan Connected Devices: Detects Android devices connected via ADB.
2. Dump Backups from Device: Scans the selected device for msgstore databases and key files.
3. Decrypt Existing Backup: Decrypts a local database using a key file (auto-detected or manual input).
4. View Decrypted Database: Browses chats, contacts, and messages from a decrypted DB.
5. Export Chats: Exports conversation threads to readable formats.
6. Deploy to Termux: (PC Only) Sends the tool to your phone for local execution.

How It Works

1. Connection: Uses ADB to bridge communication between PC and Android.
2. Extraction:
   • On PC: Pulls accessible files from /sdcard/WhatsApp or /sdcard/Android/media.
   • On Termux: Accesses internal storage directly via requested permissions.
3. Decryption:
   • For recent backups (crypt14/15), you need the 64-digit hexadecimal key.
   • This key is obtained when you enable "End-to-End Encrypted Backups" in WhatsApp Settings > Chats > Chat Backup.
   • If you don't have this key, you cannot decrypt E2E backups unless you have the root key file extracted from /data/data/com.whatsapp/files/key.
4. Analysis: Parses the SQLite database to reconstruct chat history and link media files.

📂 Project Structure

whatsapp-forensic-tool/
├── core/                   # Core modules
│   ├── crypto_manager.py   # Decryption logic (AES/GCM/CBC)
│   ├── device_manager.py   # ADB and file system abstraction
│   ├── termux_manager.py   # Android-native operations
│   ├── viewer.py           # SQLite parsing and data retrieval
│   ├── ui.py               # Rich text user interface
│   └── utils.py            # Helper functions and logging
├── main.py                 # Application entry point
├── start.bat               # Windows launcher
├── start.sh                # Linux/Mac/Termux launcher
└── requirements.txt        # Python dependencies

⚠️ Disclaimer

This tool is intended for educational and forensic analysis purposes only.

• Do not use this tool on devices you do not own or do not have explicit permission to analyze.
• The developer assumes no responsibility for unauthorized use or data loss.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.