carving.hpp

Go to the documentation of this file.

// carving.hpp -- file-system-agnostic file carving via magic signatures.
//
// File carving recovers files by scanning the raw disk for known magic
// byte sequences. It works when filesystem metadata (MFT / inode table /
// catalog B-tree) is destroyed but the file content is still intact on
// disk. It complements the per-filesystem recovery -- carving runs
// when filesystem recovery has been tried, OR when the user explicitly
// asks to carve unallocated space.
//
// Core pipeline:
//   1. Read the disk in chunks (16 MiB by default), with a sliding
//      overlap so that magic bytes spanning a chunk boundary are not
//      missed.
//   2. For each chunk, scan for known magic byte sequences at every
//      byte offset (Boyer-Moore not needed; the inner loop is small
//      enough to be fast with a simple match).
//   3. When a magic is found, invoke its FORMAT-SPECIFIC handler:
//        - parse the header to determine file size (header-driven
//          formats like BMP, WAV, ZIP)
//        - search for a footer signature within a reasonable window
//          (footer-terminated formats like JPEG, PNG, PDF, GIF)
//        - fallback to a fixed max size if neither works
//   4. Validate post-magic structure to minimize false positives.
//   5. Write the recovered bytes to <output>/carved/<format>/
//      <offset>_<id>.<ext>.
//
// Honest limits:
//   - Recovers FILE CONTENT only; no filenames, no directory structure
//     (the on-disk dirent/inode is gone -- carving doesn't change that).
//   - Fragmented files: only the FIRST contiguous run is recovered.
//     A defragmented disk yields nearly-100% recovery; a fragmented
//     one will recover partial files (the first chunk only).
//   - False positives: minimized via post-magic validation but not zero.
//     A 3-byte JPEG magic can statistically appear in random data.
//   - Encrypted or compressed-on-the-fly volumes (BitLocker, FileVault,
//     LUKS): NOT carved -- the bytes on disk are encrypted, magics
//     don't appear.
 
#pragma once
 
#include "models.hpp"
#include "filesystem_recovery.hpp"
#include "disk_reader.hpp"
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace carving {
 
struct CarvingOptions {
    // Limit the scan to the first N bytes of the disk. 0 means no limit
    // (= scan the whole disk). Defaults to 16 GiB to keep runtime
    // bounded on huge disks; the user can override.
    uint64_t max_bytes_to_scan {16ull * 1024 * 1024 * 1024};
 
    // Maximum file size we are willing to carve. Beyond this we cap the
    // output (= prefix of the file is saved). Most user document files
    // are well under 500 MB; carving larger probably means a false
    // positive runaway.
    uint64_t max_file_size {500ull * 1024 * 1024};
 
    // If set, skip carving formats whose magic is short (<=3 bytes) to
    // reduce false positives. Default: keep all (the per-format
    // validators do their own filtering).
    bool skip_short_magic {false};
};
 
// Run the carving pass on `reader`. Recovered files are appended to
// `recovered`; progress and warnings to `logs`.
//
// Returns true if any files were carved (false if zero results, but
// not an error condition).
bool run_carving(DiskReader& reader,
                 const std::string& output_dir,
                 const CarvingOptions& opts,
                 std::vector<RecoveredFileRecord>& recovered,
                 std::vector<std::string>& logs,
                 std::string& error);
 
} // namespace carving