Magic Extractor

描述

Magic Extractor 是一款面向 Windows 的通用提取工具，它会通过多种检测器识别文件，并将其路由到正确的内置解压程序。它旨在覆盖主流压缩格式、如今常见的安装程序，以及一系列不太常见的归档工具。

它可自动检测 80 多种格式 —— 包括归档文件、安装程序、磁盘映像、取证映像 (EWF/AFF/AD1)、光盘映像、邮件存储和现代编解码器。完整列表请参阅 formats.md。

快速开始

下载最新版本，解压后运行：

magic-extractor.exe extract mystery.bin

identify、list、carve、--recursive 和 --bruteforce 的用法请参阅示例。

项目结构

cli：源代码。
- bin：内置的检测器和解压程序二进制文件。
  - detectors：DIE、Magika、binwalk（TrID 的定义被转换为 data/signatures.json）。
  - extractors：7z、unrar、unace、unshield、lessmsi、dark (WiX) 等。
- data：运行时配置，动态加载（见下文）。
- formats：每个格式家族对应一个处理模块。
gui：可选的 tkinter 前端，封装了 CLI（见图形界面）。
test：每种格式的示例文件（用于提取/检测测试的样例）。
tools：开发者工具（generate_data.py —— 从处理模块构建数据文件）。

编译后的构建将 bin/、data/ 和 config.ini 放在 exe 外部，以便通过替换文件即可更新它们；main.py 中的路径解析器会在可执行文件旁边（冻结模式）或 cli/ 目录下（开发模式）找到这些文件。

检测原理

对于常规提取，检测器按以下顺序运行并使用提前退出机制 —— 第一个给出已知处理模块的检测器胜出（最便宜的优先，因此机器学习模型通常会被跳过）：

puremagic —— 纯 Python 实现，无子进程；对格式良好的归档文件进行廉价的 MIME 检查。
内置签名 —— data/signatures.json 中的魔法字节模式；可识别引擎遗漏的归档工具（bcm、dgca、kgb、uharc、alzip、freearc……），且无需外部进程。
DIE (Detect It Easy) —— 签名引擎；擅长处理安装程序、PE 和 SFX。
binwalk —— 简短的类型键（cpio、lzma……）以及嵌入内容。
Magika —— 谷歌的 AI 内容类型检测器，作为兜底方案。

每个检测器都有其独特贡献（它们是互补的，而非冗余）：签名数据库识别引擎遗漏的归档工具，DIE 处理安装程序/PE，binwalk 捕捉其他检测器遗漏的少数类型， puremagic/Magika 负责 MIME。

PureMagic 2.x 在接收完整文件时还提供内容感知的深度扫描。默认进行全文件分析；可选的 --fast-check 修饰符在启动速度比深度检查更重要时仅传入前 64 KiB。

每个处理模块通过 detection_mimes() / detection_names() / detection_signatures() 声明自己的检测指标；tools/generate_data.py 将这些编译为 data/handlers.json 和 data/signatures.json（可选地叠加 data/extra_detections.json）。TrID 未被使用。

注意：任何其签名在 puremagic 的 magic_data.json 中缺失（或 puremagic 仅将其报告为通用的 application/octet-stream）的格式，必须在其处理模块中声明自定义的 detection_signatures() 条目 —— 否则将无法通过内容进行检测。

--bruteforce 禁用提前退出：每个检测器都会运行，并且依次尝试每个被检测到的处理模块（当第一个猜测错误时很有用）。
未被任何检测器识别的可执行文件会回退到封装式 exe 安装程序处理模块（BitRock、Clickteam、Inno……），这些模块会进行自我验证。
carve 子命令额外使用 binwalk 的偏移映射来提取嵌入在任意偏移处的归档文件（例如固件映像内部）。

检测 → 处理模块的路由映射位于 data/handlers.json（手工整理，运行时加载）；通用令牌黑名单位于 data/detection_blacklist.json。

支持的格式

完整格式及其处理模块列表请参阅 formats.md。

添加一种格式

要添加对新格式的支持，请参阅 docs/adding-a-handler.md —— 这本端到端指南涵盖了（处理模块类、检测声明、DIE/TrID 查询、魔法签名、重新生成路由数据、捆绑工具以及测试）。

安装（从源码）

大多数用户只需下载发布版（见快速开始）。要从源码运行：需要 Python 3.12 或更高版本。

git clone <repo-url>
cd magic-extractor
pip install -r cli/requirements.txt

