ESP32 Universal Firmware Extractor

🚀 One-Click ESP32 Firmware Extraction & Analysis Tool

A streamlined, user-friendly tool for extracting and analyzing ESP32 firmware - whether from a physical device or an existing firmware dump.

Features

• 🚀 Auto-Detection: Automatically detects ESP32 device, port, and flash size
• ⚡ Quick Mode: One-command extraction with --auto flag
• 🔌 Direct Device Extraction: Download firmware directly from ESP32 via serial port
• 📁 File-Based Extraction: Analyze existing firmware dumps
• 🔍 Automatic Partition Detection: Identifies and extracts all partitions
• 🛠️ ELF Generation: Creates analyzable ELF files from app partitions
• 📊 Comprehensive Analysis: Generates detailed reports using esptool
• 🎨 User-Friendly Interface: Interactive menu with colored output
• 📦 Organized Output: Creates timestamped directories with all results

Quick Start

Prerequisites

# Install Python dependencies
pip install esptool makeelf

Usage

Fastest - One Command (NEW!)

# Just connect ESP32 and run:
./quick_extract.sh

No questions asked - automatically detects, downloads, and extracts everything!

Auto Mode

# Auto-detect ESP32 and download firmware with options
./extract.sh --auto

Interactive Mode

# Run with menu options
./extract.sh

Command Line Mode

# Process existing firmware file
./extract.sh --file flash.bin

# Show help
./extract.sh --help

Workflow

1. Choose Source:

   • Download from ESP32 device (via serial)
   • Use existing firmware file

2. Automatic Processing:

   • Reads partition table
   • Extracts all partitions (nvs, ota, factory, etc.)
   • Creates ELF files for reverse engineering
   • Generates analysis report

3. Output:

   • Organized directory with timestamp
   • All extracted partitions
   • ELF executables for IDA/Ghidra/radare2
   • Detailed analysis report
   • README with next steps

Output Structure

extraction_YYYYMMDD_HHMMSS/
├── flash_dump.bin          # Original firmware
├── partition_table.txt     # Partition layout
├── nvs.bin                 # NVS partition
├── otadata.bin             # OTA data
├── ota_0.bin              # Application partition 0
├── ota_0.elf              # ELF for analysis
├── factory.bin            # Factory app
├── factory.elf            # Factory ELF
├── analysis_report.txt    # Detailed analysis
└── README.md              # Next steps guide

Supported Partitions

• nvs: Non-Volatile Storage (WiFi creds, configs)
• otadata: OTA update data
• phy_init: PHY initialization
• ota_0/ota_1: Application partitions
• factory: Factory application
• storage: User storage

Analysis Tools

For ELF Files

• IDA Pro: Industry-standard disassembler
• Ghidra: Free reverse engineering suite
• radare2: Open-source RE framework
• objdump: Basic disassembly

For Binary Files

• hexdump/xxd: Command-line hex viewers
• HxD: Windows hex editor
• Hex Fiend: macOS hex editor

Device Connection

Linux

# USB serial typically appears as:
/dev/ttyUSB0
/dev/ttyACM0

macOS

# USB serial typically appears as:
/dev/tty.usbserial-XXXX
/dev/tty.usbmodem-XXXX

Windows

COM3, COM4, etc.

Common Flash Sizes

• 2MB: Minimal ESP32 modules
• 4MB: Most common (ESP32-WROOM-32)
• 8MB: ESP32-WROVER modules
• 16MB: High-capacity modules

Troubleshooting

Permission Denied on Serial Port

# Linux: Add user to dialout group
sudo usermod -a -G dialout $USER
# Then logout and login again

esptool Not Found

pip install esptool

Timeout During Download

• Try reducing baud rate (default: 921600)
• Check cable quality
• Ensure proper grounding

Security Notes

⚠️ Legal Use Only: Only extract firmware from devices you own or have permission to analyze.

License

Based on ESP32 Image Parser tools. See LICENSE file for details.