
magic-extractor v1.3.1
Strumento di estrazione universale per Windows che rileva i file sconosciuti e li indirizza al giusto estrattore incluso.
Magic Extractor
Descrizione
Magic Extractor è uno strumento di estrazione universale per Windows che identifica un file con diversi rilevatori e lo indirizza all'estrattore corretto incluso nel pacchetto. Mira a coprire i formati di compressione mainstream, gli installer che si incontrano realmente oggi e una serie di archiviatori meno comuni.
Rileva automaticamente oltre 80 formati — archivi, installer, immagini disco, immagini
forensi (EWF/AFF/AD1), immagini di dischi ottici, archivi di posta e codec moderni. Consulta
formats.md per l'elenco completo.
Avvio rapido
Scarica la versione più recente, estraila e avvia:
magic-extractor.exe extract mystery.bin
Vedi Esempi per identify, list, carve, --recursive e --bruteforce.
Struttura del progetto
src/cli: lo strumento da riga di comando.bin: binari dei rilevatori e degli estrattori inclusi.detectors: DIE, Magika, binwalk (le definizioni di TrID sono convertite indata/signatures.json).extractors: 7-Zip (più 7-Zip ZS come fallback), unrar, unace, unshield, lessmsi, dark (WiX) e altri.
data: dati di routing generati dagli handler (vedi sotto).formats: un modulo handler per ogni famiglia di formati.
src/gui: front-end tkinter opzionale che avvolge la CLI (vedi GUI).icons: icone Fluent convertite in PNG per modalità chiara e scura.
test: test unitari, le batterie di formati e motori, e file di esempio per formato.tools: strumenti per sviluppatori —generate_data.py(costruisce i dati di routing dagli handler) egenerate_icons.py(genera le icone della GUI).update: la configurazione dell'updater e gli script che aggiornano i binari inclusi.docs: formati supportati, come aggiungere un handler, note di terze parti.
La build compilata mantiene bin/, data/ e config.ini esterni all'exe così
possono essere aggiornati con una sostituzione di file; cli_paths.py li trova accanto
all'eseguibile (frozen) o sotto src/cli/ (dev).
Come funziona il rilevamento
Per l'estrazione normale, i rilevatori vengono eseguiti in questo ordine con early-exit — il primo che produce un handler noto vince (prima i più economici, così il modello ML viene di solito saltato):
- puremagic — pure-python, nessun sottoprocesso; un controllo MIME economico per archivi ben formati.
- firme integrate — pattern di magic-byte in
data/signatures.json; identifica gli archiviatori che i motori non rilevano (bcm, dgca, kgb, uharc, alzip, freearc, ...) senza processi esterni. - DIE (Detect It Easy) — motore a firme; lo specialista per installer, PE e SFX.
- binwalk — chiavi di tipo brevi (cpio, lzma, ...) e contenuti incorporati.
- Magika — il rilevatore di content-type basato su AI di Google, come catch-all.
Ogni rilevatore contribuisce in modo unico (sono complementari, non ridondanti): il database delle firme identifica gli archiviatori che i motori non rilevano, DIE gestisce installer/PE, binwalk intercetta alcuni tipi che gli altri non rilevano, puremagic/Magika coprono il MIME.
PureMagic 2.x fornisce anche una scansione approfondita consapevole del contenuto quando riceve il file
completo. 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 approfondita.
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 opzionale
data/extra_detections.json sovrapposto). TrID non viene utilizzato.
Nota: qualsiasi formato la cui firma manca dal
magic_data.jsondi puremagic (o che puremagic segnala solo come genericoapplication/octet-stream) deve dichiarare una voce personalizzatadetection_signatures()nel proprio handler — altrimenti non verrà rilevato in base al contenuto.
--bruteforcedisabilita l'early-exit: ogni rilevatore viene eseguito e ogni handler rilevato viene provato a turno (utile quando la prima ipotesi è sbagliata).- Gli eseguibili ricevono anche gli handler SFX e installer (RAR, ACE, ARC, KGB, UHARC, Inno Setup, BitRock, Clickteam) come candidati di fallback; ognuno rifiuta i file che non sono propri, così la catena passa al successivo.
- Il sottocomando
carveutilizza inoltre la mappa degli offset di binwalk per estrarre archivi incorporati a offset arbitrari (ad esempio all'interno di immagini firmware).
La mappa di routing rilevamento → handler si trova in data/handlers.json (generata, caricata
a runtime). Una chiave può mappare a più handler, provati in ordine finché uno non riesce:
ad esempio prima 7-Zip, poi 7-Zip ZS per ciò che il 7-Zip principale non riesce ad aprire (SquashFS con
LZ4, NSIS con ZSTD). 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, consulta docs/adding-a-handler.md — la guida end-to-end (classe handler, dichiarazione di rilevamento, lookup DIE/TrID, firme magiche, rigenerazione dei dati di routing, bundling 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 superiore.
git clone <repo-url>
cd magic-extractor
pip install -r src/cli/requirements.txt
Utilizzo
Magic Extractor utilizza i sottocomandi:
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)
Un percorso semplice senza sottocomando assume per impostazione predefinita extract (retrocompatibile), e
le opzioni possono precedere il percorso o il sottocomando:
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 funzionano con ogni sottocomando; --password con
extract, list e carve.
<path> può essere una cartella per ogni sottocomando: i suoi file (non le sottocartelle) vengono
elaborati uno per uno. Ogni file ottiene la propria cartella di output: <stem>_extracted
(accanto al file, oppure sotto output_dir quando specificato), o <name>_extracted quando
due file condividono lo stesso stem.
Se la cartella di output contiene già dei file, extract scrive in una nuova
<folder>_<YYYYmmdd-HHMMSS> invece di mescolarsi con o sovrascrivere il risultato
precedente; --merge-output estrae invece nella cartella esistente, sovrascrivendo
file e cartelle con gli stessi nomi (la GUI lo fa quando la destinazione è
bloccata). L'archivio in fase di estrazione non viene mai sovrascritto. Ogni tentativo di handler
viene eseguito nella propria cartella temporanea, così un tentativo fallito non lascia mai file parziali
in giro.