AEGIS File Recovery Tool

Araw EXT4 file recovery utility written in pure C — no external libraries, no filesystem APIs.

When Linux deletes a file on an EXT4 partition, it frees the inode, but the physical data blocks often survive untouched on the disk. This tool interacts directly with the raw block device to bypass the operating system and resurrect those files using a Dual-Engine Architecture.

Dual-Engine Architecture

AEGIS employs two distinct, specialized recovery engines to maximize precision:

1. Inode Extent Engine (Pass 1) — Walks the EXT4 inode table directly from the raw block device. It looks for deleted inodes whose extent trees still survive. By parsing the ext4_extent_header and leaf records, it maps the exact logical-to-physical block runs and retrieves the precise file size. This is the only way to recover fragmented files or files with no magic bytes (like Text, Source Code, CSVs, and JSONs).
2. Bounded Carving Engine (Pass 2) — Acts as a fallback for binary files. If journal cleanup wiped the inode extent tree, AEGIS scans the raw disk sectors for file format magic signatures (like %PDF or PK\x03\x04). It implements format-specific parsers to detect the internal structure and bound the file exactly at its end-of-file marker (e.g., %%EOF for PDFs or the EOCD record for ZIP/PyTorch).

Every recovered file is strictly tagged with its origin (INODE or CARVE) in the generated manifest so you know exactly how the data was reconstructed.

---

Supported Formats

AEGIS supports targeted recognition and recovery of 13 distinct file formats across its two engines:

Type	Engine	Detection Mechanism	Bounded End Marker
PDF	Both	%PDF magic signature	%%EOF
JPEG	Both	FF D8 FF magic signature	FF D9
PNG	Both	89 50 4E 47 magic signature	IEND chunk + CRC
ZIP	Both	PK\x03\x04 + precise header validation	End of Central Directory (EOCD)
ODT	Both	ZIP validation with mimetype root entry	EOCD
PTH	Both	ZIP validation with archive/data.pkl	EOCD
HDF5	Both	89 48 44 46 magic signature	Superblock EOF calculation
SVG	Inode Only	<svg text signature	Inode exact size
JSON	Inode Only	{ / [ structural text	Inode exact size
Python	Inode Only	import / def / class keywords	Inode exact size
C code	Inode Only	#include keyword	Inode exact size
CSV	Inode Only	Heuristic (≥2 commas on first line)	Inode exact size
LOG	Inode Only	Leading timestamp heuristics	Inode exact size

(Note: Text-based formats have no reliable binary markers or EOF signatures, which is why the Inode Engine is strictly required to recover them.)

---

Build Instructions

Building the tool is extremely lightweight.

git clone https://github.com/karnayanarohith/Aegis_File_Recovery_Tool.git
cd Aegis_File_Recovery_Tool
make

Requirements: A standard Linux environment with gcc and make. There are absolutely no dependencies on external parsing libraries or filesystem utilities.

---

Step-by-Step Usage Guide

AEGIS operates in a strict, secure pipeline: Scan → Preview → Recover → Verify.

(All commands require sudo privileges to open and read raw block devices like /dev/nvme0n1pX or /dev/sdaX)

Step 1: Scan the Partition

First, map the disk and index all recoverable files. AEGIS will generate an internal index of surviving inodes and carved blocks.

sudo ./aegis-recover --scan /dev/nvme0n1p8

Output snippet:

[AEGIS] === Superblock Info ===
  Magic:              0xef53 (valid EXT4)
  Block size:         4096 bytes
...
[AEGIS] Pass 1/2 — inode table (extent-tree recovery)...
[AEGIS]   inode pass: 12 files with surviving extents
[AEGIS] Pass 2/2 — raw-block carving (fallback)...
[AEGIS]   carve pass 1 — 100%...
[AEGIS]   carve pass: 5 additional files

[AEGIS] Found 17 files. Index saved to recovered/index.txt

Step 2: Preview Metadata

Before writing anything to disk, you can preview the raw text content or format metadata of any found file ID.

sudo ./aegis-recover --preview /dev/nvme0n1p8 1

Step 3: Targeted File Recovery

You can recover a specific file by its ID, or extract all files of a specific type (e.g., extracting all PyTorch models or PDFs without touching anything else).

Recover a single file by ID:

sudo ./aegis-recover --recover /dev/nvme0n1p8 1

Recover all files of a specific type:

sudo ./aegis-recover --recover-type /dev/nvme0n1p8 PDF

Output snippet:

[AEGIS] Recovering 5 PDF file(s)...
  [001] PDF        678911 bytes  recovered/file_001_PDF.pdf
  [002] PDF        134217 bytes  recovered/file_002_PDF.pdf
[AEGIS] 5/5 PDF files recovered.

Step 4: Full Disk Recovery

To resurrect everything found in the index during the scan phase:

sudo ./aegis-recover --recover-all /dev/nvme0n1p8

This reconstructed files are saved safely to the local ./recovered/ directory along with a manifest.txt detailing exactly how and where each file was reconstructed.

Step 5: Cryptographic Verification

If you captured a ground truth manifest before simulating a deletion (useful for forensics or testing), AEGIS can verify the integrity of the recovered bytes using built-in SHA-256 validation.

./aegis-recover --verify

---

Technical Notes

• Extents vs Block Pointers: Modern EXT4 file systems use extent trees (flag EXT4_EXTENTS_FL = 0x80000), abandoning legacy direct-block arrays. The AEGIS parser fully implements the reading of ext4_extent_header and ext4_extent leaf records to resolve logical runs to physical blocks.
• PyTorch .pth Validation: A .pth file is structurally a ZIP archive. AEGIS avoids misidentifying it by actively peaking into the ZIP's central directory and asserting that the first entry matches the archive/data.pkl layout required by torch.save().
• ZIP Header Strictness: The carver rejects generic internal PK\x03\x04 headers by enforcing strict version limits (≤ 63), compression methods (0, 8, 14), and validating the printability of the filename buffer to avoid false positives midway through massive archives.
• Raw Disk Operations Only: No dependency on the operating system's EXT4 inode bitmap or journal structures. This prevents kernel lockups and allows the tool to run on unmounted, damaged, or otherwise compromised partitions.

---

Built by

Rohith — ECE Student, Andhra University College of Engineering. Developed as part of the AEGIS local AI security platform research project.