🚀 RECLAIM - Professional File Recovery Tool

Features • Requirements • Installation • Usage • Formats • Performance • Docs • License

📖 About

RECLAIM is a professional-grade, high-performance, cross-platform file recovery tool for recovering deleted files from RAW devices using signature-based file carving.

Built in Rust with focus on:

⚡ Performance: 940 MiB/s footer search throughput
🔒 Security: Multi-layer validation + U64 overflow protection
🎯 Accuracy: Rigorous integrity verification
🌍 Cross-Platform: Windows, Linux, macOS native support
📊 Reliability: Checkpoint + recovery system
🧵 Parallelization: Multi-threading with linear scaling
✨ Improvements: Rate limiting, U64 safe, checkpoint management

Recover your data safely through advanced file carving techniques (header/footer detection).

✨ Key Features

🎯 Efficient Recovery

Signature-based file carving - Automatic detection by header/footer
Rigorous validation - Format-specific integrity verification
Image reconstruction - Incomplete JPEG/PNG recovery
Automatic detection - Identifies format by byte pattern
Checkpoint system - Resume interrupted recoveries
Rate limiting - Intelligent bandwidth control (100 MB/s default)

🆕 Improvements (v1.1.0)

Feature	Benefit	Status
U64 Overflow Protection	Safe for disks > 4GB	✅ Implemented
Multi-threading	4-6x speedup on SSD/NVMe	✅ Feature-gated
Rate Limiter	I/O flood protection	✅ Sliding window
Checkpoint Manager	Automatic cleanup	✅ Versioned
ValidationReport Public	Safe inspection interface	✅ Public methods
CheckpointManager	Full lifecycle management	✅ Automatic

📋 Supported Formats

Format	Header	Footer	Max Size	Validation	Status
JPEG	`FF D8 FF`	`FF D9`	50 MB	✅ Complete	✅ Active
PNG	`89 50 4E 47 0D 0A 1A 0A`	`49 45 4E 44 AE 42 60 82`	50 MB	✅ Complete	✅ Active
PDF	`25 50 44 46`	`25 25 45 4F 46`	100 MB	✅ Partial	✅ Active
ZIP	`50 4B 03 04`	`50 4B 05 06`	500 MB	✅ Partial	✅ Active
BMP	`42 4D`	None	50 MB	⚠️ Minimal	✅ Active
GIF	`47 49 46 38`	`00 3B`	20 MB	✅ Partial	✅ Active

🌍 Cross-Platform

OS	Support	Implementation	Requirement
Windows 10+	✅ Native	Windows API (CreateFileW)	Admin
Linux (5.0+)	✅ Native	File syscalls + ioctl	sudo
macOS 10.15+	✅ Native	File syscalls (rdisk)	sudo

⚙️ Advanced Features

Feature	Description	Status
📄 Checkpoints	Resume recoveries	✅ JSON + versioning
📊 Telemetry	Performance metrics	✅ Arc
🎛️ Rate Limiting	Bandwidth control	✅ Sliding window 1s
🥗 Health Checks	5 pre-operation validations	✅ Device, output, disk, memory, perms
🛡️ Security	Path traversal + validation	✅ Defense in depth
📈 Progress Visual	Real-time indicator	✅ indicatif with ETA
💾 Buffer Pool	RAII with auto-release	✅ 8.7x vs malloc
🧵 Parallelization	Multi-threading (feature flag)	✅ Linear scaling ≤8T
🧪 Validation	SHA-256 + metadata	✅ Per-format
🔨 Reconstruction	JPEG/PNG incomplete	✅ jpeg-decoder + image

📊 Performance

Benchmarks Real (v1.1.0)

├─ Footer Search        940 MiB/s  ✅ Excellent
├─ File Carving         416 MiB/s  ✅ Very Good
├─ Buffer Pool ops      13 ns      ⚡ Ultra-fast
├─ RecoveryStats (U64)  1.5 ns     ⚡ Lock-free
├─ Rate Limiter         <1ms       ✅ Sliding window
├─ Multithreaded (4T)   207 µs     ✅ Scalable
└─ Multithreaded (8T)   415 µs     ✅ Linear

Estimated Times per Disk

Disk Type	Speed	Time for 1TB	Notes
HDD 7200 RPM	50-100 MB/s	~2.8 hours	Single-thread better
SSD SATA	200-500 MB/s	~42 minutes	4 threads ideal
SSD NVMe	500+ MB/s	~15-30 minutes	8 threads ideal

Note: Times with multi-threading enabled via --features parallel

⚙️ Requirements

Operating System

Requirement	Windows	Linux	macOS
Min Version	10	Kernel 5.0+	10.15+
Architecture	x86_64	x86_64	x86_64 + arm64
Privileges	Admin	sudo	sudo

Rust & Tools

Rust: 1.70 or higher (install here)
Cargo: Included with Rust
Git: For cloning repository (optional)

System Resources

