DiskSpade

A Python-based file carving tool that recovers deleted or embedded files from raw disk images by scanning for known file signatures (magic bytes).

What it does

DiskSpade scans a raw disk image (.dd, .img, .raw) byte-by-byte for the header patterns of common file types. When a header is found, it scans forward for the matching footer, records the offset and size, and (optionally) writes the recovered bytes out as a standalone file with an MD5/SHA256 hash and a python-magic type check.

This works independent of the filesystem's own metadata. It's the same core technique used by tools like foremost, scalpel, and photorec.

Recovers: JPEG, PNG, PDF, ZIP, DOCX, MP4

Installation

git clone https://github.com/logandehning/DiskSpade.git
cd diskspade
pip install -e .

Or with pip's dev extras (for running tests):

pip install -e ".[dev]"

DiskSpade also uses python-magic, which wraps the system libmagic library. On Debian/Ubuntu you may need:

sudo apt install libmagic1

Usage

# Scan an image and recover every known file type into ./output
diskspade --image disk.dd --output ./output

# Only look for specific types
diskspade --image disk.dd --output ./output --types jpeg,png,pdf

# Report findings without writing any files
diskspade --image disk.dd --dry-run

# Print the full report to stdout as well as writing report files
diskspade --image disk.dd --output ./output --verbose

Each run writes:

• The recovered files themselves, named recovered_NNNN_0xOFFSET.ext (partial/truncated carves get a _PARTIAL suffix)
• report.json - machine-readable summary (offsets, sizes, hashes, types)
• report.txt - the same summary in human-readable form

Generating a test image

No real disk image handy? Build a synthetic one with known planted files:

python scripts/make_test_image.py samples/test.dd
diskspade --image samples/test.dd --output output --verbose

Project layout

diskspade/
├── src/diskspade/
│   ├── signatures.py   # file type → header/footer magic-byte definitions
│   ├── scanner.py      # scans an image, finds matches (no file I/O)
│   ├── extractor.py    # writes matches to disk, hashes, validates type
│   ├── report.py        # builds the JSON/text forensic report
│   └── cli.py          # argparse-based command line interface
├── tests/              # pytest unit tests
├── scripts/            # helper scripts (e.g. synthetic test image builder)
├── samples/            # test disk images (gitignored)
└── output/             # recovered files + reports (gitignored)

Running tests

Make sure dev dependencies are installed (see Installation above), then:

pytest

For more detail on individual test results:

pytest -v

You should see 15 tests pass, covering the signature engine, scanner (header/footer matching, partial carves, edge cases), and extractor (hashing, dry-run behavior, file naming).

Known limitations (v1)

See docs/FORENSICS_NOTES.md for a deeper discussion, but in short:

• PDF and DOCX are carved with a simple header-footer scan. Real PDFs can contain multiple %%EOF markers (incremental updates), and DOCX is itself a ZIP container. Both can produce imperfect carves on complex real-world files.
• No fragmented file reconstruction. If a file's data is split into non-contiguous fragments on disk, DiskSpade will only recover the contiguous portion between header and footer (or up to the size cap). Reassembling fragmented files is a stretch goal for v2.
• No encrypted volume support.

Legal / Ethical use

Only run DiskSpade against disk images you own or are explicitly authorized to analyze (e.g. your own test images, or evidence you have legal authority to examine as part of an investigation). Recovering files from storage media you don't have authorization to access may be illegal in your jurisdiction.

Roadmap (v2 / stretch goals)

• Fragmented file reconstruction via entropy analysis
• YARA rule integration for scanning carved files for IOCs
• Simple web UI (Flask)
• Pip-installable single binary
• E01 (EnCase) image format support

License

MIT