Added ESP Unpacker

.gitignore

@@ -1,6 +1,8 @@
 __pycache__/
 venv/
+.venv*/
 .idea/
+.vscode/
 test/
 .DS_Store
 *.iml
@@ -21,4 +23,5 @@ build/
 dist/
 .coverage*
 **/license.json
+*.license
 assets/*_ghidra

ofrak_core/CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased](https://github.com/redballoonsecurity/ofrak/tree/master)
 
 ### Added
+- Add ESP32/ESP8266 firmware support: app image identifier, unpacker, analyzer, header modifier, and packer, plus a flash-dump unpacker and partition analyzer. ([#412](https://github.com/redballoonsecurity/ofrak/pull/412))
 - Add DockerImage components (identifier and unpacker) ([#715](https://github.com/redballoonsecurity/ofrak/pull/715))
 - Add `FlashGeometryHeuristicAnalyzer` that infers `FlashAttributes` (page/OOB geometry) for raw NAND dumps tagged as `FlashResource`, using YAFFS2, Linux MTD large-page OOB, small-page OOB density, and exact Hamming ECC verification as signals ([#737](https://github.com/redballoonsecurity/ofrak/pull/737))
 - Add `FlashFieldType.SPARE` and `FlashSpareAreaResource` so `FlashOobResourceUnpacker` can preserve OOB bytes without ECC/Checksum computation, and extend `FlashLogicalDataResourcePacker` to consume the sibling `FlashSpareAreaResource` so the original OOB layout is reconstructed verbatim during repacking ([#738](https://github.com/redballoonsecurity/ofrak/pull/738))

ofrak_core/requirements-test.txt

@@ -1,2 +1,5 @@
+# esptool is only used by the ESP app tests to independently validate repacked images
+# (`python -m esptool image_info`); the ESP components themselves have no esptool dependency.
+esptool==4.8.1
 filelock==3.19.1
 pyelftools==0.29

ofrak_core/src/ofrak/core/esp/__init__.py

@@ -0,0 +1,125 @@
+"""
+ESP (Espressif) device support for OFRAK.
+
+This module provides unpackers, modifiers, and packers for ESP flash dumps and app images,
+supporting ESP8266, ESP32, ESP32-S2, ESP32-S3, and other Espressif devices.
+"""
+
+# App components
+from .app import (
+    ESPAppIdentifier,
+    ESPAppUnpacker,
+    ESPAppAnalyzer,
+    ESPAppHeaderModifier,
+    ESPAppPacker,
+)
+
+# App models
+from .app_model import (
+    ESPApp,
+    ESPAppSection,
+    ESPAppAttributes,
+    ESPAppHeaderModifierConfig,
+    ESP_APP_MAGIC,
+    ESP8266V2_APP_MAGIC,
+    ESP_APP_HEADER_SIZE,
+    ESP_APP_EXTENDED_HEADER_SIZE,
+    ESP_APP_SEGMENT_HEADER_SIZE,
+    ESP_APP_DESCRIPTION_MAGIC_WORD,
+    ESP_APP_CHECKSUM_MAGIC,
+    ESPChip,
+    ESPAppFlashMode,
+    FlashSizeESP8266,
+    FlashSizeESP32,
+    FlashSizeESP32S2S3,
+    FlashFrequencyESP8266,
+    FlashFrequencyESP32,
+    FlashFrequencyESP32C6,
+    FlashSize,
+    FlashFrequency,
+)
+
+# Flash components
+from .flash import (
+    ESPFlashIdentifier,
+    ESPFlashUnpacker,
+    ESPFlashAnalyzer,
+    ESPPartitionTableEntryModifier,
+    ESPPartitionTableEntryModifierConfig,
+)
+
+# Flash models
+from .flash_model import (
+    ESPFlash,
+    ESPFlashAttributes,
+    ESPPartitionTable,
+    ESPPartition,
+    ESPPartitionTableEntry,
+    ESPFlashSection,
+    ESPFlashSectionStructure,
+    ESPPartitionStructure,
+    ESPPartitionType,
+    ESPPartitionSubtype,
+    ESPPartitionFlag,
+    ESP_PARTITION_ENTRY_MAGIC,
+    ESP_PARTITION_TABLE_OFFSET,
+    ESP_PARTITION_TABLE_SIZE,
+    ESP_PARTITION_ENTRY_SIZE,
+    ESP_BOOTLOADER_OFFSET,
+    ESP_BOOTLOADER_MAGIC,
+)
+
+__all__ = [
+    # App components
+    "ESPApp",
+    "ESPAppIdentifier",
+    "ESPAppUnpacker",
+    "ESPAppAnalyzer",
+    "ESPAppHeaderModifier",
+    "ESPAppPacker",
+    # App models
+    "ESPAppSection",
+    "ESPAppAttributes",
+    "ESPAppHeaderModifierConfig",
+    "ESP_APP_MAGIC",
+    "ESP8266V2_APP_MAGIC",
+    "ESP_APP_HEADER_SIZE",
+    "ESP_APP_EXTENDED_HEADER_SIZE",
+    "ESP_APP_SEGMENT_HEADER_SIZE",
+    "ESP_APP_DESCRIPTION_MAGIC_WORD",
+    "ESP_APP_CHECKSUM_MAGIC",
+    "ESPChip",
+    "ESPAppFlashMode",
+    "FlashSizeESP8266",
+    "FlashSizeESP32",
+    "FlashSizeESP32S2S3",
+    "FlashFrequencyESP8266",
+    "FlashFrequencyESP32",
+    "FlashFrequencyESP32C6",
+    "FlashSize",
+    "FlashFrequency",
+    # Flash components
+    "ESPFlash",
+    "ESPFlashIdentifier",
+    "ESPFlashUnpacker",
+    "ESPFlashAnalyzer",
+    "ESPPartitionTableEntryModifier",
+    # Flash models
+    "ESPPartitionTable",
+    "ESPPartition",
+    "ESPPartitionTableEntry",
+    "ESPFlashSection",
+    "ESPFlashSectionStructure",
+    "ESPPartitionStructure",
+    "ESPFlashAttributes",
+    "ESPPartitionTableEntryModifierConfig",
+    "ESPPartitionType",
+    "ESPPartitionSubtype",
+    "ESPPartitionFlag",
+    "ESP_PARTITION_ENTRY_MAGIC",
+    "ESP_PARTITION_TABLE_OFFSET",
+    "ESP_PARTITION_TABLE_SIZE",
+    "ESP_PARTITION_ENTRY_SIZE",
+    "ESP_BOOTLOADER_OFFSET",
+    "ESP_BOOTLOADER_MAGIC",
+]