moria

Identifikation und Extraktion von IoT-Firmware

moria identifiziert Dateien und die in Firmware und IoT-Images eingebetteten Strukturen (Dateisysteme, Kernel, Bootloader, Archive, Schlüssel) und entpackt das meiste, was es findet, ohne Root-Rechte. Es meldet jeden Fund mit einem Byte-Offset, einem Typ und einem Konfidenzwert und gibt sauberes JSON aus, sodass Skripte und LLM-Agenten es genauso einfach steuern können wie Menschen.

Warum moria

• Extrahiert eine breite Palette von Dateisystemen im Prozess, ohne sudo: SquashFS, ext2/3/4, F2FS, XFS, btrfs, HFS+, NTFS, EROFS, JFFS2, UBIFS und mehr.
• Standardmäßig rekursiv. Ein gzip-verpacktes SquashFS in einem UBI-Volume wird bis ganz nach unten entpackt.
• Erkennt gepackte ausführbare Dateien. Erkennt UPX-gepackte ELF/PE/Mach-O über alle Architekturen hinweg anhand des checksummenverifizierten PackHeader-Trailers (Format, Methode und Größen) und markiert Stubs, deren Header genullt oder verändert wurde, um upx -d zu vereiteln.
• Deterministisch. Dieselbe Eingabe erzeugt stets dieselbe Ausgabe; die Konfliktlösung hat keinen zufälligen Tie-Break.
• Sicher bei feindseliger Eingabe. Jeder Lesezugriff ist grenzgeprüft, jeder Schreibzugriff läuft über openat + O_NOFOLLOW (kein Path-Traversal oder Symlink-Escape), und die Dekompression ist gegen Bomben begrenzt.
• Identifikation zuerst. Standardmäßig ein lesbarer Baum, JSON (-j) für Tools, mit Offsets und Konfidenz bei jedem Fund.

Build & Install

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cmake --install build --prefix ~/.local     # or /usr/local (needs sudo)

Zum Bauen werden cmake, ein C++20-Compiler sowie die Entwicklungsbibliotheken zlib, liblzma, lz4 und zstd benötigt (die von --extract verwendeten Dekompressoren). Unter Debian/Ubuntu: sudo apt install cmake g++ zlib1g-dev liblzma-dev liblz4-dev libzstd-dev. Um ohne einen davon zu bauen (ein minimaler oder reiner Identifizierungs-Build), konfigurieren Sie mit -DMORIA_OPTIONAL_CODECS=ON, und der fehlende Codec wird einfach deaktiviert.

Das moria-Binary ist eigenständig: Alle Signatursätze sind zur Build-Zeit eingebettet, sodass das Binary überall funktioniert, ohne dass etwas daneben installiert sein muss (cp build/moria ~/.local/bin genügt, und ein heruntergeladenes Release-Binary läuft einfach). Um statt der eingebetteten externe Signaturen zu verwenden (etwa um eine neue .toml ohne Neubau zu testen), übergeben Sie --sigs DIR oder setzen Sie $MORIA_SIGDIR.

Verwendung

Die Ausgabe ist standardmäßig menschenlesbar. Übergeben Sie -j für JSON.

moria <file>               # identify: a findings tree with offsets, types, and confidence
moria <dir>                # scan a tree: a type summary plus the notable files
moria -j <file>            # JSON, for tools and agents
moria -e <file>            # extract to <file>.extracted/   (-C DIR to choose the output dir)
moria -c <file>            # carve raw byte ranges to <file>.carved/ (no parsing)
moria -E <file>            # entropy pass: flag unidentified / possibly-encrypted regions
moria --list <archive>     # list tar/cpio/zip/cab/CE-ROM members without extracting
moria --broad <path>       # also load the ~2.5k general file-type signatures
moria --unpack-executables # unpack executables inside other extracted output (cfbf/msi files)
moria --help

Extraktion

-e entpackt erkannte Formate unter <file>.extracted/, ein Verzeichnis pro Region (0x<offset>-<type>/), plus eine manifest.json, die Offsets auf Pfade abbildet. Es rekursiert automatisch in verschachtelte Container und baut UBI-Images Volume für Volume neu auf. Schutzmechanismen (--depth, --max-files, --max-bytes und eine Obergrenze für das Dekompressionsverhältnis) begrenzen feindliche Eingaben; ein ausgelöster Schutzmechanismus stoppt diesen Zweig und liefert dennoch alles Wiederhergestellte zurück.

Im Prozess entpackt, ohne externe Tools und ohne sudo:

• Dateisysteme: SquashFS, ext2/3/4, F2FS, FAT12/16/32, exFAT, NTFS, HFS+/HFSX, XFS, btrfs, JFFS2, UBI/UBIFS, romfs, YAFFS2, cramfs, EROFS, ReiserFS
• Archive und Images: ZIP, tar, cpio, MS-CAB (stored/MSZIP/LZX), CFBF-Compound-Dateien / Windows Installer .msi, ISO 9660, Android sparse, Android boot
• Kernel und Wrapper: U-Boot uImage, U-Boot FIT, Windows CE XIP ROM (nk.bin / .cos), eigenständige gzip- / xz- / zstd- / lz4-Streams, Ingenic jzlzma (Hardware-LZ77)
• Firmware-Pakete: RAE Systems / Honeywell RFP (Abschnittstabelle; LZARI-dekomprimiert jeden Abschnitt); Artosyn OTRA (AR8030 / VT4 / VR04; SHA-256-verifiziert, LZO1X-dekomprimiert jede Partition oder legt bei Flat-Images den rohen Flash-Inhalt offen)
• Konfigurationsspeicher: U-Boot-Umgebung, ESP32 NVS, Windows CE-Registry-Hives (.hv)

Signaturen

• signatures/ ist der handgeschriebene Kern: Firmware-Dateisysteme, Container, Kernel und gängige Formate, jeweils mit struktureller Validierung.
• signatures-firmware/ enthält die Magics von Hersteller-Firmware-Containern und wird standardmäßig geladen.
• signatures-generated/ enthält ~2,5k allgemeine Dateityp-Magics, abgeleitet aus der Magic-Datenbank von file(1), und wird nur mit --broad geladen.

Um ein Format hinzuzufügen, lege eine .toml in signatures/ ab. Ein kleiner C++-Validator ist nur für Prüfungen nötig, die die deklarative Ebene nicht ausdrücken kann, etwa CRCs oder blockübergreifende Zeiger. Die Feldsemantik (magic_offset, Magic-Endianness, kurze Signaturen, weiche Constraints, der Validator-Vertrag) ist in SIGAUTHORING.md dokumentiert.

Umfang

moria führt strukturelle Identifikation, Extraktion und Carving durch. Secret-/Credential-Scanning, SBOM-, CVE- und Lizenzanalyse sind ein separates Tool (mithril).

Lizenz

MIT, siehe LICENSE.

Einige Teile der Behandlung von On-Disk-Formaten sind eine saubere Neuimplementierung der Algorithmen anderer Open-Source-Projekte, unabhängig gegen morias eigene I/O-Schicht geschrieben (kein Quellcode kopiert): der UCL/NRV2B-Dekompressor und die CTO-Unfilter aus UPX/UCL (GPL-2.0, nur Algorithmen), und das Metadata-Commit- und CTZ-Skip-List-Layout von littlefs (BSD-3-Clause), und das Page-/Object-Layout von SPIFFS (MIT).