
magic-extractor v1.3.1
通用 Windows 解压工具,可检测未知文件并将其路由到正确的内置解压器。
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 模型):
- puremagic——纯 Python,无子进程;对格式良好的归档进行廉价的 MIME 检查。
- 内置签名——
data/signatures.json中的魔数模式;可识别 引擎遗漏的归档器(bcm、dgca、kgb、uharc、alzip、freearc 等),无需 外部进程。 - DIE(Detect It Easy)——签名引擎;安装程序、PE 和 SFX 的专家。
- binwalk——短类型键(cpio、lzma 等)和嵌入内容。
- 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);
没有它窗口仍可正常工作,只是不支持拖放。文件可以拖放到窗口的任意位置;
当拖入多个文件时,第一个填入源路径,其余进入批处理队列。它还可以注册资源管理器
右键菜单项(编辑 → 添加到资源管理器菜单)。