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.

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

Identificare un file senza toccarlo — mostra cosa ha visto ogni rilevatore e quale handler verrebbe eseguito:

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

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:

magic-extractor extract app-1.0.tar.gz --recursive

Bruteforce — quando il rilevamento è incerto, prova ogni handler corrispondente invece di fermarsi al primo:

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:

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.

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)

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.