SageThumbs.db3 Recovery Tool

A read-only recovery and forensic-analysis utility for SageThumbs.db3 caches created by SageThumbs on Windows.

The tool analyzes the SQLite cache, recovers surviving image BLOBs, preserves original path information, calculates cryptographic hashes, validates recovered image data, identifies duplicate cached images, and produces forensic reports.

Features

• Read-only SQLite database access
• SQLite integrity_check and quick_check
• Enumeration of Pathes and Entities
• Recovery of surviving image BLOBs
• JPEG, PNG, GIF, WebP, BMP and ICO signature detection
• Optional Pillow-based image validation
• SHA-256 and MD5 hashes
• Duplicate-thumbnail analysis
• Recovery manifest in CSV format
• Empty-BLOB report
• Creation/last-write timeline
• Conservative decoding of known ImageInfo fields
• Collision-safe output filenames
• Preservation of original Windows path information
• Optional searchable HTML galleries
• Human-readable forensic recovery report

Forensic design

The source database is opened using SQLite's read-only mode.

The source SageThumbs.db3 is never modified by the tool.

For forensic work:

1. Preserve the original evidence separately.
2. Work from a forensic acquisition or verified working copy.
3. Record the source database hash before analysis.
4. Run the tool against the working copy.
5. Preserve the generated reports and recovered files.
6. Correlate the results with other forensic artifacts.

An Empty BLOB finding means that an Entities record exists but its Image BLOB is NULL or zero-length. It does not, by itself, prove that the corresponding original source file was deleted.

Requirements

• Python 3.9 or newer
• Pillow

Install the dependency:

python -m pip install -r requirements.txt

Recommended virtual-environment setup:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Usage

Default

python .\sagethumbs_recover.py

The default input is:

SageThumbs.db3

and the default output directory is:

SageThumbs_Recovered

Specify a database

python .\sagethumbs_recover.py --database "C:\Evidence\SageThumbs.db3"

Specify an output directory

python .\sagethumbs_recover.py `
    --database "C:\Evidence\SageThumbs.db3" `
    --output "C:\Case\Recovered\SageThumbs"

Generate HTML galleries

Gallery generation is disabled by default.

Enable it with:

python .\sagethumbs_recover.py `
    --database "C:\Evidence\SageThumbs.db3" `
    --output "C:\Case\Recovered\SageThumbs" `
    --gallery

The gallery is a convenience view and should not replace the CSV manifest or other forensic records.

Command-line interface

A typical run looks like:

==============================================================================
  SageThumbs.db3 Recovery Tool v1.0
  Read-only recovery and forensic analysis
==============================================================================

[+] Evidence
  Database : C:\Evidence\SageThumbs.db3
  Output   : C:\Case\Recovered\SageThumbs
  Pillow   : AVAILABLE
  Access   : READ-ONLY

[+] SQLite integrity
  integrity_check : OK
  quick_check     : OK

[+] Recovery
  Pathes   : 639
  Entities : 8,292

  Processed 8,250/8,292 | Recovered 8,052 | Empty BLOBs 198
  Processed 8,292/8,292 | Recovered 8,092 | Empty BLOBs 200

[+] Complete
  Entities processed : 8,292
  Cached images      : 8,092
  Cached but invalid : 0
  Empty BLOBs        : 200
  Extraction errors  : 0
  Recovered data     : ...
  Duplicate groups   : ...
  Gallery            : DISABLED (default)

  The source database was not modified.

Recovered and Empty BLOBs are cumulative counters. The final progress line is always printed, even when the total entity count is not an exact multiple of 250.

Output

A normal run produces:

SageThumbs_Recovered/
├── manifest.csv
├── missing_thumbnails.csv
├── duplicates.csv
├── timeline.csv
├── recovery_report.txt
└── recovered files...

When --gallery is enabled:

├── gallery.html
└── missing_gallery.html

manifest.csv

The primary machine-readable recovery manifest.

It contains:

• database record IDs
• original paths
• original filenames
• original file size
• original dimensions when available
• thumbnail dimensions
• raw and interpreted timestamps
• ImageInfo metadata
• cached image size
• detected format
• validation status
• SHA-256
• MD5
• extracted filename
• extraction errors

missing_thumbnails.csv

Despite the historical filename, this report specifically records empty or NULL Image BLOBs.

An entry means the database record exists but no cached image bytes are currently present in that record.

duplicates.csv

Lists recovered records that share the same SHA-256 digest.

timeline.csv

Contains CreationTime and LastWriteTime events with both raw database values and interpreted timestamps.

recovery_report.txt

Human-readable summary covering:

• SQLite integrity
• database counts
• recovery classifications
• image formats
• validation results
• hash and duplicate statistics
• recovered byte count
• decoded ImageInfo fields
• forensic interpretation notes

Recovery classifications

CACHED_IMAGE

Image data existed, was extracted successfully, and Pillow validation succeeded.

CACHED_IMAGE_INVALID

Image data existed and was extracted, but validation did not establish it as a valid image.

NO_SURVIVING_THUMBNAIL

The Entities record exists, but the Image BLOB is NULL or zero-length.

This is reported in the interface as Empty BLOBs.

This finding does not prove deletion of the original source file.

EXTRACTION_ERROR

Image data existed, but the recovered bytes could not be written to the output location.

Image validation

The tool first examines the binary image signature.

When Pillow is installed, the recovered data is also opened and passed through Image.verify().

Validation describes the recovered cached bytes. It does not establish the condition of the original source image.

Hashes

Each recovered image BLOB is hashed with:

• SHA-256
• MD5

SHA-256 is the preferred evidentiary identifier. MD5 is retained for compatibility and comparison.

Hashes are calculated over the cached BLOB exactly as stored in the database.

ImageInfo

The current decoder conservatively handles the known 192-byte structure and extracts:

0x04  Original width
0x08  Original height
0x10  Codec identifier
0x18  Codec description
0x64  Original FileSize for JPEG ImageInfo

Unknown or malformed structures are reported rather than guessed.

Evidence handling

Do not:

• modify the original evidence database;
• treat an Empty-BLOB finding as proof of source-file deletion;
• treat the HTML gallery as the primary evidence record;
• discard raw timestamp values;
• silently overwrite recovered files.

Keep recovered files associated with their manifest records and preserve the generated reports.

Limitations

This is a SageThumbs database recovery utility, not a general filesystem undelete or file-carving program.

It cannot:

• recover thumbnail bytes that no longer exist in the database;
• reconstruct an original full-quality image from a thumbnail;
• prove source-file deletion solely from an Empty-BLOB finding;
• guarantee identical internal structures across every SageThumbs release;
• replace a complete forensic examination.

Repository layout

SageThumbs-Recovery/
├── sagethumbs_recover.py
├── README.md
├── requirements.txt
├── LICENSE
├── .gitignore
└── .github/
    └── workflows/
        └── python.yml

Development

Run a basic syntax check:

python -m py_compile .\sagethumbs_recover.py

Install dependencies:

python -m pip install -r requirements.txt

License

This project is released under the MIT License. See LICENSE.

Disclaimer

This software is intended for legitimate forensic examination, incident response, research and data-recovery purposes. The user is responsible for ensuring that its use complies with applicable law, organizational policy and evidence-handling requirements.