用法

Magic Extractor 使用子命令：

python cli/main.py extract  <path> [output_dir] [options]   # 检测并提取
python cli/main.py identify <path>                          # 报告类型 + 候选处理模块
python cli/main.py list     <path>                          # 列出归档内容
python cli/main.py carve    <path> [output_dir] [options]   # 提取嵌入的归档（binwalk 偏移）

不带子命令的裸路径默认为 extract（向后兼容）：

python cli/main.py <path> <output_dir> [options]

extract 选项：

--password <password>：加密归档的密码。
-r、--recursive：提取输出目录中找到的归档（受 --max-depth 限制，默认 5）。
-b、--bruteforce：尝试所有检测到的处理模块，而不是在第一个处停止。
--open-output-folder <true|false>：完成后打开输出文件夹。
--check-free-space <true|false>：如果输出卷可能空间不足则发出警告。
--check-unicode <true|false>：警告非 ASCII 的提取文件名。
--fix-file-extensions <true|false>：为无扩展名的提取文件添加基于内容的扩展名（绝不覆盖已有扩展名）。
--create-log-files <true|false>：将每次运行的日志写入输出目录。

（省略时每个选项均默认为 config.ini 中的值；可结合 --update-defaults 持久化给定的值 —— 例如 --open-output-folder false --update-defaults 会关闭先前保存的默认设置。）
--fast-check：仅检查前 64 KiB，而不运行全文件检测。
--update-defaults：将给定设置持久化为 config.ini 中的默认值。

carve 选项：--list（打印 binwalk 片段表）、--fragment N（按索引提取一个片段）、--raw（提取所有片段，而不仅是处理模块已知的片段）。

在下面的示例中，magic-extractor 是编译后的 .exe。从源码运行时，将其替换为 python cli/main.py —— 参数完全相同。

示例

提取归档文件 —— 你无需知道其类型；它会自动检测：

magic-extractor extract mystery.bin
# 提取到文件旁边的 mystery_extracted/ 目录

识别一个文件而不触碰它 —— 显示每个检测器看到了什么以及将运行哪个处理模块：

magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler

列出归档内容（不提取）：

magic-extractor list backup.7z

递归 —— 提取输出目录中发现的归档（例如 .tar.gz，或包含更多归档的安装程序），最多 --max-depth 层：

magic-extractor extract app-1.0.tar.gz --recursive

暴力破解 —— 当检测不确定时，尝试所有匹配的处理模块，而不是在第一个处停止：

magic-extractor extract weird-archive.dat --bruteforce

雕刻 —— 提取嵌入在更大文件内部某个偏移处的归档（固件映像的经典场景）。先检查，再雕刻：

magic-extractor carve router-firmware.bin --list
IDX      OFFSET          SIZE  NAME       DESCRIPTION
  0  0x00000000       793,720  pe         Windows PE binary
  1  0x000c1c78     2,495,983  lzma       LZMA compressed data

magic-extractor carve router-firmware.bin              # 雕刻并提取已知的数据块
magic-extractor carve router-firmware.bin --fragment 1 # 仅雕刻片段 #1

图形界面

一个可选的 tkinter 前端（位于 gui/）封装了 CLI —— 一个 Universal-Extractor 风格的窗口，提供 extract、scan 和 carve 模式、拖放、批处理队列、运行历史和“首选项”对话框。Run 选项下提供暴力破解功能。它调用同一个 main.py，因此检测和提取行为完全一致。

python gui/main.py                 # 启动窗口
python gui/main.py <file> [outdir] # 预填源文件（和目标目录）
python gui/main.py <file> /scan    # 预填并以识别模式启动

拖放功能需要可选的 tkinterdnd2 包（pip install -r gui/requirements.txt）；没有它窗口仍可工作，只是不支持拖放。它还可以从其“首选项”对话框注册一个资源管理器右键菜单项。

构建（Windows）

cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic

然后将 bin/、data/ 和 config.ini 复制到 dist/magic-extractor.exe 旁边。 CI 会自动执行此操作 —— 参见 .github/workflows/release.yml。

许可证

MIT —— 参见 LICENSE.txt。注意：cli/bin/ 下捆绑的第三方解压程序/检测器二进制文件保留其各自的许可证（部分为专有免费软件），不受 MIT 覆盖；分发前请核实其再分发条款。

作者

首席开发者：DSR! —— [email protected]
感谢所有贡献者。

magic-extractor v1.3.1

分类