Universal PE Deep Inspection & Automated Disassembly Toolchain

A high-performance, robust, and zero-hardcoding binary analysis pipeline designed for reverse engineering, malware analysis, packer research, and low-level firmware/driver triage.

This toolchain orchestrates pure Python structural parsing with headless Ghidra disassembly to generate complete, single-file raw forensic dumps (A-to-Z) for any PE32 / PE32+ executable, DLL, kernel driver, or UEFI binary.

flowchart TD
    A["Target Binary (.exe / .dll / .sys / .efi)"] --> B["run_full_dump.sh (Master Orchestrator)"]
    B --> C["SHA-256 Hashing & Project Cache Isolation"]
    C --> D["pe_raw_parser.py (PE Structural Inspector)"]
    D --> E["Dump Header: DOS, Rich Header, Data Directories, Relocations, Exports, Imports, Hexdump"]
    C --> F["Ghidra Headless Engine (analyzeHeadless)"]
    F --> G["ExportRawTotal.java (Deep Memory Disassembler)"]
    G --> H["Byte-for-Byte Disassembly & Data Hexdump with Symbols & Calling Conventions"]
    E --> I["Unified Master Raw Dump (.txt)"]
    H --> I

Loading

---

🌟 Key Architectural Features

1. Universal Zero-Hardcoding Engine

• Dynamic architecture resolution: Native support for Intel x86 (PE32), AMD64 / x64 (PE32+), ARM, ARM Thumb-2, ARM64 (AArch64), Intel Itanium (IA64), EFI Bytecode, MIPS, and SuperH.
• Dynamic Subsystem & Calling Convention Deduction: Auto-detects Entry Point prototypes and calling conventions for Native NT Drivers (DriverEntry), DLLs (_DllMainCRTStartup), Windows GUI (WinMainCRTStartup), Console CUI (mainCRTStartup), and UEFI applications (EfiMain).
• Zero path assumptions: All runner scripts and Ghidra headless hooks auto-resolve relative directories and runtime paths dynamically.

2. Deep PE Structural Inspection (pe_raw_parser.py)

• Zero External Dependencies: Built entirely on Python 3 standard libraries (struct, os, sys, json, argparse).
• Microsoft DanS / Rich Header Decryption: Auto-detects XOR keys, decrypts telemetry blocks, and maps compiler/linker build IDs to Visual Studio toolchain versions (VS2005, VS2008, VS2010, VS2012, VS2015, VS2019, VS2022). Includes safety guards for non-MSVC/stripped binaries.
• 16 Data Directories Exhaustive Parser:
  • Export Directory: Parses ordinal bases, named exports, and forwarded export symbols (DLL.Function).
  • Import Directory & IAT: Enforces 20-byte NULL boundary checks with full thunk table and Hint/Name parsing.
  • Base Relocation Directory (.reloc): Comprehensive block-walking engine decoding individual 16-bit fixup entries (IMAGE_REL_BASED_HIGHLOW, DIR64, ABSOLUTE), producing fixup statistics and sample virtual addresses.
  • Load Configuration Directory: Implements exact 32-bit (IMAGE_LOAD_CONFIG_DIRECTORY32) and 64-bit (IMAGE_LOAD_CONFIG_DIRECTORY64) layouts. Accurately extracts SecurityCookie, SafeSEH handler tables, Guard CF check pointers, Guard CF function tables, Guard CF function counts, and CFG flags (IMAGE_GUARD_CF_INSTRUMENTED).
  • Delay-Loaded Imports: Detects Attributes & 1 (dlattrRva) to support both legacy pre-VS2010 absolute VA pointers and modern RVA descriptors.
  • Thread Local Storage (TLS): Dumps raw data boundaries, index addresses, and walks the TLS callback function pointer array.
  • 3-Level Resource Tree (.rsrc): Recursively enumerates Type -> Name/ID -> Language leaves with cross-section pointer boundary validation to spot obfuscation.
  • Debug Directory: Parses CodeView RSDS (GUID + PDB path) and legacy NB10 debug information.
  • Exception Directory (.pdata): Walks 64-bit and ARM RUNTIME_FUNCTION unwind descriptors.
  • Dynamic Headers Hexdump: Automatically sizes the raw header hexdump based on SizeOfHeaders.

3. Fault-Tolerant Headless Disassembler (ExportRawTotal.java)

• Byte-for-Byte Disassembly: Dumps assembly instructions alongside their exact hexadecimal bytes, prototypes, calling conventions, and Ghidra auto-analysis comments.
• Anti-Hang & Corrupted Binary Protection: Enforces Math.max(1, instr.getLength()) to prevent infinite loops on malformed or obfuscated packing artifacts where instruction length may return zero.
• Isolated Memory Access Guards: Wraps instr.getBytes() in exception handlers, preventing section-level memory access faults from dropping subsequent sections.
• Synthetic Block Sanitization: Precisely filters internal emulator memory artifacts (tdb, pdb, gdt, KUSER_SHARED_DATA, EXTERNAL, OTHER, MEMORY[...], Reserved) while guaranteeing all authentic PE sections are exported.

