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):

1. puremagic — python puro, sem subprocesso; uma verificação MIME barata para arquivos bem formados.
2. 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.
3. DIE (Detect It Easy) — mecanismo de assinaturas; o especialista em instaladores, PE e SFX.
4. binwalk — chaves de tipo curtas (cpio, lzma, ...) e conteúdo embutido.
5. 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.

  (Cada um usa como padrão o valor do config.ini quando omitido; combine com --update-defaults para persistir o valor informado — por exemplo, --open-output-folder false --update-defaults desativa um padrão salvo anteriormente.)

• --fast-check: verifica apenas os primeiros 64 KiB em vez de executar a detecção no arquivo completo.

• --update-defaults: persiste as configurações fornecidas como padrões no config.ini.

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