Magic Extractor

Descrição

O Magic Extractor é uma ferramenta universal de extração para Windows que identifica um arquivo com vários detectores e o encaminha para o extrator incluído correto. Seu objetivo é cobrir formatos de compressão convencionais, os instaladores que você vê hoje e uma variedade de arquivadores menos comuns.

Ele detecta automaticamente mais de 80 formatos — arquivos compactados, instaladores, imagens de disco, imagens forenses (EWF/AFF/AD1), imagens de CD/DVD, armazenamentos de e-mail e codecs modernos. Consulte formats.md para a lista completa.

Início Rápido

Baixe o último lançamento, descompacte-o e execute:

magic-extractor.exe extract mystery.bin

Consulte Exemplos para identify, list, carve, --recursive e --bruteforce.

Estrutura do Projeto

cli: código-fonte.
- bin: binários de detectores e extratores incluídos.
  - detectors: DIE, Magika, binwalk (as definições do TrID são convertidas em data/signatures.json).
  - extractors: 7z, unrar, unace, unshield, lessmsi, dark (WiX), e mais.
- data: configuração em tempo de execução, carregada dinamicamente (veja abaixo).
- formats: um módulo de handler por família de formato.
gui: front-end opcional em tkinter que envolve a CLI (veja GUI).
test: arquivos de exemplo por formato (fixtures para os testes de extração/detecção).
tools: ferramentas de desenvolvimento (generate_data.py — gera os arquivos de dados a partir dos handlers).

O build compilado mantém bin/, data/ e config.ini externos ao exe para que possam ser atualizados com uma troca de arquivos; o resolvedor de caminhos em main.py os encontra ao lado do executável (congelado) ou em cli/ (desenvolvimento).

Como a detecção funciona

Para extração normal, os detectores são executados nesta ordem com early-exit — o primeiro que resultar em um handler conhecido vence (o mais barato primeiro, então o modelo de ML normalmente é ignorado):

puremagic — python puro, sem subprocesso; uma verificação MIME barata para arquivos bem formados.
assinaturas integradas — padrões de magic bytes em data/signatures.json; identifica arquivadores que os mecanismos não detectam (bcm, dgca, kgb, uharc, alzip, freearc, ...) sem processo externo.
DIE (Detect It Easy) — mecanismo de assinaturas; o especialista em instaladores, PE e SFX.
binwalk — chaves de tipo curtas (cpio, lzma, ...) e conteúdo embutido.
Magika — o detector de tipo de conteúdo por IA do Google, como uma opção abrangente.

Cada detector contribui de forma única (eles são complementares, não redundantes): o banco de assinaturas identifica arquivadores que os mecanismos não detectam, o DIE lida com instaladores/PE, o binwalk captura alguns tipos que os outros não detectam, o puremagic/Magika cobre MIME.

O PureMagic 2.x também fornece varredura profunda com consciência de conteúdo quando recebe o arquivo completo. A análise de arquivo completo é o padrão; o modificador opcional --fast-check passa apenas os primeiros 64 KiB quando a velocidade de inicialização é mais importante que a inspeção profunda.

Cada handler declara seus próprios indicadores via detection_mimes() / detection_names() / detection_signatures(); o tools/generate_data.py compila isso em data/handlers.json e data/signatures.json (com um opcional data/extra_detections.json mesclado por cima). O TrID não é usado.

Nota: qualquer formato cuja assinatura esteja ausente do magic_data.json do puremagic (ou que o puremagic relate apenas como um application/octet-stream genérico) deve declarar uma entrada detection_signatures() personalizada em seu handler — caso contrário, ele não será detectado pelo conteúdo.

--bruteforce desativa o early-exit: todos os detectores são executados e cada handler detectado é testado por vez (útil quando o primeiro palpite está errado).
Executáveis que nenhum detector identifica recorrem aos handlers de instaladores de exe encapsulados (BitRock, Clickteam, Inno, ...), que se autovalidam.
O subcomando carve também usa o mapa de deslocamentos do binwalk para extrair arquivos compactados embutidos em deslocamentos arbitrários (por exemplo, dentro de imagens de firmware).

O mapa de roteamento detecção → handler fica em data/handlers.json (curado manualmente, carregado em tempo de execução); uma blacklist de tokens genéricos fica em data/detection_blacklist.json.

Formatos Suportados

Consulte formats.md para a lista completa de formatos e seus handlers.

Adicionar um formato

