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>

## 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`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md).

## Schnellstart
Laden Sie das [neueste Release](../../releases/latest) herunter, entpacken Sie es und
führen Sie Folgendes aus:
```text
magic-extractor.exe extract mystery.bin
```
Beispiele für `identify`, `list`, `carve`, `--recursive` und `--bruteforce` finden Sie
unter [Beispiele](#examples).

## 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](#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`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/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](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md).

## Ein Format hinzufügen
Um Unterstützung für ein neues Format hinzuzufügen, siehe
[docs/adding-a-handler.md](https://github.com/xchwarze/magic-extractor/blob/master/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](#quick-start)).
Zur Ausführung aus dem Quellcode ist Python 3.12 oder neuer erforderlich.

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

## Verwendung
Magic Extractor verwendet Unterbefehle:
```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)
```
Ein Pfad ohne Unterbefehl verwendet standardmäßig `extract` (abwärtskompatibel):
```bash
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.

  (Jede Option verwendet standardmäßig ihren `config.ini`-Wert, wenn sie weggelassen wird; kombinieren
  Sie sie mit `--update-defaults`, um den angegebenen Wert dauerhaft zu speichern — z. B. deaktiviert
  `--open-output-folder false --update-defaults` einen zuvor gespeicherten Standardwert.)
- `--fast-check`: prüft nur die ersten 64 KiB statt einer Erkennung über die gesamte Datei.
- `--update-defaults`: speichert die angegebenen Einstellungen als Standardwerte in `config.ini`.

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:
```text
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:
```text
magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler
```

**Inhalt eines Archivs auflisten** (ohne Extraktion):
```text
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:
```text
magic-extractor extract app-1.0.tar.gz --recursive
```

**Bruteforce** — wenn die Erkennung unsicher ist, jeden gematchten Handler ausprobieren,
statt beim ersten zu stoppen:
```text
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:
```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
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.
```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
```
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)
```bash
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.