Magic Extractor

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 per l'elenco completo.

Avvio rapido

Scarica la versione più recente, estraila ed esegui:

magic-extractor.exe extract mystery.bin

Vedi Esempi 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).
• 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 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 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 — 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). Per eseguire da sorgente: è richiesto Python 3.12 o successivo.

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

Utilizzo

Magic Extractor usa sottocomandi:

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

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:

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