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     # 或 /usr/local（需要 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>              # 识别：带有偏移、类型和置信度的发现树
moria <dir>               # 扫描目录树：类型摘要及值得注意的文件
moria -j <file>           # JSON，供工具和代理使用
moria -e <file>           # 提取到 <file>.extracted/   （-C DIR 选择输出目录）
moria -c <file>           # 将原始字节范围雕刻到 <file>.carved/（不解析）
moria -E <file>           # 熵分析：标记未识别/可能加密的区域
moria --list <archive>    # 列出 tar/cpio/zip 成员而不提取
moria --broad <path>      # 同时加载约 2.5k 个通用文件类型签名
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
• 归档与镜像： ZIP、tar、cpio、ISO 9660、Android sparse、Android boot
• 内核与封装： U-Boot uImage、U-Boot FIT、独立 gzip / xz / zstd / lz4 流
• 固件包： RAE Systems / Honeywell RFP（节表；对每个节进行 LZARI 解压缩）

签名

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

要添加格式，请在 signatures/ 中放入一个 .toml。仅当声明层无法表达检查（如 CRC 或跨块指针）时，才需要一个小型 C++ 验证器。

范围

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

许可证

MIT，参见 LICENSE。

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