magic-extractor

# 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>

## 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`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) para a lista completa.

## Início Rápido
Baixe o [último lançamento](../../releases/latest), descompacte-o e execute:
```text
magic-extractor.exe extract mystery.bin
```
Consulte [Exemplos](#examples) 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](#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`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/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](https://github.com/xchwarze/magic-extractor/blob/master/docs/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](https://github.com/xchwarze/magic-extractor/blob/master/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](#quick-start)). Para executar a partir do código-fonte:
Python 3.12 ou mais recente é necessário.

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

## Uso
O Magic Extractor usa subcomandos:
```bash
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):
```bash
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

**Extrair um arquivo compactado** — você não precisa saber o tipo; ele é detectado automaticamente:
```text
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:
```text
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):
```text
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:
```text
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:
```text
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:
```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              # 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.
```bash
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)
```bash
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.