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 см. в разделе Примеры.
Структура проекта
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>: записывать журнал каждого запуска в выходной каталог.(Каждый параметр по умолчанию берёт значение из
config.ini, если не указан; комбинируйте с--update-defaults, чтобы сохранить указанное значение — например,--open-output-folder false --update-defaultsотключает ранее сохранённое значение по умолчанию.) -
--fast-check: проверять только первые 64 КиБ вместо полного определения файла. -
--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
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]
- Спасибо всем участникам.