返回更新列表
新发布Aug 27, 2026

magic-extractor v1.3.1

通用 Windows 解压工具,可检测未知文件并将其路由到正确的内置解压器。

分享

Magic Extractor

Magic Extractor

描述

Magic Extractor 是一款适用于 Windows 的通用提取工具,它使用多种检测器识别文件,并将其路由到正确的内置提取器。它旨在覆盖主流压缩格式、当前实际常见的安装程序,以及一系列较少见的归档工具。

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

快速开始

下载最新版本,解压后运行:

magic-extractor.exe extract mystery.bin

有关 identify、list、carve、--recursive 和 --bruteforce 的用法,请参见示例。

项目结构

  • src/cli:命令行工具。
    • bin:随附的检测器和提取器二进制文件。
      • detectors:DIE、Magika、binwalk(TrID 的定义已转换为 data/signatures.json)。
      • extractors:7-Zip(以及作为后备的 7-Zip ZS)、unrar、unace、unshield、lessmsi、 dark(WiX)等。
    • data:由各处理器生成的路由数据(见下文)。
    • formats:每个格式族对应一个处理器模块。
  • src/gui:可选的 tkinter 前端,封装了 CLI(见 GUI)。
    • icons:为浅色和深色模式烘焙成 PNG 的 Fluent 图标。
  • test:单元测试、格式与引擎测试组,以及每种格式的示例文件。
  • tools:开发者工具——generate_data.py(从处理器构建路由数据)和 generate_icons.py(烘焙 GUI 图标)。
  • update:更新器配置以及用于刷新随附二进制文件的脚本。
  • docs:支持的格式、如何添加处理器、第三方声明。

编译后的构建会将 bin/、data/ 和 config.ini 保留在 exe 外部,以便 通过替换文件进行更新;cli_paths.py 会在可执行文件旁(冻结状态)或 src/cli/ 下(开发状态)找到它们。

检测工作原理

