• Android devices (connected via USB with ADB debugging enabled)
• Direct Android execution via Termux app
• PC platforms: Windows, Linux, and macOS

• When using ADB mode (PC), the tool can extract backups from accessible storage locations (/sdcard/WhatsApp)
• When running via Termux on Android, storage permissions are requested to access internal storage

​

64-Character Hexadecimal Key (Recommended)

1. Open WhatsApp > Settings > Chats > Chat Backup
2. Enable “End-to-end encrypted backups”
3. Choose “Use 64-digit encryption key”
4. Save this key immediately - you cannot retrieve it later

​

Root-Extracted Key File

/data/data/com.whatsapp/files/key
/data/data/com.whatsapp.w4b/files/key (Business)

• crypt12 - Older WhatsApp backup format (AES-GCM encryption)
• crypt14 - Current standard format
• crypt15 - Latest format with enhanced security

• Known offset patterns for IV and ciphertext
• Brute-force offset scanning for non-standard layouts
• Both raw and derived key methods
• Automatic decompression (zlib)

• If you have the 64-character hexadecimal key saved when you enabled E2E encrypted backups, the tool can decrypt them
• Without this key, E2E encrypted backups cannot be decrypted unless you have root access to extract the key file from the device’s protected storage

1. Enable USB Debugging:
   • Go to Settings > About Phone
   • Tap “Build Number” 7 times to enable Developer Mode
   • Go to Settings > Developer Options
   • Enable “USB Debugging”
2. Check USB Connection:
   • Use a data-capable USB cable (not charge-only)
   • Try different USB ports
   • Accept any authorization prompts on your phone
3. Verify ADB Installation:
   • The tool auto-installs ADB, but you can manually verify by running:
   adb devices
   
4. Restart ADB Server:
   adb kill-server
   adb start-server
   
5. Check Drivers (Windows):
   • Install your device manufacturer’s USB drivers
   • Try using Google’s Universal ADB Driver

​

Deployment Method:

1. Connect your phone to your PC via USB
2. Run the tool on PC and select “Deploy to Termux (Downloads)”
3. Install Termux from F-Droid (not Play Store)
4. Open Termux and run:
   cp -r /sdcard/Download/whatsapp-forensic-tool $HOME
   cd $HOME/whatsapp-forensic-tool
   bash start.sh
   

​

Manual Installation:

pkg update && pkg upgrade
pkg install git python
git clone https://github.com/cedroid/whatsapp-forensic-tool.git
cd whatsapp-forensic-tool
bash start.sh

​

Database Content:

• Chat messages (text, media references)
• Contact information and JIDs (WhatsApp IDs)
• Group information and participants
• Message timestamps and metadata
• Message status (sent, delivered, read)
• Deleted message indicators (if present in database)

​

Media Files:

• Images and photos
• Videos
• Audio messages and voice notes
• Documents (PDF, DOCX, etc.)
• Stickers and GIFs

​

Export Formats:

• HTML: Formatted chat view with media links
• CSV: Spreadsheet-compatible format
• JSON: Structured data for programmatic analysis
• TXT: Plain text readable format

​

Legal Uses:

• Analyzing your own device and data
• Forensic investigation with proper authorization
• Educational purposes and security research
• Parental monitoring with legal custody rights
• Corporate investigations with employee consent

​

Illegal Uses:

• Accessing someone else’s data without consent
• Unauthorized surveillance or spying
• Violating computer fraud laws (CFAA, etc.)
• Breaking data protection regulations (GDPR, etc.)

• iOS WhatsApp backups use iCloud with different encryption
• iOS file system structure is completely different
• ADB doesn’t work with iOS devices
• Different database formats and schemas

• Detect if Python is installed
• Attempt to install Python if missing (Windows via installer, Linux via apt, macOS via brew)
• Create a virtual environment to isolate dependencies
• Install all required packages from requirements.txt

​

Manual Installation:

# Install Python 3.8+
python3 --version  # Verify installation

# Clone and run
git clone https://github.com/cedroid/whatsapp-forensic-tool.git
cd whatsapp-forensic-tool
bash start.sh  # or start.bat on Windows

​

Modern Android (11+):

/sdcard/Android/media/com.whatsapp/WhatsApp/Databases/
/sdcard/Android/media/com.whatsapp.w4b/WhatsApp Business/Databases/

​

Legacy Android:

/sdcard/WhatsApp/Databases/
/sdcard/WhatsApp Business/Databases/

​

Backup Files:

• msgstore.db.crypt15 - Latest backup (crypt15 format)
• msgstore.db.crypt14 - Previous format backups
• msgstore-YYYY-MM-DD.1.db.cryptXX - Older dated backups

1. Format Detection: Identifies crypt12, crypt14, or crypt15 format
2. Key Derivation:
   • For crypt14/15: Derives the actual AES key using HMAC-SHA256
   • For crypt12: Uses the key directly
3. IV Extraction: Locates the Initialization Vector in the encrypted file header
4. Decryption: Uses AES-GCM cipher to decrypt the ciphertext
5. Decompression: Decompresses the decrypted data using zlib
6. Validation: Verifies the result is a valid SQLite database

• Tries known offset patterns first (fast)
• Falls back to brute-force scanning if needed (slower but comprehensive)

• Code style guidelines
• Fork and pull request workflow
• Issue reporting templates
• Feature request process
• Testing requirements

1. Verify the key:
   • Ensure it’s exactly 64 hexadecimal characters
   • No spaces or special characters
   • Case doesn’t matter (hex is case-insensitive)
2. Check the backup format:
   • Confirm the file extension matches the actual format
   • Try a different backup file from the same device
3. Key mismatch:
   • The key must match the device and WhatsApp installation
   • Different devices have different keys
   • Reinstalling WhatsApp generates a new key
4. Corrupted backup:
   • Try an older backup file
   • Re-extract the backup from the device

1. Check existing issues on GitHub first
2. Gather information:
   • Tool version
   • Operating system
   • Android version (if applicable)
   • Error messages or logs
   • Steps to reproduce
3. Submit an issue on GitHub with details
4. Or email: [email protected]