Magic Extractor

Beschreibung

Magic Extractor ist ein universelles Extraktionswerkzeug für Windows, das eine Datei mithilfe mehrerer Detektoren identifiziert und an den richtigen gebündelten Extraktor weiterleitet. Es zielt darauf ab, gängige Komprimierungsformate, die heute tatsächlich vorkommenden Installer und eine Reihe weniger verbreiteter Archivierer abzudecken.

Es erkennt automatisch 80+ Formate — Archive, Installer, Festplatten-Images, Forensik-Images (EWF/AFF/AD1), Disc-Images, Mail-Stores und moderne Codecs. Die vollständige Liste finden Sie in formats.md.

Schnellstart

Laden Sie das neueste Release herunter, entpacken Sie es und führen Sie Folgendes aus:

magic-extractor.exe extract mystery.bin

Beispiele für identify, list, carve, --recursive und --bruteforce finden Sie unter Beispiele.

Projektstruktur

• cli: Quellcode.
  • bin: gebündelte Detektor- und Extraktor-Binaries.
    • detectors: DIE, Magika, binwalk (die TrID-Definitionen werden in data/signatures.json konvertiert).
    • extractors: 7z, unrar, unace, unshield, lessmsi, dark (WiX) und weitere.
  • data: Laufzeitkonfiguration, dynamisch geladen (siehe unten).
  • formats: ein Handler-Modul pro Formatfamilie.
• gui: optionales tkinter-Frontend, das die CLI kapselt (siehe GUI).
• test: Beispieldateien pro Format (Fixtures für die Extraktions-/Erkennungstests).
• tools: Entwicklerwerkzeuge (generate_data.py — erstellt die Datendateien aus den Handlern).

Der kompilierte Build hält bin/, data/ und config.ini außerhalb der exe, sodass sie per Dateiaustausch aktualisiert werden können; der Pfad-Resolver in main.py findet sie neben der ausführbaren Datei (frozen) oder unter cli/ (Entwicklung).

So funktioniert die Erkennung

Für die normale Extraktion laufen die Detektoren in dieser Reihenfolge mit Early-Exit — der erste, der einen bekannten Handler liefert, gewinnt (zuerst die kostengünstigsten, sodass das ML-Modell normalerweise übersprungen wird):

1. puremagic — Pure-Python, kein Subprozess; ein kostengünstiger MIME-Check für wohlgeformte Archive.
2. Eingebaute Signaturen — Magic-Byte-Muster in data/signatures.json; benennt Archivierer, die die Engines übersehen (bcm, dgca, kgb, uharc, alzip, freearc, ...), ohne externen Prozess.
3. DIE (Detect It Easy) — Signatur-Engine; der Spezialist für Installer, PE und SFX.
4. binwalk — kurze Typschlüssel (cpio, lzma, ...) und eingebettete Inhalte.
5. Magika — Googles KI-Inhaltstyp-Erkenner, als Auffangnetz.

Jeder Detektor trägt auf seine eigene Weise bei (sie sind komplementär, nicht redundant): Die Signatur-Datenbank benennt Archivierer, die die Engines übersehen, DIE übernimmt Installer/PE, binwalk fängt einige Typen ab, die die anderen übersehen, und puremagic/Magika decken MIME ab.

PureMagic 2.x bietet außerdem inhaltsbewusstes Tiefenscannen, wenn es die vollständige Datei erhält. Die Analyse der gesamten Datei ist die Standardeinstellung; der optionale Modifikator --fast-check übergibt nur die ersten 64 KiB, wenn die Startgeschwindigkeit wichtiger ist als eine tiefgehende Prüfung.

Jeder Handler deklariert seine eigenen Erkennungsmerkmale über detection_mimes() / detection_names() / detection_signatures(); tools/generate_data.py kompiliert diese in data/handlers.json und data/signatures.json (optional wird data/extra_detections.json darüber gemerged). TrID wird nicht verwendet.

Hinweis: Jedes Format, dessen Signatur in puremagics magic_data.json fehlt (oder das puremagic nur als generisches application/octet-stream meldet), muss einen eigenen detection_signatures()-Eintrag in seinem Handler deklarieren — andernfalls wird es nicht anhand des Inhalts erkannt.

• --bruteforce deaktiviert den Early-Exit: Jeder Detektor läuft, und jeder erkannte Handler wird der Reihe nach ausprobiert (nützlich, wenn der erste Tipp falsch ist).
• Ausführbare Dateien, die kein Detektor identifiziert, fallen auf die Wrapped-EXE-Installer-Handler zurück (BitRock, Clickteam, Inno, ...), die sich selbst validieren.
• Der Unterbefehl carve nutzt zusätzlich binwalks Offset-Karte, um Archive zu extrahieren, die an beliebigen Offsets eingebettet sind (z. B. in Firmware-Images).