Resource	Minimum	Recommended
RAM	512 MB	2 GB
Disk	100 MB (app)	1 GB (app + buffer)
CPU	1 core	4+ cores

🚀 Installation

Option 1: Via Cargo (Recommended)

Single-thread (default):

cargo install --path .

# Verify
reclaim --version

Multi-thread (optimized for SSD/NVMe):

cargo install --path . --features parallel

# Or with all features
cargo install --path . --features full

✅ Simplest | ⏱️ ~2 minutes

Option 2: Build from Source

# Clone repository
git clone https://github.com/Paulogb98/reclaim.git
cd reclaim

# Compile (release = optimized)
cargo build --release

# Or with features
cargo build --release --features parallel

# Executable at: target/release/reclaim
./target/release/reclaim --help

# Install globally (optional)
cargo install --path .

✅ Full control | ⏱️ ~3 minutes

Option 3: Via Homebrew (macOS)

brew install reclaim

✅ Native macOS integration | ⏱️ ~1 minute

Option 4: Pre-compiled Binaries

Download from: https://github.com/Paulogb98/reclaim/releases

✅ No compilation needed | ⏱️ ~30 seconds

📖 Usage

General Syntax

reclaim <COMMAND> [OPTIONS]

Available Commands

1. Recover - Recover Files

reclaim recover --drive <LETTER/PATH> --format <FORMAT> [OPTIONS]

# Examples:
# Windows
reclaim recover --drive C --format jpeg --output D:\Recovered

# Linux
sudo reclaim recover --drive /dev/sda --format jpeg --output ./recovered

# macOS
sudo reclaim recover --drive /dev/disk0 --format jpeg --output ./recovered

# With checkpoint
reclaim recover --drive C --format jpeg --output D:\Recovered \
  --resume ./checkpoints/checkpoint_C_jpeg.json \
  --checkpoint-interval 50

Options:

--drive, -d (required) - C, D, /dev/sda, /dev/disk0
--format, -f (default: jpeg) - jpeg, png, pdf, zip, bmp, gif
--output, -o (default: ./recovered) - Destination directory
--resume, -r (optional) - Checkpoint path
--checkpoint-interval (default: 100) - Interval in MB

2. ListFormats - List Supported Formats

reclaim list-formats

# Output:
# 🔍 SUPPORTED FORMATS:
# ======================================================================
#   1. JPEG (.jpg)
#   2. PNG (.png)
#   3. PDF (.pdf)
#   ...

3. ListDevices - List Available Devices

reclaim list-devices

# Output:
# 📁 AVAILABLE DEVICES:
# ======================================================================
#   1. C:
#      Path: \\.\C:
#      Size: 931.51 GB
#      Removable: No
#   ...

4. Analyze - Analyze File

reclaim analyze --file ./recovered_00001.jpg

# Output:
# ✅ Format detected: jpeg (.jpg)
# 📋 VALIDATION REPORT:
# ======================================================================
# Status: ✅ VALID
# Size: 512000 bytes (500.00 KB)
# SHA-256: abc123def456...
# Dimensions: 1920x1080
# ...

5. CheckDevice - Verify Device

reclaim check-device --drive C

# Output:
# ✅ Device accessible: \\.\C:
#    Total size: 931.51 GB
#    Removable: No
#    ...

6. Validate - Validate Configuration

reclaim validate --drive C --format jpeg --output D:\Recovered

# Output:
# ============================================================
# 🔍 VALIDATION REPORT
# ============================================================
# ✅ Status: VALID
# ✅ Checks:
#   • Drive validated against traversal
#   • Format 'jpeg' supported
#   • Output path validated
# ============================================================

💡 Practical Examples

Recover JPEGs from Drive C

# Windows
reclaim recover -d C -f jpeg -o D:\Fotos

# Linux
sudo reclaim recover -d /dev/sda -f jpeg -o ~/fotos

# macOS
sudo reclaim recover -d /dev/disk0 -f jpeg -o ~/fotos

Recover Multiple Formats

# JPEGs
reclaim recover -d C -f jpeg -o D:\Recovered\JPEG

# Then PNGs
reclaim recover -d C -f png -o D:\Recovered\PNG

# Then PDFs
reclaim recover -d C -f pdf -o D:\Recovered\PDF

Resume Interrupted Recovery

# First attempt
reclaim recover -d C -f jpeg -o D:\Recovered
# [Ctrl+C to stop]

# Resume
reclaim recover -d C -f jpeg -o D:\Recovered \
  --resume ./checkpoints/checkpoint_C_jpeg.json

With Detailed Logging

# Windows
$env:RUST_LOG="reclaim=debug"
reclaim recover -d C -f jpeg -o D:\Recovered

# Linux/macOS
RUST_LOG=reclaim=debug reclaim recover -d /dev/sda -f jpeg -o ~/recovered

Background Recovery (No System Impact)

# Linux/macOS
RECLAIM_RATE_LIMIT=52428800 nice -n 19 \
  reclaim recover -d /dev/sdb -f jpeg -o ./background_recovery
