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-модель обычно пропускается):

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

Примеры