4. Automated Pipeline Orchestration (run_full_dump.sh)

• SHA-256 Workspace Isolation: Calculates the target binary's SHA-256 hash to allocate isolated Ghidra headless project caches (PEProj_<hash>), eliminating stale project collisions during batch analysis.
• Multi-Source Ghidra Discovery: Automatically resolves analyzeHeadless across $GHIDRA_PATH, $GHIDRA_HOME, system $PATH, and standard installation paths (/home/$USER/ghidra*, /opt/ghidra*).

---

📁 Repository Structure

• run_full_dump.sh: Master Bash script orchestrating the entire parsing and disassembly pipeline.
• pe_raw_parser.py: Python PE32/PE32+ deep header, relocation, and directory inspection engine.
• ExportRawTotal.java: Ghidra headless analysis script for complete disassembly and data section hexdumps.

---

🚀 Quick Start & Usage

Prerequisites

• Linux / POSIX environment with Bash
• Python 3.8+
• Java Runtime Environment (JRE/JDK 17+)
• Ghidra 11.x or 12.x

Running the Full Master Pipeline

To run the complete analysis (PE structural dump + Ghidra disassembly) in a single command:

chmod +x run_full_dump.sh
./run_full_dump.sh /path/to/target_binary.dll /path/to/output_dump.txt

If the output path is omitted, the script automatically generates <target_binary>_RAW_AZ_DUMP.txt in the current working directory.

Running the Python PE Parser Standalone

The Python parser can be executed independently without requiring Ghidra:

python3 pe_raw_parser.py /path/to/target_binary.dll -o pe_structure_dump.txt

Optional JSON Symbol Annotation

You can provide custom symbol descriptions and annotations via a JSON mapping file:

python3 pe_raw_parser.py /path/to/target_binary.dll -o pe_structure_dump.txt -m annotations.json

Example annotations.json format:

{
  "0x00001000": {
    "symbol": "MyCustomExport",
    "signature": "int __stdcall MyCustomExport(void *ctx)",
    "convention": "__stdcall",
    "role": "Core Encryption Engine Dispatcher",
    "description": "Main entry for cryptographic session initialization."
  }
}

---

📋 Generated Dump Specification

The resulting master text dump is organized into structured, easily searchable sections:

1. PE Memory Map & Sections Breakdown: Lists all virtual address spaces, raw file offsets, sizes, and memory protection flags (Read, Write, Execute).
2. Microsoft Visual C++ Rich Header Metadata: Decrypted tool IDs, compiler build numbers, and mapped toolchain descriptions.
3. PE Data Directories Table: Complete 16-entry directory table with RVAs and resolved Virtual Addresses.
4. Specialized Directories Deep Inspection:
   • Load Config: SafeSEH handlers, Security Cookie VA, Guard CF flags & tables.
   • Base Relocations: Fixup type breakdown (HIGHLOW, DIR64, etc.) and page-by-page fixup target lists.
   • TLS Directory: Callbacks table and address ranges.
   • Resource Catalog: 3-level tree layout with cross-section anomaly detection.
   • Delay Imports & Exception Handlers.
5. PE Export Directory: Complete architectural breakdown of exports, forwarded targets, and CRT entry point metadata.
6. PE Import Directory & IAT: Modular breakdown of imported DLLs, function names, hints, and IAT addresses.
7. Raw DOS & PE Headers Hexdump: 16-byte aligned raw dump of header bytes with structural annotations.
8. Byte-for-Byte Disassembly & Data Sections:
   • .text: Disassembly with function prototypes, calling conventions, raw hex opcodes, and Ghidra analysis comments.
   • .rdata, .data, .rsrc, .reloc: Clean, formatted 16-byte hexdumps with ASCII decodings and symbol labels.

---

🤝 Contributing

Contributions from the community are warmly welcomed! Areas for active enhancement include:

• Expanding Rich Header toolchain databases for newer Clang-CL and Visual Studio preview builds.
• Adding specialized decoders for Authenticode PKCS#7 signatures in the Security Directory (data_dirs[4]).
• Adding support for .NET CLR metadata stream parsing (CLI metadata headers, tables, and string blobs).
• Providing headless scripts for alternative disassemblers (Radare2 / Cutter, IDA Pro).

Submitting Improvements

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/reloc-extended-heuristics).
3. Commit your changes (git commit -m "Enhance relocation block validation heuristics").
4. Push to the branch (git push origin feature/reloc-extended-heuristics).
5. Open a Pull Request.

---

📜 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.