This guide walks you through your first complete workflow: connecting a device, extracting backups, decrypting the database, and viewing chat messages.
Time to complete : 10-15 minutes (depending on backup size)
Prerequisites Before starting, ensure:
✅ Tool is installed and launches successfully
✅ Android device is connected via USB (PC mode) or Termux is running (Android mode)
✅ USB Debugging is enabled on the target device
✅ You have the 64-character decryption key (if backups are encrypted)
You must have the encryption key ready. This key is shown only once when you enable End-to-End Encrypted Backups in WhatsApp settings. Without it, decryption is impossible.
Start the application using the launcher script:
You’ll see the main menu:
=========================================== WhatsApp Backup Forensic Tool =========================================== Main Menu 1. Scan Connected Devices 2. Dump Backups from Device 3. Decrypt Existing Backup 4. View Decrypted Database 5. Export Chats 6. Deploy to Termux (Downloads) # PC only 7. Exit Enter choice:
Step 2: Connect and Scan Device
Connect Your Android Device
Connect your Android device via USB cable. If prompted on your phone, select:
File Transfer or MTP mode Allow USB Debugging (trust this computer) The device will remember this computer. You only need to authorize once.
Scan for Devices
Select option 1 (Scan Connected Devices): Enter choice: 1 [*] Scanning for devices... [✓] Found 1 device(s) Connected Devices ┌───┬──────────────┬────────────┬─────────┬────────────┐ │ # │ Serial │ Model │ Brand │ OS │ ├───┼──────────────┼────────────┼─────────┼────────────┤ │ 1 │ ABCD1234EFGH │ SM-G991B │ Samsung │ Android 13 │ └───┴──────────────┴────────────┴─────────┴────────────┘ [i] Auto-selected: ABCD1234EFGH
The tool automatically selects the device if only one is connected.
View Device Details
The tool displays comprehensive device information: Device Hardware ┌──────────────┬─────────────────────┐ │ Property │ Value │ ├──────────────┼─────────────────────┤ │ Model │ SM-G991B │ │ Brand │ Samsung │ │ Manufacturer │ samsung │ │ Device Name │ o1s │ │ Board │ universal9810 │ └──────────────┴─────────────────────┘ Software Info ┌─────────────────┬──────────┐ │ Property │ Value │ ├─────────────────┼──────────┤ │ Android Version │ 13 │ │ SDK API │ 33 │ │ Security Patch │ 2024-01 │ └─────────────────┴──────────┘ System Status ┌──────────────────┬────────────────────┐ │ Property │ Value │ ├──────────────────┼────────────────────┤ │ Battery Level │ 78% │ │ RAM Total │ 7.62 GB │ │ RAM Available │ 3.21 GB │ │ Internal Storage │ 89.3GB / 128GB │ └──────────────────┴────────────────────┘ Applications ┌──────────────────────┬──────────────────────────────────┐ │ Property │ Value │ ├──────────────────────┼──────────────────────────────────┤ │ WhatsApp Installed │ WhatsApp Messenger (com.whatsapp)│ └──────────────────────┴──────────────────────────────────┘
Step 3: Dump Backups from Device
Initiate Backup Scan
Return to the main menu and select option 2 (Dump Backups from Device): Enter choice: 2 [*] Scanning users on ABCD1234EFGH... [*] Found 1 user(s). Scanning packages... [*] Scanning for backup files... [✓] Found 3 backup files.
Select Backups to Dump
The tool displays all available backup files: Available Backups ┌───┬────────┬──────────┬──────────────────────────────────┬──────────┐ │ # │ User │ Type │ File │ Size │ ├───┼────────┼──────────┼──────────────────────────────────┼──────────┤ │ 1 │ User 0 │ WhatsApp │ msgstore.db.crypt15 │ 342.18 MB│ │ 2 │ User 0 │ WhatsApp │ msgstore-2024-03-01.db.crypt15 │ 338.92 MB│ │ 3 │ User 0 │ WhatsApp │ msgstore-2024-02-25.db.crypt15 │ 335.67 MB│ └───┴────────┴──────────┴──────────────────────────────────┴──────────┘ Dump Options 1. Dump All 2. Select Specific Files 3. Dump All WhatsApp Messenger 4. Dump All WhatsApp Business 5. Back Choice:
Select option 1 to dump all backups (recommended for first use).
Choose Media Extraction
The tool asks if you want to include media files: Selected 3 files to dump. Include Media? (y/n) [n]:
Enter n for faster backup (databases only)
Enter y to include all WhatsApp media (photos, videos, documents)
Media extraction can take 10-30 minutes depending on storage size. You can always extract media later.
Wait for Extraction
The tool pulls files from the device with a progress bar: Dumping Databases... ████████████████████████████████████████ 3/3 [00:45<00:00] [✓] Dump process completed.
Files are saved to: backups/<device_serial>/user_0/messenger/ Step 4: Decrypt a Backup Now decrypt the extracted backup file:
Select Decrypt Option
From the main menu, select option 3 (Decrypt Existing Backup): Enter choice: 3 Available Backups ┌───┬──────────────┬────────┬──────────┬───────────────────────────┐ │ # │ Device │ User │ Type │ File Name │ ├───┼──────────────┼────────┼──────────┼───────────────────────────┤ │ 1 │ ABCD1234EFGH │ User 0 │ WhatsApp │ msgstore.db.crypt15 │ │ 2 │ ABCD1234EFGH │ User 0 │ WhatsApp │ msgstore-2024-03-01... │ │ 3 │ ABCD1234EFGH │ User 0 │ WhatsApp │ msgstore-2024-02-25... │ └───┴──────────────┴────────┴──────────┴───────────────────────────┘ Select file (number): 1
Choose the most recent backup (usually the first one).
Enter Decryption Key
If no saved key exists, the tool prompts for the 64-character hexadecimal key: Enter 64-char hex key: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456 [*] Decrypting... [*] Decrypting msgstore.db.crypt15... [*] Scanning offsets for Derived Key... [✓] Decrypted with Derived Key (Offset 67) [✓] Saved to: backups/ABCD1234EFGH/user_0/messenger/msgstore.db.crypt15.decrypted.db [✓] Key saved securely for ABCD1234EFGH (com.whatsapp)
The key is saved in encrypted form to ~/.whatsapp-forensic-tool/keys.json (or AppData on Windows) for future use.
Decryption Process Explained
The decryption engine (crypto_manager.py:129-192) performs these steps:
Key Derivation : Derives AES key using HMAC-SHA256Offset Detection : Tries known offsets (67, 191, 8 bytes for IV)GCM Decryption : Uses AES-GCM with authenticationDecompression : Applies zlib decompression to the decrypted dataValidation : Verifies SQLite database header If decryption fails, the tool performs brute-force offset scanning (0-190 byte range). Step 5: View Decrypted Database
Open Database Viewer
Select option 4 (View Decrypted Database) from the main menu: Enter choice: 4 Decrypted Databases ┌───┬──────────┬────────────────────────────────────────┐ │ # │ Type │ File │ ├───┼──────────┼────────────────────────────────────────┤ │ 1 │ WhatsApp │ msgstore.db.crypt15.decrypted.db │ └───┴──────────┴────────────────────────────────────────┘ [*] Loading database...
The tool automatically connects to the decrypted SQLite database.
Browse Chat List
The viewer displays all chats sorted by last activity: DB: msgstore.db.crypt15.decrypted.db | Messages: 12,847 Chats (Page 1) ┌───┬──────────────────────┬──────────────────────────┬─────────────────┐ │ # │ Last Active │ JID │ Subject │ ├───┼──────────────────────┼──────────────────────────┼─────────────────┤ │ 1 │ 2024-03-05 14:32:18 │ [email protected] ... │ Mom │ │ 2 │ 2024-03-05 11:15:42 │ [email protected] ... │ Work Team │ │ 3 │ 2024-03-04 22:08:33 │ [email protected] ... │ John Smith │ │ 4 │ 2024-03-04 18:45:12 │ 1239874560-1616161616... │ Family Group │ └───┴──────────────────────┴──────────────────────────┴─────────────────┘ Showing 20 chats. Total: 156 Option [N=Next, P=Prev, B=Back, #=View Chat]:
View Messages in a Chat
Enter a chat number to view messages. Example - enter 1 : Chat: Mom ([email protected] ) Showing last 50 messages... ------------------------------------------------------------ [2024-03-05 14:32:18] Mom 📍 Location shared [2024-03-05 14:30:45] You On my way home now [2024-03-05 12:15:22] Mom Don't forget to pick up groceries [2024-03-05 11:08:33] You 👍 [2024-03-04 18:22:11] Mom 📎 IMG-20240304-WA0023.jpg ------------------------------------------------------------ Options: [M]ore, [A]ll, [B]ack [b]:
M - Load 50 more messagesA - Load all messages in the chatB - Return to chat list Step 6: Export Chats Export conversations to readable formats:
Open Export Menu
Select option 5 (Export Chats) from the main menu: Enter choice: 5 Select Database to Export From ┌───┬──────────┬────────────────────────────────────────┐ │ # │ Type │ File │ ├───┼──────────┼────────────────────────────────────────┤ │ 1 │ WhatsApp │ msgstore.db.crypt15.decrypted.db │ └───┴──────────┴────────────────────────────────────────┘ Select DB # (or Enter for current loaded): 1
Choose Export Scope
Select what to export: Export Options 1. All Chats 2. Single Chat 3. Back Choice: 1
All Chats - Exports every conversation (can take several minutes)Single Chat - Export a specific conversation by name or number
Select Export Format
Choose output format: Format 1. HTML 2. CSV 3. JSON 4. TXT 5. All Formats 6. Back Choice: 1
Format descriptions:
HTML - Rich formatted view with clickable media linksCSV - Spreadsheet-compatible (Excel, Google Sheets)JSON - Machine-readable structured dataTXT - Plain text transcriptAll Formats - Exports to all four formats simultaneously
Export Complete
The tool exports and opens the output folder: [*] Exporting... [✓] Exported to backups/ABCD1234EFGH/user_0/messenger/exports
On Windows, the exports folder opens automatically in File Explorer. HTML exports include relative links to media files if you dumped media in Step 3.
Example Output Files HTML Export Sample
CSV Export Sample
JSON Export Sample
Plain Text Export Sample
<! DOCTYPE html > < html > < head > < title > WhatsApp Chat: Mom </ title > < style > .message { padding : 10 px ; margin : 5 px ; border-radius : 8 px ; } .sent { background : #dcf8c6 ; text-align : right ; } .received { background : #ffffff ; } </ style > </ head > < body > < h1 > Chat with Mom ([email protected] ) </ h1 > < div class = "message received" > < strong > Mom </ strong > - 2024-03-05 14:32:18 < br > 📍 < a href = "https://maps.google.com/?q=40.7128,-74.0060" > Location </ a > </ div > < div class = "message sent" > < strong > You </ strong > - 2024-03-05 14:30:45 < br > On my way home now </ div > <!-- More messages... --> </ body > </ html >
Understanding the File Structure After completing the workflow, your directory structure looks like this:
whatsapp-forensic-tool/ ├── backups/ │ └── ABCD1234EFGH/ # Device serial │ └── user_0/ # User ID │ └── messenger/ # WhatsApp type │ ├── msgstore.db.crypt15 │ ├── msgstore.db.crypt15.decrypted.db │ ├── Media/ # If dumped │ │ ├── WhatsApp Images/ │ │ ├── WhatsApp Video/ │ │ ├── WhatsApp Audio/ │ │ └── WhatsApp Documents/ │ └── exports/ # Exported chats │ ├── [email protected] │ ├── [email protected] │ └── all_chats.html ├── adb/ # ADB platform tools │ └── platform-tools/ ├── venv/ # Python virtual environment ├── core/ # Application modules └── main.py # Entry point
Troubleshooting Common Issues
No devices found after scanning
Solutions:
Check USB cable is properly connected
Verify USB Debugging is enabled: Settings → Developer Options → USB Debugging
Try authorizing the computer again (tap “Allow” on device prompt)
Run adb devices manually from adb/platform-tools/ to check ADB connectivity
Possible causes:
WhatsApp hasn’t created a backup yet
Backups are stored in scoped storage (Android 11+)
Device uses encrypted backups stored in cloud only
Solution: In WhatsApp, go to Settings → Chats → Chat Backup and create a local backup manually.
Decryption failed with correct key
Reasons:
Wrong key for this specific backup
Corrupted backup file
Unsupported crypt format
Solution: Try an older backup file (option 2 or 3 in the list) or verify the key was copied correctly.
Database viewer shows empty chats
Reasons:
Database schema version incompatibility
Incomplete decryption
WhatsApp database format changed
Solution: Check that the decrypted file size matches the original encrypted file size (within 10%). If significantly smaller, decryption may have failed partially.
Media files not accessible in exports
Solution: Dump media files in Step 3 by selecting “y” when prompted “Include Media?”. HTML exports use relative paths to Media/ folders.
Next Steps Now that you’ve completed your first extraction, explore advanced features:
Decrypt Multiple Backups Process historical backups to view deleted messages or track conversation changes over time
Compare Backups Use the JSON export format to diff backup files and identify deleted or modified messages
Termux Mode Deploy to Android for direct device analysis without ADB limitations
Automation Scripts Use the core modules programmatically to automate batch processing of multiple devices
Tips for Forensic Analysis Best Practices:
Preserve originals : Always keep the original encrypted backups unmodifiedDocument everything : Note device serial, extraction date, and key sourceHash verification : Use SHA256 checksums to verify file integrityChain of custody : Maintain proper evidence handling proceduresExport immediately : Export to multiple formats immediately after successful decryption You’ve successfully completed your first WhatsApp forensic extraction. The tool is now ready for regular use in your forensic workflow. 