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>

## Descrizione
Magic Extractor è uno strumento di estrazione universale per Windows che identifica un file
con diversi rilevatori e lo instrada verso il giusto estrattore incluso. Mira a
coprire i formati di compressione principali, gli installatori che si vedono oggi, e una
gamma di archiviatori meno comuni.

Rileva automaticamente **oltre 80 formati** — archivi, installatori, immagini disco, immagini
forensi (EWF/AFF/AD1), immagini di CD/DVD, archivi di posta e codec moderni. Vedi
[`formats.md`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) per l'elenco completo.

## Avvio rapido
Scarica la [versione più recente](../../releases/latest), estraila ed esegui:
```text
magic-extractor.exe extract mystery.bin
```
Vedi [Esempi](#examples) per `identify`, `list`, `carve`, `--recursive` e `--bruteforce`.

## Struttura del Progetto
- `cli`: codice sorgente.
  - `bin`: binari dei rilevatori ed estrattori inclusi.
    - `detectors`: DIE, Magika, binwalk (le definizioni di TrID sono convertite in `data/signatures.json`).
    - `extractors`: 7z, unrar, unace, unshield, lessmsi, dark (WiX) e altri.
  - `data`: configurazione runtime, caricata dinamicamente (vedi sotto).
  - `formats`: un modulo handler per ogni famiglia di formati.
- `gui`: front-end tkinter opzionale che incapsula la CLI (vedi [GUI](#gui)).
- `test`: file di esempio per ogni formato (fixture per i test di estrazione/rilevamento).
- `tools`: strumenti per sviluppatori (`generate_data.py` — genera i file dati dagli handler).

La build compilata mantiene `bin/`, `data/` e `config.ini` all'esterno dell'exe, così
possono essere aggiornati con una semplice sostituzione di file; il risolutore di percorsi in `main.py` li trova
accanto all'eseguibile (frozen) o sotto `cli/` (dev).

## Come funziona il rilevamento
Per l'estrazione normale, i rilevatori vengono eseguiti in questo ordine con **uscita anticipata** — il primo
che produce un handler noto vince (prima i più economici, quindi il modello ML viene di solito saltato):

1. **puremagic** — puro Python, nessun sottoprocesso; un controllo MIME economico per archivi ben formati.
2. **firme integrate (built-in)** — pattern magic-byte in `data/signatures.json`; nomina
   archiviatori che i motori non riconoscono (bcm, dgca, kgb, uharc, alzip, freearc, ...) senza
   processo esterno.
3. **DIE** (Detect It Easy) — motore a firme; lo specialista per installatori, PE e SFX.
4. **binwalk** — brevi chiavi di tipo (cpio, lzma, ...) e contenuto incorporato.
5. **Magika** — il rilevatore di tipo di contenuto AI di Google, come catch-all.

Ogni rilevatore contribuisce in modo unico (sono complementari, non ridondanti): il
database delle firme nomina archiviatori che i motori non riconoscono, DIE gestisce installatori/PE, binwalk
cattura alcuni tipi che gli altri non vedono, puremagic/Magika coprono il MIME.

PureMagic 2.x fornisce anche una scansione profonda consapevole del contenuto quando riceve l'intero
file. L'analisi dell'intero file è l'impostazione predefinita; il modificatore opzionale `--fast-check`
passa solo i primi 64 KiB quando la velocità di avvio conta più dell'ispezione profonda.

Ogni handler dichiara i propri indicatori tramite `detection_mimes()` /
`detection_names()` / `detection_signatures()`; `tools/generate_data.py` li compila
in `data/handlers.json` e `data/signatures.json` (con un eventuale
`data/extra_detections.json` sovrapposto). TrID non viene usato.

> Nota: qualsiasi formato la cui firma non è presente in [`magic_data.json`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/magic_data.json) di puremagic
> (o che puremagic segnala solo come generico `application/octet-stream`) deve
> dichiarare una voce `detection_signatures()` personalizzata nel suo handler — altrimenti
> non verrà rilevato dal contenuto.

- `--bruteforce` disabilita l'uscita anticipata: ogni rilevatore viene eseguito e ogni handler rilevato
  viene provato a turno (utile quando la prima ipotesi è sbagliata).
- Gli eseguibili che nessun rilevatore identifica ricadono sugli handler degli installatori a eseguibile racchiuso
  (BitRock, Clickteam, Inno, ...), che si auto-convalidano.
- Il sottocomando `carve` usa inoltre la mappa degli offset di binwalk per estrarre archivi
  incorporati a offset arbitrari (es. all'interno di immagini firmware).

La mappa di instradamento rilevamento → handler si trova in `data/handlers.json` (curata a mano,
caricata a runtime); una blacklist di token generici si trova in `data/detection_blacklist.json`.

## Formati Supportati
Vedi [formats.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) per l'elenco completo dei formati e dei relativi handler.

## Aggiungere un formato
Per aggiungere il supporto a un nuovo formato, vedi
[docs/adding-a-handler.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/adding-a-handler.md) — la guida completa
(classe handler, dichiarazione del rilevamento, lookup DIE/TrID, firme magic,
rigenerazione dei dati di instradamento, inclusione dello strumento e test).

## Installazione (da sorgente)
La maggior parte degli utenti scarica semplicemente la release (vedi [Avvio rapido](#quick-start)). Per eseguire da sorgente:
è richiesto Python 3.12 o successivo.

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

## Utilizzo
Magic Extractor usa sottocomandi:
```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)
```
Un semplice percorso senza sottocomando usa come predefinito `extract` (retrocompatibile):
```bash
python cli/main.py <path> <output_dir> [options]
```

Opzioni di `extract`:
- `--password <password>`: password per gli archivi criptati.
- `-r`, `--recursive`: estrae gli archivi trovati all'interno dell'output (limitato da `--max-depth`, default 5).
- `-b`, `--bruteforce`: prova ogni handler rilevato invece di fermarsi al primo.
- `--open-output-folder <true|false>`: apre la cartella di output al termine.
- `--check-free-space <true|false>`: avvisa se il volume di output potrebbe non avere spazio sufficiente.
- `--check-unicode <true|false>`: avvisa in caso di nomi estratti non ASCII.
- `--fix-file-extensions <true|false>`: assegna ai file estratti senza estensione un'estensione basata sul contenuto (non sovrascrive mai una esistente).
- `--create-log-files <true|false>`: scrive un log per ogni esecuzione nella cartella di output.

  (Ognuno usa il valore del proprio `config.ini` se omesso; combina con
  `--update-defaults` per rendere persistente il valore dato — es. `--open-output-folder false
  --update-defaults` disattiva un default precedentemente salvato.)
- `--fast-check`: controlla solo i primi 64 KiB invece di eseguire il rilevamento sull'intero file.
- `--update-defaults`: salva le impostazioni fornite come default in `config.ini`.

Opzioni di `carve`: `--list` (stampa la tabella dei frammenti di binwalk), `--fragment N` (estrae un
frammento per indice), `--raw` (estrae ogni frammento, non solo quelli noti agli handler).

> Negli esempi seguenti, `magic-extractor` è il `.exe` compilato. Da sorgente, sostituiscilo
> con `python cli/main.py` — gli argomenti sono identici.

## Esempi

**Estrarre un archivio** — non è necessario conoscerne il tipo; viene rilevato automaticamente:
```text
magic-extractor extract mystery.bin
# extracts into mystery_extracted/ next to the file
```

**Identificare** un file senza toccarlo — mostra cosa ha visto ogni rilevatore e quale
handler verrebbe eseguito:
```text
magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler
```

**Elencare** il contenuto di un archivio (senza estrazione):
```text
magic-extractor list backup.7z
```

**Ricorsivo** — estrae gli archivi trovati all'interno dell'output (es. un .tar.gz, o un
installer che contiene altri archivi), fino a `--max-depth` livelli:
```text
magic-extractor extract app-1.0.tar.gz --recursive
```

**Bruteforce** — quando il rilevamento è incerto, prova ogni handler corrispondente invece
di fermarsi al primo:
```text
magic-extractor extract weird-archive.dat --bruteforce
```

**Carve** — estrae gli archivi incorporati a un certo offset all'interno di un file più grande
(classico per le immagini firmware). Ispeziona prima, poi estrai:
```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
Un front-end tkinter opzionale (in `gui/`) incapsula la CLI — una finestra in stile Universal-Extractor
con modalità `extract`, `scan` e `carve`, drag-and-drop, una coda batch, cronologia
delle esecuzioni e una finestra Preferenze. Bruteforce è disponibile nelle opzioni di esecuzione. Fa
riferimento allo stesso `main.py`, quindi rilevamento ed estrazione si comportano in modo identico.
```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
```
Il drag-and-drop richiede il pacchetto opzionale `tkinterdnd2` (`pip install -r gui/requirements.txt`);
senza di esso la finestra funziona comunque, tranne che per il supporto al trascinamento. Può anche registrare una voce
nel menu contestuale di Esplora risorse dalla sua finestra Preferenze.

## Compilazione (Windows)
```bash
cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic
```
Quindi copia `bin/`, `data/` e `config.ini` accanto a `dist/magic-extractor.exe`.
La CI lo fa automaticamente — vedi `.github/workflows/release.yml`.

## Licenza
MIT — vedi `LICENSE.txt`. Nota: i binari di estrattori/rilevatori di terze parti
inclusi sotto `cli/bin/` mantengono le proprie licenze (alcuni freeware proprietari)
e non sono coperti da MIT; verifica i loro termini di ridistribuzione prima della distribuzione.

## Autori
- Sviluppatore principale: DSR! — [email protected]
- Grazie a tutti i collaboratori.