Quick Start - WhatsApp Forensic Tool

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.

Step 1: Launch the Tool

Start the application using the launcher script:

start.bat

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-SHA256
Offset Detection: Tries known offsets (67, 191, 8 bytes for IV)
GCM Decryption: Uses AES-GCM with authentication
Decompression: Applies zlib decompression to the decrypted data
Validation: 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  │ 1234567890@s.whatsapp... │ Mom             │
│ 2 │ 2024-03-05 11:15:42  │ 9876543210@s.whatsapp... │ Work Team       │
│ 3 │ 2024-03-04 22:08:33  │ 5551234567@s.whatsapp... │ 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 (1234567890@s.whatsapp.net)
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 messages
A - Load all messages in the chat
B - 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
HTML
CSV
JSON
TXT
All Formats
Back

Choice: 1

Format descriptions:

HTML - Rich formatted view with clickable media links
CSV - Spreadsheet-compatible (Excel, Google Sheets)
JSON - Machine-readable structured data
TXT - Plain text transcript
All 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

<!DOCTYPE html>
<html>
<head>
    <title>WhatsApp Chat: Mom</title>
    <style>
        .message { padding: 10px; margin: 5px; border-radius: 8px; }
        .sent { background: #dcf8c6; text-align: right; }
        .received { background: #ffffff; }
    </style>
</head>
<body>
    <h1>Chat with Mom (1234567890@s.whatsapp.net)</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
│                   ├── chat_1234567890@s.whatsapp.net.html
│                   ├── chat_1234567890@s.whatsapp.net.csv
│                   └── 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

No backup files found

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 unmodified
Document everything: Note device serial, extraction date, and key source
Hash verification: Use SHA256 checksums to verify file integrity
Chain of custody: Maintain proper evidence handling procedures
Export 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.

​Prerequisites

​Step 1: Launch the Tool

​Step 2: Connect and Scan Device

​Step 3: Dump Backups from Device

​Step 4: Decrypt a Backup

​Step 5: View Decrypted Database

​Step 6: Export Chats

​Example Output Files

​Understanding the File Structure

​Troubleshooting Common Issues

​Next Steps

Decrypt Multiple Backups

Compare Backups

Termux Mode

Automation Scripts

​Tips for Forensic Analysis

Prerequisites

Step 1: Launch the Tool

Step 2: Connect and Scan Device

Step 3: Dump Backups from Device

Step 4: Decrypt a Backup

Step 5: View Decrypted Database

Step 6: Export Chats

Example Output Files

Understanding the File Structure

Troubleshooting Common Issues

Next Steps

Tips for Forensic Analysis