deep-search

Targeted file-type search inside .img disk images with a graphical interface.

Main script: deep-search-gui.py

What's New in v1.0.12

• Added optional forensic scan for deleted files.
• Added optional automatic recovery of deleted files to an external folder.
• Added manual forensic recovery for selected files directly from scan results.
• Added recovery tracking in CSV export (Deleted, Recovered, Recovery Path, Recovery Source).
• Added SHA-256 hashing for found files and recovered files.

Requirements

• Python 3.9+
• Tkinter (usually included with Python)
• pytsk3

Install dependencies:

pip install -r requirements.txt

Install pytsk3 in a virtual environment (venv)

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pytsk3

On Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install pytsk3

On Windows (Command Prompt):

python -m venv .venv
.venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install pytsk3

Install all project dependencies in the same venv:

pip install -r requirements.txt

Run

python3 deep-search-gui.py

Run inside venv

Linux/macOS:

source .venv/bin/activate
python deep-search-gui.py

Windows (PowerShell):

.\.venv\Scripts\Activate.ps1
python deep-search-gui.py

Windows (Command Prompt):

.venv\Scripts\activate.bat
python deep-search-gui.py

Linux Launcher (.desktop)

This project includes deep-search.desktop. The launcher icon is assets/deep-search-icon.svg.

Install it in the user applications menu:

chmod +x deep-search.desktop
cp deep-search.desktop ~/.local/share/applications/
update-desktop-database ~/.local/share/applications/ 2>/dev/null || true

Add it to the desktop as well:

cp deep-search.desktop ~/Desktop/
chmod +x ~/Desktop/deep-search.desktop

Main Features

• Select .img disk image files
• Filter by type (Documents, Images, Audio, Video, Archives, Executables, Code, All)
• Add custom extensions (for example: log,csv,bak)
• Scan partitions and internal filesystems
• Optional forensic deleted-file scan (Include deleted files)
• Optional automatic recovery of deleted files during scan (Recover deleted files)
• Manual recovery of selected files from the results table (Recover selected)
• External recovery folder selection for forensic output storage
• Stop an active scan at any time (Stop scan button)
• Live status counter during scanning (Found: N files, recovered: M)
• Sequential numbering of found files (# column)
• Result table includes deleted state and recovery path (Deleted, Recovery path)
• Export results to CSV with forensic fields and timestamped filename
• Open the last exported CSV quickly (Linux: xdg-open)

Forensic Workflow

1. Select a disk image.
2. Choose file type filters and optional extra extensions.
3. Enable Include deleted files (forensic scan) when you want deleted entries.
4. Enable Recover deleted files and choose an external Recovery folder for automatic deleted-file recovery.
5. Start the scan.
6. Optionally select one or more rows in the results table and click Recover selected for manual forensic recovery (allocated or deleted entries, when inode metadata is available).

Recovery is always performed by reading from the image through pytsk3 metadata access, without mounting partitions.

CSV Output

The exported CSV now includes:

• Filename
• File Path
• Deleted (Yes/No)
• Recovered (Yes/No)
• Recovery Path
• Recovery Source (deleted_auto_scan or selected_manual)
• Found SHA-256
• Recovered SHA-256

Screenshots

1. Main interface and image-file selection.

2. Search setup with type filters and custom extensions.

3. Scan results view with found files and CSV export.

Notes

The script reads filesystems directly from the disk image without mounting it. If some partitions are unsupported or damaged, they are skipped and the scan continues on the others.

For deleted files and manual recovery operations, extraction is best-effort. Some files may be partially recoverable or unrecoverable if data blocks are fragmented, overwritten, or not fully addressable from filesystem metadata.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Copyright (C) 2026 Alessandro Orlando

See the LICENSE file for details.