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 (см. GUI).
test: примеры файлов для каждого формата (фикстуры для тестов извлечения/определения).
tools: инструменты для разработчиков (generate_data.py — собирает файлы данных из обработчиков).

В собранной сборке bin/, data/ и config.ini остаются внешними по отношению к exe, чтобы их можно было обновлять простой заменой файлов; резолвер путей в main.py находит их рядом с исполняемым файлом (в замороженном виде) или в cli/ (в режиме разработки).

Как работает определение

Для обычного извлечения детекторы запускаются в следующем порядке с ранним выходом — первый, кто даёт известный обработчик, выигрывает (сначала самые дешёвые, поэтому ML-модель обычно пропускается):

puremagic — чистый Python, без субпроцессов; дешёвая MIME-проверка для корректно сформированных архивов.
Встроенные сигнатуры — шаблоны magic-байтов в data/signatures.json; называет архиваторы, которые движки пропускают (bcm, dgca, kgb, uharc, alzip, freearc, ...) без внешнего процесса.
DIE (Detect It Easy) — сигнатурный движок; специалист по установщикам, PE и SFX.
binwalk — короткие типовые ключи (cpio, lzma, ...) и встроенное содержимое.
Magika — AI-детектор типа контента от Google, как универсальное средство.

Каждый детектор вносит уникальный вклад (они дополняют друг друга, а не дублируются): база сигнатур называет архиваторы, которые движки пропускают, DIE обрабатывает установщики/PE, binwalk ловит несколько типов, которые остальные пропускают, puremagic/Magika покрывают MIME.

PureMagic 2.x также обеспечивает контент-зависимое глубокое сканирование, когда получает полный файл. Анализ полного файла используется по умолчанию; опциональный модификатор --fast-check передаёт только первые 64 КиБ, когда скорость запуска важнее глубокой проверки.

Каждый обработчик объявляет собственные индикаторы через detection_mimes() / detection_names() / detection_signatures(); tools/generate_data.py компилирует их в data/handlers.json и data/signatures.json (с опциональным data/extra_detections.json, накладываемым сверху). TrID не используется.

Примечание: любой формат, сигнатура которого отсутствует в magic_data.json из puremagic (или который 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, magic-сигнатуры, перегенерация данных маршрутизации, встраивание инструмента и тестирование).

Установка (из исходников)

Большинству пользователей достаточно скачать релиз (см. Быстрый старт). Для запуска из исходников: требуется 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>: записывать журнал каждого запуска в выходной каталог.

Параметры 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

Bruteforce — когда определение ненадёжно, пробовать каждый подошедший обработчик вместо остановки на первом:

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              # извлечь + распаковать известные блобы
magic-extractor carve router-firmware.bin --fragment 1 # извлечь только фрагмент №1

GUI

Опциональный tkinter-интерфейс (в gui/) оборачивает CLI — окно в стиле Universal-Extractor с режимами extract, scan и carve, перетаскиванием, пакетной очередью, историей запусков и диалогом настроек. Bruteforce доступен в параметрах запуска. Он вызывает тот же main.py, поэтому определение и извлечение работают идентично.

python gui/main.py                 # запустить окно
python gui/main.py <file> [outdir] # предзаполнить источник (и назначение)
python gui/main.py <file> /scan    # предзаполнить и запустить в режиме identify

Для перетаскивания требуется опциональный пакет 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/ сохраняют собственные лицензии (некоторые проприетарный freeware) и не покрываются MIT; проверьте условия их распространения перед публикацией.

Авторы

Ведущий разработчик: DSR! — [email protected]
Спасибо всем участникам.

Популярное

magic-extractor