# 50 MB/s rate limit + nice priority 19

# Windows PowerShell
$env:RECLAIM_RATE_LIMIT = "52428800"
reclaim recover -d E -f jpeg -o ./background_recovery

🏗️ Architecture

Layered Vision

┌──────────────────────────────────────────┐
│         CLI Layer (cli.rs)               │
│    Argument parsing (Clap)               │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│    Validation Layer                      │
│  (validation.rs, health.rs, security.rs) │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│   Business Logic Layer                   │
│  (recovery/*, carver.rs, validator.rs)   │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│  Infrastructure Layer                    │
│ (config.rs, models.rs, formats.rs, etc.) │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│   OS Abstraction Layer                   │
│  (device/platform/{windows,linux,macos}) │
└──────────────────────────────────────────┘

For detailed architecture: See ARCHITECTURE.md

🧪 Testing

# All tests
cargo test

# Specific module tests
cargo test recovery::

# With full output
cargo test -- --nocapture --test-threads=1

# Ignored tests
cargo test -- --ignored

# Integration tests only
cargo test --test integration_tests

📊 Benchmarks

# Run benchmarks
cargo bench --bench scanner_bench

# Save baseline
cargo bench -- --save-baseline v1.1.0

# Compare against baseline
cargo bench -- --baseline v1.1.0

# Generate HTML reports
cargo bench -- --plotting-backend gnuplot

For complete analysis: See BENCHMARK.md

📚 Complete Documentation

Document	Description	Audience
README.md	This file - Overview	Everyone
ARCHITECTURE.md	Technical design	Developers
DESIGN_DECISIONS.md	Why each decision	Architects
PERFORMANCE.md	Tuning & optimization	DevOps/Ops
SECURITY.md	Safety measures	SecOps
DEPLOYMENT.md	Build & release	DevOps
TROUBLESHOOTING.md	Problem solving	Support
CONTRIBUTING.md	How to contribute	Contributors
BENCHMARK.md	Performance analysis	Optimizers

🤝 Contributing

Contributions welcome!

Fork the repository
Create branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'feat: add AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Open Pull Request

Desired Contribution Areas

✅ New file formats
✅ Performance optimizations (SIMD, Boyer-Moore)
✅ UX/messaging improvements
✅ Documentation
✅ Additional tests
✅ New platform support

Read: CONTRIBUTING.md

🛠️ Quick Troubleshooting

❌ "Failed to open device"

Windows: Run as Administrator
Linux/macOS: Use sudo
Check: reclaim list-devices

❌ "Invalid drive"

Windows: Use letter (C, D, E)
Linux: Use /dev/sdX
macOS: Use /dev/diskX

❌ "No files found"

Try different format
Data may be overwritten
Use: RUST_LOG=debug reclaim recover...

For more: See TROUBLESHOOTING.md

📞 Contact & Support

Channel	Type	Response Time
GitHub Issues	Bugs/Features	24-48h
GitHub Discussions	Questions	24-48h
Email	Urgent/Security	12-24h

📧 [email protected]

📄 License

MIT License - Simple and permissive

MIT License

Copyright (c) 2024 Paulo G.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

🙏 Acknowledgments

✨ Rust community
📦 Crates: clap, indicatif, image, jpeg-decoder, serde, tracing
🤝 All contributors and testers
❤️ Users who report bugs and suggestions

📊 Project Status

Aspect	Status	Details
Development	✅ Active	Issues and PRs accepted
Production	✅ Ready	v1.1.0 stable
Testing	✅ Complete	60+ unit, 15+ integration
Performance	✅ Optimized	940 MiB/s footer search
Security	✅ Audited	Defense in depth + U64
Documentation	✅ Complete	5,700+ lines

🚀 Roadmap

✅ V1.1.0 (Current)

✅ File carving recovery
✅ 6 supported formats
✅ Checkpoints + resumption
✅ Multi-threading (feature flag)
✅ Complete telemetry
✅ Health checks (5 validations)
✅ Security (defense in depth)
✅ U64 overflow protection
✅ Rate limiting sliding window
✅ CheckpointManager lifecycle

📋 V2.0 (Planned)

📋 SIMD for footer search (+50%)
📋 Boyer-Moore algorithm (+30%)
📋 Memory mapping (> 1GB files)
📋 Plugin system
📋 GPU acceleration

💭 V3.0+ (Future)

💭 Cloud storage integration
💭 Web UI
💭 Distributed recovery
💭 ML-based reconstruction

Built with ❤️ in Rust

🏗️ Architecture • 🔧 Troubleshooting • 🤝 Contributing • ⚙️ Performance

RECLAIM v1.1.0 | ✅ Production Ready | 📅 2025-11-02

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
assets		assets
benches		benches
config		config
docs		docs
src		src
tests		tests
.gitignore		.gitignore
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

License

Paulogb98/Reclaim

Folders and files

Latest commit

History

Repository files navigation