moria

IoT 固件识别与提取

moria 可识别固件和 IoT 镜像中内嵌的文件与结构（文件系统、内核、引导加载程序、归档文件、密钥），并在无需 root 权限的情况下解包其发现的大部分内容。它会报告每项发现的字节偏移、类型和置信度评分，并输出干净的 JSON，使脚本和 LLM 代理能够像人类一样轻松驱动它。

为什么选择 moria

• 在进程内提取多种文件系统，无需 sudo： SquashFS、ext2/3/4、F2FS、XFS、btrfs、HFS+、NTFS、EROFS、JFFS2、UBIFS 等。
• 默认递归。 UBI 卷内由 gzip 包装的 SquashFS 会被一路解包到底。
• 标记加壳可执行文件。 通过经校验和验证的 PackHeader 尾部（格式、方法和大小）检测跨架构的 UPX 加壳 ELF/PE/Mach-O，并标记那些头部被清零或篡改以规避 upx -d 的存根。
• 确定性。 相同输入始终产生相同输出；冲突解决没有随机决胜。
• 对恶意输入安全。 每次读取都进行边界检查，每次写入都通过 openat + O_NOFOLLOW（无路径遍历或符号链接逃逸），解压缩针对压缩炸弹设有上限。
• 识别优先。 默认输出可读树状结构，面向工具时输出 JSON（-j），每项发现均附带偏移和置信度。

构建与安装

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

构建需要 cmake、C++20 编译器，以及 zlib、liblzma、lz4 和 zstd 开发库（即 --extract 使用的解压器）。在 Debian/Ubuntu 上：sudo apt install cmake g++ zlib1g-dev liblzma-dev liblz4-dev libzstd-dev。若要在缺少某个库的情况下构建（最小化构建或仅识别构建），请使用 -DMORIA_OPTIONAL_CODECS=ON 进行配置，缺失的编解码器将被直接禁用。

moria 二进制文件是自包含的：所有签名集都在构建时嵌入，因此该二进制文件可在任何地方运行，无需在其旁边安装任何东西（cp build/moria ~/.local/bin 即可，下载的发布版二进制文件也可直接运行）。若要改用外部签名而非嵌入的签名（例如在不重新构建的情况下测试新的 .toml），请传入 --sigs DIR 或设置 $MORIA_SIGDIR。

用法

默认输出为人类可读格式。传入 -j 可输出 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

提取

-e 会将识别出的格式解包到 <file>.extracted/ 下，每个区域一个目录（0x<offset>-<type>/），并生成一个将偏移映射到路径的 manifest.json。它会自动递归进入嵌套容器，并逐卷重建 UBI 镜像。防护机制（--depth、--max-files、--max-bytes 以及解压比上限）用于限制恶意输入；一旦触发防护，该分支会停止，但仍会返回所有已恢复的内容。

在进程内解包，无需外部工具，也无需 sudo：

• 文件系统： SquashFS、ext2/3/4、F2FS、FAT12/16/32、exFAT、NTFS、HFS+/HFSX、XFS、btrfs、JFFS2、UBI/UBIFS、romfs、YAFFS2、cramfs、EROFS、ReiserFS
• 归档与镜像： ZIP、tar、cpio、MS-CAB（stored/MSZIP/LZX）、CFBF 复合文件 / Windows Installer .msi、ISO 9660、Android sparse、Android boot
• 内核与封装： U-Boot uImage、U-Boot FIT、Windows CE XIP ROM（nk.bin / .cos）、独立 gzip / xz / zstd / lz4 流、Ingenic jzlzma（硬件 LZ77）
• 固件包： RAE Systems / Honeywell RFP（节表；对每个节进行 LZARI 解压）；Artosyn OTRA（AR8030 / VT4 / VR04；经 SHA-256 校验，对每个分区进行 LZO1X 解压，或在扁平镜像上暴露原始 flash 主体）
• 配置存储： U-Boot 环境、ESP32 NVS、Windows CE 注册表配置单元（.hv）

签名

• signatures/ 是手写的核心部分：固件文件系统、容器、内核和常见格式，每种都带有结构验证。
• signatures-firmware/ 存放厂商固件容器的魔数，默认加载。
• signatures-generated/ 存放约 2.5k 个通用文件类型魔数，源自 file(1) 的魔数数据库，仅在 --broad 时加载。

要添加一种格式，只需在 signatures/ 中放入一个 .toml 文件。只有当声明式层无法表达检查（例如 CRC 或跨块指针）时，才需要一个小型 C++ 验证器。字段语义（magic_offset、魔数字节序、短签名、软约束、验证器契约）记录在 SIGAUTHORING.md 中。

范围

moria 负责结构识别、提取和雕刻。密钥/凭据扫描、SBOM、CVE 和许可证分析属于另一个工具（mithril）。

许可证

MIT，参见 LICENSE。

部分磁盘格式处理是对其他开源项目中算法的干净重实现，基于 moria 自己的 I/O 层独立编写（未复制源代码）：来自 UPX/UCL 的 UCL/NRV2B 解压器和 CTO 反过滤器（GPL-2.0，仅算法），以及 littlefs 的元数据提交和 CTZ 跳表布局（BSD-3-Clause），以及 SPIFFS 的页/对象布局（MIT）。