
magic-extractor v1.3.1
Ferramenta universal de extração para Windows que detecta arquivos desconhecidos e os direciona para o extrator integrado correto.
Magic Extractor
Descrição
Magic Extractor é uma ferramenta de extração universal para Windows que identifica um arquivo com vários detetores e o encaminha para o extrator adequado incluído. O seu objetivo é cobrir os formatos de compressão mais comuns, os instaladores que realmente se veem hoje em dia e uma série de arquivadores menos comuns.
Deteta automaticamente mais de 80 formatos — arquivos, instaladores, imagens de disco, imagens
forenses (EWF/AFF/AD1), imagens de disco ótico, armazenamentos de correio e codecs modernos. Consulte
formats.md para a lista completa.
Início Rápido
Descarregue a versão mais recente, descomprima-a e execute:
magic-extractor.exe extract mystery.bin
Consulte Exemplos para identify, list, carve, --recursive e --bruteforce.
Estrutura do Projeto
src/cli: a ferramenta de linha de comando.bin: binários de detecção e extração incluídos.detectors: DIE, Magika, binwalk (as definições do TrID são convertidas paradata/signatures.json).extractors: 7-Zip (mais 7-Zip ZS como alternativa), unrar, unace, unshield, lessmsi, dark (WiX) e outros.
data: dados de roteamento gerados a partir dos handlers (veja abaixo).formats: um módulo handler por família de formato.
src/gui: front-end tkinter opcional que envolve a CLI (veja GUI).icons: ícones Fluent convertidos em PNGs para modo claro e escuro.
test: testes unitários, as baterias de formato e motor, e arquivos de exemplo por formato.tools: ferramentas para desenvolvedores —generate_data.py(constrói os dados de roteamento a partir dos handlers) egenerate_icons.py(gera os ícones da GUI).update: a configuração do atualizador e os scripts que atualizam os binários incluídos.docs: formatos suportados, como adicionar um handler, avisos de terceiros.
A compilação mantém bin/, data/ e config.ini externos ao exe para que
possam ser atualizados com uma troca de arquivos; cli_paths.py os encontra ao lado do
executável (congelado) ou em src/cli/ (desenvolvimento).
Como funciona a detecção
Para extração normal, os detectores são executados nesta ordem com saída antecipada — o primeiro que produzir um handler conhecido vence (do mais barato primeiro, então o modelo de ML geralmente é ignorado):
- puremagic — pure-python, sem subprocesso; uma verificação MIME barata para arquivos bem formados.
- assinaturas integradas — padrões de magic-byte em
data/signatures.json; nomeia arquivadores que os motores não detectam (bcm, dgca, kgb, uharc, alzip, freearc, ...) sem processo externo. - DIE (Detect It Easy) — motor de assinaturas; o especialista para instaladores, PE e SFX.
- binwalk — chaves de tipo curtas (cpio, lzma, ...) e conteúdo incorporado.
- Magika — detector de tipo de conteúdo por IA do Google, como alternativa abrangente.
Cada detector contribui de forma única (são complementares, não redundantes): o banco de assinaturas nomeia arquivadores que os motores não detectam, o DIE lida com instaladores/PE, o binwalk captura alguns tipos que os outros não detectam, puremagic/Magika cobrem MIME.
O PureMagic 2.x também fornece varredura profunda sensível ao conteúdo quando recebe o arquivo
completo. A análise do arquivo completo é o padrão; o modificador opcional --fast-check
passa apenas os primeiros 64 KiB quando a velocidade de inicialização importa mais que a inspeção profunda.
Cada handler declara seus próprios indicadores via detection_mimes() /
detection_names() / detection_signatures(); tools/generate_data.py compila
estes 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.jsondo puremagic (ou que o puremagic reporte apenas como um genéricoapplication/octet-stream) deve declarar uma entrada personalizada emdetection_signatures()em seu handler — caso contrário não será detectado por conteúdo.
--bruteforcedesativa a saída antecipada: todos os detectores são executados e cada handler detectado é tentado por vez (útil quando a primeira suposição está errada).- Executáveis também recebem os handlers SFX e de instalador (RAR, ACE, ARC, KGB, UHARC, Inno Setup, BitRock, Clickteam) como candidatos de fallback; cada um rejeita arquivos que não são seus, então a cadeia avança para o próximo.
- O subcomando
carvetambém usa o mapa de offsets do binwalk para extrair arquivos incorporados em offsets arbitrários (por exemplo, dentro de imagens de firmware).
O mapa de roteamento detecção → handler fica em data/handlers.json (gerado, carregado
em tempo de execução). Uma chave pode mapear para vários handlers, tentados em ordem até um ter sucesso:
por exemplo, 7-Zip primeiro, depois 7-Zip ZS para o que o 7-Zip principal não consegue abrir (SquashFS com
LZ4, NSIS com ZSTD). Uma lista de bloqueio de tokens genéricos fica em data/detection_blacklist.json.
Formatos Suportados
Consulte formats.md para a lista completa de formatos e seus handlers.
Adicionando um formato
Para adicionar suporte a um novo formato, consulte docs/adding-a-handler.md — o guia completo (classe 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 a versão de lançamento (consulte Início Rápido). Para executar a partir do código-fonte: é necessário Python 3.12 ou mais recente.
git clone <repo-url>
cd magic-extractor
pip install -r src/cli/requirements.txt
Uso
O Magic Extractor utiliza subcomandos:
python src/cli/main.py extract <path> [output_dir] [options] # detect and extract
python src/cli/main.py identify <path> # report type + candidate handlers
python src/cli/main.py list <path> # list archive contents
python src/cli/main.py carve <path> [output_dir] [options] # carve embedded archives (binwalk offsets)
Um caminho simples sem subcomando assume extract por padrão (compatível com versões anteriores), e as opções podem vir antes do caminho ou do subcomando:
python src/cli/main.py <path> <output_dir> [options]
python src/cli/main.py --debug <path>
python src/cli/main.py --version
--debug e --fast-check funcionam com todos os subcomandos; --password com
extract, list e carve.
<path> pode ser uma pasta para todos os subcomandos: os seus ficheiros (não as subpastas) são
processados um a um. Cada ficheiro recebe a sua própria pasta de saída: <stem>_extracted
(junto ao ficheiro, ou em output_dir quando indicado), ou <name>_extracted quando
dois ficheiros partilham o mesmo stem.