mft_parser.py

"""
mft_parser.py — NTFS $MFT Parser
Project Helix CTF · TCM Security
Author: Dibyanshu Sekhar

Walks all FILE records in $MFT, applies USA fixup, and extracts:
  - Filename attributes (0x30) to identify files by name
  - Data attributes (0x80) to recover Zone.Identifier ADS content

Usage:
    python mft_parser.py --mft /path/to/$MFT --target freq.txt
"""

import struct
import argparse


def apply_usa_fixup(record: bytearray) -> bytearray:
    """Apply the Update Sequence Array fixup to an MFT record."""
    usa_off = struct.unpack_from('<H', record, 4)[0]
    usa_cnt = struct.unpack_from('<H', record, 6)[0]
    usa_val = bytes(record[usa_off:usa_off + 2])

    for i in range(1, usa_cnt):
        fix = bytes(record[usa_off + i * 2: usa_off + i * 2 + 2])
        pos = i * 512 - 2
        if pos + 2 <= len(record) and record[pos:pos + 2] == bytearray(usa_val):
            record[pos:pos + 2] = fix

    return record


def extract_filename(record: bytearray, attr_off: int, attr_len: int) -> str | None:
    """Extract filename from a $FILE_NAME (0x30) attribute."""
    try:
        content_off = struct.unpack_from('<H', record, attr_off + 20)[0]
        name_len = record[attr_off + content_off + 64]
        name_start = attr_off + content_off + 66
        name_bytes = record[name_start: name_start + name_len * 2]
        return name_bytes.decode('utf-16-le', errors='replace')
    except Exception:
        return None


def extract_data_ads(record: bytearray, attr_off: int, attr_len: int) -> str | None:
    """
    Extract content from a resident $DATA (0x80) attribute.
    Returns the content as a string if it looks like Zone.Identifier text.
    """
    try:
        non_resident = record[attr_off + 8]
        if non_resident:
            return None  # Skip non-resident data (clusters wiped on deletion)

        content_off = struct.unpack_from('<H', record, attr_off + 20)[0]
        content_len = struct.unpack_from('<I', record, attr_off + 16)[0]
        content = record[attr_off + content_off: attr_off + content_off + content_len]
        text = content.decode('utf-8', errors='replace')

        if 'ZoneTransfer' in text or 'HostUrl' in text:
            return text.strip()
    except Exception:
        pass
    return None


def parse_mft(mft_path: str, target_name: str):
    """Walk all FILE records in $MFT, find target file, dump Zone.Identifier."""
    record_size = 1024
    results = []

    print(f"[*] Parsing $MFT: {mft_path}")
    print(f"[*] Looking for: {target_name}\n")

    with open(mft_path, 'rb') as f:
        data = f.read()

    total_records = len(data) // record_size
    print(f"[*] Total records to scan: {total_records:,}")

    for record_num in range(total_records):
        offset = record_num * record_size
        raw = bytearray(data[offset: offset + record_size])

        if raw[:4] != b'FILE':
            continue

        record = apply_usa_fixup(raw)

        # Check flags: bit 0 = in-use, bit 1 = directory
        flags = struct.unpack_from('<H', record, 22)[0]
        is_deleted = not (flags & 0x01)

        attr_pos = struct.unpack_from('<H', record, 20)[0]
        filename = None
        zone_content = None

        while attr_pos < len(record) - 8:
            attr_type = struct.unpack_from('<I', record, attr_pos)[0]
            if attr_type == 0xFFFFFFFF:
                break
            attr_len = struct.unpack_from('<I', record, attr_pos + 4)[0]
            if attr_len == 0:
                break

            if attr_type == 0x30:  # $FILE_NAME
                name = extract_filename(record, attr_pos, attr_len)
                if name:
                    filename = name

            if attr_type == 0x80:  # $DATA
                zone = extract_data_ads(record, attr_pos, attr_len)
                if zone:
                    zone_content = zone

            attr_pos += attr_len

        if filename and target_name.lower() in filename.lower():
            status = "[DELETED]" if is_deleted else "[ACTIVE]"
            print(f"[+] Record {record_num}: {filename} {status}")
            if zone_content:
                print(f"[+] Zone.Identifier ADS found:")
                print("-" * 40)
                print(zone_content)
                print("-" * 40)
            results.append({
                'record': record_num,
                'name': filename,
                'deleted': is_deleted,
                'zone': zone_content,
            })

    if not results:
        print(f"[-] No records found for '{target_name}'")
    else:
        print(f"\n[*] Done. Found {len(results)} matching record(s).")

    return results


if __name__ == '__main__':
    parser = argparse.ArgumentParser(description='NTFS $MFT Parser — Project Helix')
    parser.add_argument('--mft', required=True, help='Path to $MFT file')
    parser.add_argument('--target', default='freq.txt', help='Filename to search for')
    args = parser.parse_args()

    parse_mft(args.mft, args.target)