ForensicScanner

A Python-based digital forensics toolkit built for evidence collection, integrity verification, and reporting. Designed as a portfolio project for a career in digital forensics and federal law enforcement.

Features

• Chain of custody — MD5 + SHA-256 hashing of every scanned file
• Timestamps — created, modified, and accessed times for timeline reconstruction
• EXIF extraction — GPS coordinates, device info, and capture timestamps from images
• PDF metadata — author, creator, producer, and date fields
• Keyword search — scan text files for keywords or regex patterns with context snippets
• File signature verification — detect extension/header mismatches (renamed or hidden files)
• Duplicate detection — group files by SHA-256 hash regardless of filename
• Timeline view — visual timeline grouped by day with suspicious time-cluster alerts
• Case management — timestamped case folders with JSON + HTML output
• Dark-themed HTML reports — professional forensics aesthetic

Requirements

• Python 3.12+
• macOS (developed on Apple M1)

Install

pip install -r requirements.txt

Usage

# Basic scan
python forensic_scanner.py ./evidence "Det. Smith"

# Keyword search
python forensic_scanner.py ./evidence --keywords "password,confidential,API key"

# Keywords from file
python forensic_scanner.py ./evidence --keywords-file keywords.txt

# Filter by file type
python forensic_scanner.py ./photos --type image

# Skip subdirectories
python forensic_scanner.py ./evidence --no-recurse

# Custom report filename
python forensic_scanner.py ./evidence --output my_report.html

# Literal (non-regex) keyword matching
python forensic_scanner.py ./evidence --keywords "exact phrase" --literal-keywords

CLI Options

Flag	Description
path	Directory or file to scan
investigator	Investigator name (optional positional arg)
--keywords, -k	Comma-separated keywords or regex patterns
--keywords-file, -kf	File with one keyword per line
--output, -o	Custom report filename
--no-recurse	Do not scan subdirectories
--type, -t	Filter: image, pdf, video, other
--case-name	Custom case folder name
--literal-keywords	Treat keywords as literal strings

Output Structure

Each scan creates a case folder:

cases/
└── 20250607_201530_evidence/
    ├── scan_results.json
    └── forensic_report_20250607_201530.html

Project Structure

forensics-lab/
├── forensic_scanner.py       # CLI entry point
├── modules/
│   ├── hasher.py             # MD5 / SHA-256
│   ├── metadata.py           # EXIF and PDF extraction
│   ├── keyword_search.py     # Content keyword scanning
│   ├── file_signature.py     # Magic byte verification
│   ├── duplicates.py         # SHA-256 duplicate grouping
│   ├── case_manager.py       # Case folders and JSON export
│   └── report.py             # HTML report generation
└── requirements.txt

License

Personal portfolio project — built for educational and professional development purposes.