xchwarze/magic-extractor

# Magic Extractor

## 描述 Magic Extractor 是一款适用于 Windows 的通用提取工具，它通过多种探测器识别文件， 并将其路由到合适的内置提取器。它旨在 涵盖主流压缩格式、当今实际可见的安装程序， 以及各种不太常见的归档工具。 它会自动检测 **80 多种格式** —— 包括归档文件、安装程序、磁盘映像、取证 映像（EWF/AFF/AD1）、光盘映像、邮件存储和现代编解码器。完整列表请参见 [`formats.md`](formats.md)。 ## 快速开始 下载 [最新发布版本](../../releases/latest)，解压缩后运行： ``` magic-extractor.exe extract mystery.bin ``` 有关 `identify`、`list`、`carve`、`--recursive` 和 `--bruteforce` 的用法，请参见[示例](#examples)。 ## 项目结构 - `cli`：源代码。 - `bin`：内置的探测器和提取器二进制文件。 - `detectors`：DIE、Magika、binwalk（TrID 的特征定义已被转换为 `data/signatures.json`）。 - `extractors`：7z、unrar、unace、unshield、lessmsi、dark (WiX) 等。 - `data`：运行时配置，动态加载（见下文）。 - `formats`：每个格式系列对应一个处理模块。 - `gui`：封装了 CLI 的可选 tkinter 前端（参见 [GUI](#gui)）。 - `test`：每种格式的示例文件（用于提取/检测测试的固定数据）。 - `tools`：开发者工具（`generate_data.py` —— 从处理程序构建数据文件）。 编译后的构建版本将 `bin/`、`data/` 和 `config.ini` 保留在 exe 外部，因此 可以通过替换文件来更新它们；`main.py` 中的路径解析器会在可执行文件（冻结状态）旁边或 `cli/`（开发状态）下找到它们。 ## 检测工作原理 对于常规提取，探测器按以下顺序运行并采用 **提前退出** 机制 —— 第一个 匹配到已知处理程序的探测器获胜（成本最低的优先，因此 ML 模型通常会被跳过）： 1. **puremagic** —— 纯 Python 实现，无子进程；对格式良好的归档文件进行低成本的 MIME 检查。 2. **内置特征** —— `data/signatures.json` 中的 magic-byte 模式；在不使用 外部进程的情况下，为引擎遗漏的归档工具命名（bcm、dgca、kgb、uharc、alzip、freearc 等）。 3. **DIE** (Detect It Easy) —— 特征引擎；专门用于处理安装程序、PE 和 SFX。 4. **binwalk** —— 短类型键（cpio、lzma 等）和嵌入的内容。 5. **Magika** —— Google 的 AI 内容类型探测器，作为兜底方案。 每个探测器都有其独特的作用（它们是互补的，而非冗余的）： 特征数据库为引擎遗漏的归档工具命名，DIE 处理安装程序/PE，binwalk 捕获其他工具遗漏的少数类型，puremagic/Magika 则负责覆盖 MIME。 每个处理程序通过 `detection_mimes()` / `detection_names()` / `detection_signatures()` 声明其自身的指示符；`tools/generate_data.py` 会将其 编译为 `data/handlers.json` 和 `data/signatures.json`（并可选择在最上层合并 `data/extra_detections.json`）。此处不使用 TrID。 - `--bruteforce` 会禁用提前退出机制：每个探测器都会运行，并依次尝试每个检测到的处理程序 （在首次猜测错误时非常有用）。 - 未能被任何探测器识别的可执行文件将回退到封装了 exe 的安装程序 处理程序（BitRock、Clickteam、Inno 等），这些程序会进行自我验证。 - `carve` 子命令额外使用了 binwalk 的偏移量映射，以提取 嵌入在任意偏移量处的归档文件（例如在固件映像内部）。 检测 -> 处理程序的路由映射表位于 `data/handlers.json`（人工维护， 在运行时加载）；通用 token 的黑名单位于 `data/detection_blacklist.json`。 ## 支持的格式 有关格式及其处理程序的完整列表，请参见 [formats.md](formats.md)。 ## 添加格式 要添加对新格式的支持，请参见 [docs/adding-a-handler.md](docs/adding-a-handler.md) —— 这是一份端到端的指南 （包含处理程序类、检测声明、DIE/TrID 查找、magic signatures、 重新生成路由数据、捆绑工具以及测试）。 ## 安装（从源码） 大多数用户只需下载发布版本（参见[快速开始](#quick-start)）。若要从源码运行： ``` git clone cd magic-extractor pip install -r cli/requirements.txt ``` ## 用法 Magic Extractor 使用子命令： ``` python cli/main.py extract [output_dir] [options] # detect and extract python cli/main.py identify # report type + candidate handlers python cli/main.py list # list archive contents python cli/main.py carve [output_dir] [options] # carve embedded archives (binwalk offsets) ``` 不带子命令的纯路径默认为 `extract`（向后兼容）： ``` python cli/main.py [options] ``` `extract` 选项： - `--password `：用于加密归档文件的密码。 - `-r`, `--recursive`：提取在输出结果中发现的归档文件（受 `--max-depth` 限制，默认为 5）。 - `-b`, `--bruteforce`：尝试每个检测到的处理程序，而不是在第一个处停止。 - `--open-output-folder `：完成后打开输出文件夹。 - `--check-free-space `：如果输出卷可能空间不足，则发出警告。 - `--check-unicode `：针对非 ASCII 的提取文件名发出警告。 - `--fix-file-extensions `：为无扩展名的提取文件提供基于内容的扩展名（绝不覆盖现有扩展名）。 - `--create-log-files `：将每次运行的日志写入输出目录。 （省略时，每个选项都会默认使用其 `config.ini` 中的值；结合 `--update-defaults` 可将给定的值持久化保存 —— 例如，`--open-output-folder false --update-defaults` 会关闭之前保存的默认设置。） - `--no-fast-check`：读取整个文件进行检测，而不是仅读取前 2048 个字节。 - `--update-defaults`：将给定的设置作为默认值持久化保存在 `config.ini` 中。 `carve` 选项：`--list`（打印 binwalk 片段表），`--fragment N`（按索引提取单个 片段），`--raw`（提取所有片段，而不仅仅是处理程序已知的片段）。 ## 示例 **提取归档文件** —— 你不需要知道它的类型；系统会自动检测它： ``` 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 # carve + extract the known blobs magic-extractor carve router-firmware.bin --fragment 1 # carve only fragment #1 ``` ## GUI 可选的 tkinter 前端（位于 `gui/` 中）封装了 CLI —— 这是一个 Universal-Extractor 风格的 窗口，支持拖放、批量队列、运行历史记录和首选项对话框。它 通过外部调用同一个 `main.py` 来执行，因此检测和提取的行为完全一致。 ``` python gui/main.py # launch the window python gui/main.py [outdir] # prefill the source (and destination) python gui/main.py /scan # prefill and start in identify mode ``` 拖放功能需要可选的 `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! —— xchwarze@gmail.com - 感谢所有贡献者。

标签：数字取证, 数据解析, 文件提取, 文件系统, 格式识别, 漏洞挖掘, 自动化脚本, 逆向工具