Para adicionar suporte a um novo formato, consulte docs/adding-a-handler.md — o guia completo (classe do handler, declaração de detecção, consulta DIE/TrID, assinaturas mágicas, regeneração dos dados de roteamento, empacotamento da ferramenta e testes).

Instalação (a partir do código-fonte)

A maioria dos usuários apenas baixa o lançamento (veja Início Rápido). Para executar a partir do código-fonte: Python 3.12 ou mais recente é necessário.

git clone <repo-url>
cd magic-extractor
pip install -r cli/requirements.txt

Uso

O Magic Extractor usa subcomandos:

python cli/main.py extract  <path> [output_dir] [options]   # detect and extract
python cli/main.py identify <path>                          # report type + candidate handlers
python cli/main.py list     <path>                          # list archive contents
python cli/main.py carve    <path> [output_dir] [options]   # carve embedded archives (binwalk offsets)

Um caminho simples sem subcomando usa o padrão extract (retrocompatível):

python cli/main.py <path> <output_dir> [options]

Opções de extract:

--password <password>: senha para arquivos compactados criptografados.
-r, --recursive: extrai arquivos compactados encontrados dentro da saída (limitado por --max-depth, padrão 5).
-b, --bruteforce: tenta todos os handlers detectados em vez de parar no primeiro.
--open-output-folder <true|false>: abrir a pasta de saída ao finalizar.
--check-free-space <true|false>: alertar se o volume de saída pode não ter espaço suficiente.
--check-unicode <true|false>: alertar sobre nomes extraídos não ASCII.
--fix-file-extensions <true|false>: atribuir uma extensão baseada no conteúdo a arquivos extraídos sem extensão (nunca sobrescreve uma existente).
--create-log-files <true|false>: gravar um log de cada execução na pasta de saída.

Opções de carve: --list (imprime a tabela de fragmentos do binwalk), --fragment N (extrai um fragmento por índice), --raw (extrai todos os fragmentos, não apenas os conhecidos pelos handlers).

Nos exemplos abaixo, magic-extractor é o .exe compilado. A partir do código-fonte, substitua por python cli/main.py — os argumentos são idênticos.

Exemplos

Extrair um arquivo compactado — você não precisa saber o tipo; ele é detectado automaticamente:

magic-extractor extract mystery.bin
# extracts into mystery_extracted/ next to the file

Identificar um arquivo sem tocá-lo — mostra o que cada detector viu e qual handler seria executado:

magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler

Listar o conteúdo de um arquivo compactado (sem extração):

magic-extractor list backup.7z

Recursivo — extrai arquivos compactados encontrados dentro da saída (por exemplo, um .tar.gz ou um instalador que contenha mais arquivos compactados), até --max-depth níveis:

magic-extractor extract app-1.0.tar.gz --recursive

Bruteforce — quando a detecção é incerta, tente todos os handlers que corresponderam em vez de parar no primeiro:

magic-extractor extract weird-archive.dat --bruteforce

Carve — extrai arquivos compactados embutidos em algum deslocamento dentro de um arquivo maior (clássico para imagens de firmware). Inspecione primeiro e depois faça o 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

Um front-end opcional em tkinter (em gui/) envolve a CLI — uma janela no estilo Universal-Extractor com modos extract, scan e carve, arrastar e soltar, uma fila de lotes, histórico de execuções e uma caixa de diálogo de Preferências. O Bruteforce está disponível nas opções de execução. Ele chama o mesmo main.py, portanto a detecção e a extração se comportam de forma idêntica.

python gui/main.py                 # launch the window
python gui/main.py <file> [outdir] # prefill the source (and destination)
python gui/main.py <file> /scan    # prefill and start in identify mode

Arrastar e soltar exige o pacote opcional tkinterdnd2 (pip install -r gui/requirements.txt); sem ele, a janela continua funcionando, exceto pelo suporte a arrastar. Ela também pode registrar uma entrada de menu de contexto do Explorer na caixa de diálogo de Preferências.

Compilação (Windows)

cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic

Em seguida, copie bin/, data/ e config.ini para junto de dist/magic-extractor.exe. A CI faz isso automaticamente — veja .github/workflows/release.yml.

Licença

MIT — veja LICENSE.txt. Nota: os binários de extratores/detectores de terceiros incluídos em cli/bin/ mantêm suas próprias licenças (alguns são freeware proprietário) e não são cobertos pelo MIT; verifique os termos de redistribuição antes de distribuir.

Autores

Desenvolvedor Principal: DSR! — [email protected]
Agradecimentos a todos os colaboradores.

Mais Populares

magic-extractor