Unified Forensic Intelligence

A high-performance forensic wrapper for Disk Mapping and Memory Reconstruction, fully guided by AI.

Setup Guide Connect on LinkedIn

01. Forensic Core

Resilient Disk Mapping (pytsk3)

Uses self-diagnosis to overcome corrupted headers and non-standard file systems (like forced FAT32 mounts), providing clean MACB timestamps and file metadata even when other tools fail.

AI Context Injection

The tool dynamically extracts the locally available Volatility 3 plugins and injects this valid list into the AI prompt, preventing the model from hallucinating deprecated or incorrect command names.

02. AI Key Configuration

For advanced AI-guided execution, you must create a config.json file in the root directory and populate it with your OpenRouter or DeepSeek keys.

{
  "API_KEYS": {
    "OPENROUTER": "sk-or-v1-...",
    "DEEPSEEK": "sk-deepseek-..."
  },
  "TOOL_SETTINGS": {
    "MAX_AI_FILE_SIZE_READ": 102400 // Optional limit on file content reading
  }
}

03. Volatility Integration

Pathing and Dependency

Unfold requires Volatility 3 to function in -vol mode. It looks for a folder named volatility3 containing vol.py in the same directory as the script for robust local execution.

Required Directory Structure: 
/Forensic-Tool-Folder/
├── unfold.py
└── volatility3/
    ├── vol.py
    └── ...

Setup command:

git clone https://github.com/volatilityfoundation/volatility3.git
The tool will automatically detect and correct the Python path for vol.py.

04. Usage & Command Center

Disk Mapping (Standard Report)

Generates the full file structure. Use --hash for proof of integrity.

python3 unfold.py drive.dd --json --hash -o report.json

AI Command Generation (Automated Extraction)

python3 unfold.py image.dd --extract DUMMY -ai openrouter -p "Extract the file located at /root/flag.gz" -o flag.gz

Critical Execution Flow

The AI automatically cleans the input, generates the command, and executes it in a seamless nested call.

# 1. Initial Call (AI finds path)
python3 unfold.py image.dd --extract DUMMY -ai openrouter -p "extract desktop"

# 2. Internal Execution (The script runs this command itself)
subprocess.run(
    "python3 unfold.py image.dd --extract /home/user/Desktop -o desktop.zip" 
)
// Note: The 'DUMMY' argument is dropped and replaced by the AI's determined path.

Credential Harvester

Use the --creds flag for specific hash extraction:

python3 unfold.py win_image.img --creds -o hashes.json

Outputs Linux hashes directly, or extracts Windows SAM/SYSTEM hives into a local folder for offline cracking.