对于常规提取,检测器按以下顺序运行,并采用提前退出——第一个 产生已知处理器的检测器胜出(从最廉价的开始,因此通常会跳过 ML 模型):

  1. puremagic——纯 Python,无子进程;对格式良好的归档进行廉价的 MIME 检查。
  2. 内置签名——data/signatures.json 中的魔数模式;可识别 引擎遗漏的归档器(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。

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 禁用提前退出:所有检测器都会运行,并依次尝试每个检测到的 处理器(当第一个猜测错误时很有用)。
  • 可执行文件还会获得 SFX 和安装程序处理器(RAR、ACE、ARC、KGB、UHARC、 Inno Setup、BitRock、Clickteam)作为后备候选;每个处理器都会拒绝 不属于自己的文件,因此链条会继续到下一个。
  • carve 子命令还会使用 binwalk 的偏移映射来提取嵌入在任意偏移处的 归档(例如固件镜像内部)。

检测 → 处理器路由映射位于 data/handlers.json(生成后,在运行时 加载)。一个键可以映射到多个处理器,按顺序尝试直到一个成功: 例如先尝试 7-Zip,然后对主线 7-Zip 无法打开的内容(使用 LZ4 的 SquashFS、 使用 ZSTD 的 NSIS)尝试 7-Zip ZS。通用令牌黑名单位于 data/detection_blacklist.json。

支持的格式

有关格式及其处理器的完整列表,请参见 formats.md。

添加格式

要添加对新格式的支持,请参阅 docs/adding-a-handler.md —— 端到端指南 (handler 类、检测声明、DIE/TrID 查询、magic 签名、 重新生成路由数据、打包工具以及测试)。

安装(从源码)

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

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

用法

Magic Extractor 使用子命令:

python src/cli/main.py extract  <path> [output_dir] [options]   # detect and extract
python src/cli/main.py identify <path>                          # report type + candidate handlers
python src/cli/main.py list     <path>                          # list archive contents
python src/cli/main.py carve    <path> [output_dir] [options]   # carve embedded archives (binwalk offsets)

不带子命令的裸路径默认使用 extract(向后兼容),并且 选项可以放在路径或子命令之前:

python src/cli/main.py <path> <output_dir> [options]
python src/cli/main.py --debug <path>
python src/cli/main.py --version

--debug 和 --fast-check 适用于所有子命令;--password 适用于 extract、list 和 carve。

<path> 对每个子命令都可以是文件夹:其中的文件(不含子文件夹)会被 逐个处理。每个文件都有自己的输出文件夹:<stem>_extracted (位于文件旁边,若指定了 output_dir 则位于其下),或者当两个文件共享同一 词干时使用 <name>_extracted。

如果输出文件夹中已有文件,extract 会写入新的 <folder>_<YYYYmmdd-HHMMSS>,而不是与先前结果混合或覆盖;--merge-output 则改为提取到现有文件夹中,覆盖同名文件和文件夹(当目标被锁定时,GUI 会这样做)。 被提取的归档文件本身永远不会被覆盖。每次处理程序尝试都在其自己的临时文件夹中 运行,因此失败的尝试绝不会留下部分文件。

退出码:0 成功;1 失败——无法提取任何内容、文件夹运行中的某个文件失败、 文件夹中没有文件,或 --delete-source 无法删除源文件;2 参数无效; 3 提取时出现错误——工具报告了失败,但大部分内容已提取(例如 Linux 镜像中的 符号链接无法在 Windows 上创建),因此内容保留在输出文件夹中,且源文件 不会被删除。使用 --recursive 时,无法提取的嵌套归档会作为警告报告, 且不会改变退出码(许多已提取的文件,例如安装程序的每个 DLL,看起来都像 候选对象)。

extract 选项:

  • --password <password>:加密归档的密码。

  • -r、--recursive:提取输出中发现的归档(受 --max-depth 限制,默认 5)。

  • -b、--bruteforce:尝试检测到的每个处理程序,而不是在第一个处停止。

  • --merge-output:即使输出文件夹中已有文件也提取到其中, 覆盖同名内容。

  • --delete-source:成功提取后删除源文件(除非 config.ini 中 delete_to_recycle_bin 已关闭,否则放入回收站)。

  • --open-output-folder <true|false>:完成后打开输出文件夹。

  • --check-free-space <true|false>:如果输出卷可能空间不足则发出警告。

  • --check-unicode <true|false>:对非 ASCII 的已提取名称发出警告。

  • --fix-file-extensions <true|false>:为无扩展名的已提取文件提供基于内容的扩展名(绝不覆盖已有扩展名)。默认关闭:猜测可能出错(Makefile、LICENSE 或 configure 会变成 .txt)。

  • --create-log-files <true|false>:将 magic-extractor.log 写入输出文件夹。

    (省略时,每项都默认为其 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 src/cli/main.py——参数完全相同。

示例

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

magic-extractor extract mystery.bin
# extracts into mystery_extracted/ next to the file

识别文件而不触碰它——显示每个检测器看到的内容以及将运行哪个处理器:

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

Carve — 提取嵌入在较大文件中某个偏移位置的归档(固件镜像的典型场景)。先检查,再提取:

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 前端(位于 src/gui/)封装了 CLI——一个 Universal-Extractor 风格的窗口,包含 extract、scan 和 carve 模式、拖放、批处理队列、运行历史以及首选项对话框。暴力破解可在运行选项下使用。它通过 shell 调用同一个 main.py,因此检测和提取行为完全一致。

python src/gui/main.py                 # launch the window
python src/gui/main.py <file> [outdir] # prefill the source (and destination)
python src/gui/main.py <file> /scan    # prefill and start in identify mode

拖放功能需要可选的 tkinterdnd2 包(pip install -r src/gui/requirements.txt); 没有它窗口仍可正常工作,只是不支持拖放。文件可以拖放到窗口的任意位置; 当拖入多个文件时,第一个填入源路径,其余进入批处理队列。它还可以注册资源管理器 右键菜单项(编辑 → 添加到资源管理器菜单)。

分类