Die Routing-Tabelle für Erkennung → Handler liegt in data/handlers.json (handgepflegt, zur Laufzeit geladen); eine Blacklist generischer Token liegt in data/detection_blacklist.json.

Unterstützte Formate

Die vollständige Liste der Formate und ihrer Handler finden Sie in formats.md.

Ein Format hinzufügen

Um Unterstützung für ein neues Format hinzuzufügen, siehe docs/adding-a-handler.md — die End-to-End-Anleitung (Handler-Klasse, Erkennungsdeklaration, DIE/TrID-Lookup, Magic-Signaturen, Neuaufbau der Routingdaten, Bündelung des Tools und Tests).

Installation (aus dem Quellcode)

Die meisten Benutzer laden einfach das Release herunter (siehe Schnellstart). Zur Ausführung aus dem Quellcode ist Python 3.12 oder neuer erforderlich.

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

Verwendung

Magic Extractor verwendet Unterbefehle:

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)

Ein Pfad ohne Unterbefehl verwendet standardmäßig extract (abwärtskompatibel):

python cli/main.py <path> <output_dir> [options]

Optionen von extract:

• --password <password>: Passwort für verschlüsselte Archive.

• -r, --recursive: extrahiert Archive, die im Ausgabeordner gefunden werden (begrenzt durch --max-depth, Standard 5).

• -b, --bruteforce: probiert jeden erkannten Handler aus, statt beim ersten zu stoppen.

• --open-output-folder <true|false>: öffnet den Ausgabeordner nach Abschluss.

• --check-free-space <true|false>: warnt, wenn dem Ausgabevolume der Platz ausgehen könnte.

• --check-unicode <true|false>: warnt vor Nicht-ASCII-Namen extrahierter Dateien.

• --fix-file-extensions <true|false>: vergibt Dateien ohne Endung nach der Extraktion eine inhaltsbasierte Endung (überschreibt niemals eine vorhandene).

• --create-log-files <true|false>: schreibt ein Protokoll pro Lauf in das Ausgabeverzeichnis.

Optionen von carve: --list (gibt die binwalk-Fragmenttabelle aus), --fragment N (löst ein Fragment per Index heraus), --raw (löst jedes Fragment heraus, nicht nur handler-bekannte).

In den Beispielen unten ist magic-extractor die gebaute .exe. Bei der Ausführung aus dem Quellcode ersetzen Sie sie durch python cli/main.py — die Argumente sind identisch.

Beispiele

Ein Archiv extrahieren — Sie müssen seinen Typ nicht kennen; er wird automatisch erkannt:

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

Eine Datei identifizieren, ohne sie anzufassen — zeigt, was jeder Detektor gesehen hat und welcher Handler ausgeführt würde:

magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler

Inhalt eines Archivs auflisten (ohne Extraktion):

magic-extractor list backup.7z

Rekursiv — Archive extrahieren, die im Ausgabeordner gefunden werden (z. B. eine .tar.gz oder ein Installer, der weitere Archive enthält), bis zu --max-depth Ebenen:

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

Bruteforce — wenn die Erkennung unsicher ist, jeden gematchten Handler ausprobieren, statt beim ersten zu stoppen:

magic-extractor extract weird-archive.dat --bruteforce

Carve — Archive herauslösen, die an einem Offset in eine größere Datei eingebettet sind (klassisch bei Firmware-Images). Zuerst inspizieren, dann carven:

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

Ein optionales tkinter-Frontend (in gui/) kapselt die CLI — ein Fenster im Universal-Extractor-Stil mit den Modi extract, scan und carve, Drag-and-Drop, einer Batch-Warteschlange, einem Verlauf der ausgeführten Läufe und einem Preferences-Dialog. Bruteforce ist unter den Run-Optionen verfügbar. Es ruft dieselbe main.py auf, sodass Erkennung und Extraktion sich identisch verhalten.

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

Drag-and-Drop benötigt das optionale Paket tkinterdnd2 (pip install -r gui/requirements.txt); ohne dieses funktioniert das Fenster weiterhin, nur ohne Drop-Unterstützung. Es kann außerdem über den Preferences-Dialog einen Eintrag im Explorer-Kontextmenü registrieren.

Erstellen (Windows)

cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic

Kopieren Sie anschließend bin/, data/ und config.ini neben dist/magic-extractor.exe. CI erledigt das automatisch — siehe .github/workflows/release.yml.

Lizenz

MIT — siehe LICENSE.txt. Hinweis: Die gebündelten Binaries der Drittanbieter-Extraktoren/-Detektoren unter cli/bin/ behalten ihre eigenen Lizenzen (teils proprietäre Freeware) und sind nicht durch die MIT-Lizenz abgedeckt; prüfen Sie vor dem Vertrieb deren Weitergabebedingungen.

Autoren

• Leitender Entwickler: DSR! — [email protected]
• Dank an alle Mitwirkenden.