Универсальный инструмент извлечения для Windows, который распознаёт неизвестные файлы и направляет их в соответствующий встроенный экстрактор.
# Magic Extractor
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7022/1ecc2fe011937465abd72031b0aa914c85a941290702969520086741770b5bea.png" alt="Magic Extractor" width="250" height="250">
</p>
## Описание
Magic Extractor — это универсальный инструмент извлечения для Windows, который определяет файл
с помощью нескольких детекторов и направляет его к подходящему встроенному экстрактору. Он нацелен на
покрытие основных форматов сжатия, установщиков, которые вы реально видите сегодня, а также
ряда менее распространённых архиваторов.
Он автоматически определяет **80+ форматов** — архивы, установщики, образы дисков, криминалистические
образы (EWF/AFF/AD1), образы оптических дисков, почтовые хранилища и современные кодеки. Полный
список см. в [`formats.md`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md).
## Быстрый старт
Скачайте [последний релиз](../../releases/latest), распакуйте его и выполните:
```text
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](#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`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/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](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md).
## Добавление формата
Чтобы добавить поддержку нового формата, см.
[docs/adding-a-handler.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/adding-a-handler.md) — сквозное руководство
(класс обработчика, объявление определения, поиск в DIE/TrID, magic-сигнатуры,
перегенерация данных маршрутизации, встраивание инструмента и тестирование).
## Установка (из исходников)
Большинству пользователей достаточно скачать релиз (см. [Быстрый старт](#быстрый-старт)). Для запуска из исходников:
требуется Python 3.12 или новее.
```bash
git clone <repo-url>
cd magic-extractor
pip install -r cli/requirements.txt
```
## Использование
Magic Extractor использует подкоманды:
```bash
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` (обратная совместимость):
```bash
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` — аргументы идентичны.
## Примеры
**Извлечь архив** — не нужно знать его тип; он определяется автоматически:
```text
magic-extractor extract mystery.bin
# извлекает в папку mystery_extracted/ рядом с файлом
```
**Определить** файл, не трогая его — показывает, что увидел каждый детектор и какой
обработчик запустился бы:
```text
magic-extractor identify setup.exe
File: setup.exe
[DIE] detect inno setup installer
Candidate handlers (in order):
- FormatInnoSetupHandler
```
**Вывести список** содержимого архива (без извлечения):
```text
magic-extractor list backup.7z
```
**Рекурсивно** — извлекать архивы, найденные внутри выходных данных (например, .tar.gz или
установщик, содержащий другие архивы), до уровня `--max-depth`:
```text
magic-extractor extract app-1.0.tar.gz --recursive
```
**Bruteforce** — когда определение ненадёжно, пробовать каждый подошедший обработчик вместо
остановки на первом:
```text
magic-extractor extract weird-archive.dat --bruteforce
```
**Carve** — извлекать архивы, встроенные по некоторому смещению внутри более крупного файла
(классика для образов прошивок). Сначала просмотр, затем извлечение:
```text
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`, поэтому определение и извлечение работают идентично.
```bash
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)
```bash
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]
- Спасибо всем участникам.