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>

## Descripción
Magic Extractor es una herramienta de extracción universal para Windows que identifica un archivo
con varios detectores y lo enruta al extractor incluido adecuado. Su objetivo es
cubrir los formatos de compresión convencionales, los instaladores que se ven hoy en día, y una
gama de archivadores menos comunes.

Detecta automáticamente **más de 80 formatos** — archivos, instaladores, imágenes de disco, imágenes
forenses (EWF/AFF/AD1), imágenes de disco óptico, almacenes de correo y códecs modernos. Consulta
[`formats.md`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) para ver la lista completa.

## Inicio rápido
Descarga la [última versión](../../releases/latest), descomprímela y ejecuta:
```text
magic-extractor.exe extract mystery.bin
```
Consulta [Ejemplos](#examples) para `identify`, `list`, `carve`, `--recursive` y `--bruteforce`.

## Estructura del proyecto
- `cli`: código fuente.
  - `bin`: binarios de detectores y extractores incluidos.
    - `detectors`: DIE, Magika, binwalk (las definiciones de TrID se convierten a `data/signatures.json`).
    - `extractors`: 7z, unrar, unace, unshield, lessmsi, dark (WiX), y más.
  - `data`: configuración en tiempo de ejecución, cargada dinámicamente (ver más abajo).
  - `formats`: un módulo de manejador por familia de formatos.
- `gui`: interfaz frontal opcional de tkinter que envuelve la CLI (ver [GUI](#gui)).
- `test`: archivos de muestra por formato (fixtures para las pruebas de extracción/detección).
- `tools`: herramientas de desarrollo (`generate_data.py` — genera los archivos de datos a partir de los manejadores).

La compilación final mantiene `bin/`, `data/` y `config.ini` fuera del exe para que
puedan actualizarse intercambiando archivos; el resolvedor de rutas en `main.py` los
encuentra junto al ejecutable (compilado) o bajo `cli/` (desarrollo).

## Cómo funciona la detección
Para la extracción normal, los detectores se ejecutan en este orden con **salida
anticipada** — gana el primero que produzca un manejador conocido (primero el menos
costoso, por lo que el modelo de ML normalmente se omite):

1. **puremagic** — python puro, sin subprocesos; una verificación MIME barata para archivos bien formados.
2. **firmas integradas** — patrones de magic bytes en `data/signatures.json`; nombra
   archivadores que los motores no detectan (bcm, dgca, kgb, uharc, alzip, freearc, ...) sin
   proceso externo.
3. **DIE** (Detect It Easy) — motor de firmas; el especialista en instaladores, PE y SFX.
4. **binwalk** — claves de tipo cortas (cpio, lzma, ...) y contenido incrustado.
5. **Magika** — el detector de tipo de contenido por IA de Google, como recurso final.

Cada detector contribuye de forma única (son complementarios, no redundantes): la
base de datos de firmas nombra archivadores que los motores no detectan, DIE se ocupa
de instaladores/PE, binwalk detecta algunos tipos que los demás no detectan, puremagic/Magika cubren MIME.

PureMagic 2.x también proporciona un escaneo profundo consciente del contenido cuando recibe el archivo
completo. El análisis de archivo completo es el predeterminado; el modificador opcional `--fast-check`
envía solo los primeros 64 KiB cuando la velocidad de inicio importa más que la inspección profunda.

Cada manejador declara sus propios indicadores mediante `detection_mimes()` /
`detection_names()` / `detection_signatures()`; `tools/generate_data.py` los compila
en `data/handlers.json` y `data/signatures.json` (con un
`data/extra_detections.json` opcional fusionado encima). TrID no se utiliza.

> Nota: cualquier formato cuya firma falte en el
> [`magic_data.json`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/magic_data.json)
> de puremagic (o que puremagic reporte solo como un `application/octet-stream` genérico) debe
> declarar una entrada `detection_signatures()` personalizada en su manejador; de lo contrario,
> no será detectado por contenido.

- `--bruteforce` desactiva la salida anticipada: cada detector se ejecuta y cada manejador
  detectado se prueba por turno (útil cuando la primera suposición es incorrecta).
- Los ejecutables que ningún detector identifica recurren a los manejadores de instaladores
  exe envueltos (BitRock, Clickteam, Inno, ...), que se autovalidan.
- El subcomando `carve` utiliza además el mapa de desplazamientos de binwalk para extraer archivos
  incrustados en desplazamientos arbitrarios (por ejemplo, dentro de imágenes de firmware).

El mapa de enrutamiento detección → manejador vive en `data/handlers.json` (curado
manualmente, cargado en tiempo de ejecución); una lista negra de tokens genéricos vive en
`data/detection_blacklist.json`.

## Formatos admitidos
Consulta [formats.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) para ver la lista completa de formatos y sus manejadores.

## Añadir un formato
Para añadir soporte para un nuevo formato, consulta
[docs/adding-a-handler.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/adding-a-handler.md), la guía de principio a fin
(clase de manejador, declaración de detección, consulta en DIE/TrID, firmas mágicas,
regeneración de los datos de enrutamiento, empaquetado de la herramienta y pruebas).

## Instalación (desde el código fuente)
La mayoría de los usuarios solo descargan la versión publicada (ver [Inicio rápido](#quick-start)). Para ejecutar desde el código fuente:
se requiere Python 3.12 o superior.

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

## Uso
Magic Extractor utiliza subcomandos:
```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)
```
Una ruta simple sin subcomando equivale a `extract` (compatible con versiones anteriores):
```bash
python cli/main.py <path> <output_dir> [options]
```

Opciones de `extract`:
- `--password <password>`: contraseña para archivos cifrados.
- `-r`, `--recursive`: extrae los archivos encontrados dentro de la salida (limitado por `--max-depth`, por defecto 5).
- `-b`, `--bruteforce`: prueba todos los manejadores detectados en lugar de detenerse en el primero.
- `--open-output-folder <true|false>`: abre la carpeta de salida al terminar.
- `--check-free-space <true|false>`: advierte si el volumen de salida podría no tener espacio.
- `--check-unicode <true|false>`: advierte sobre nombres extraídos no ASCII.
- `--fix-file-extensions <true|false>`: asigna a los archivos extraídos sin extensión una extensión basada en el contenido (nunca sobrescribe una existente).
- `--create-log-files <true|false>`: escribe un registro por ejecución en el directorio de salida.

  (Cada una toma por defecto su valor de `config.ini` cuando se omite; combínalo con
  `--update-defaults` para conservar el valor dado — p. ej. `--open-output-folder false
  --update-defaults` desactiva un valor predeterminado guardado previamente.)
- `--fast-check`: comprueba solo los primeros 64 KiB en lugar de realizar la detección de archivo completo.
- `--update-defaults`: guarda la configuración dada como predeterminada en `config.ini`.

Opciones de `carve`: `--list` (imprime la tabla de fragmentos de binwalk), `--fragment N` (extrae un
fragmento por índice), `--raw` (extrae todos los fragmentos, no solo los conocidos por el manejador).

> En los ejemplos siguientes, `magic-extractor` es el `.exe` compilado. Desde el código fuente, sustitúyelo
> por `python cli/main.py` — los argumentos son idénticos.

## Ejemplos

**Extraer un archivo** — no necesitas saber su tipo; se detecta automáticamente:
```text
magic-extractor extract mystery.bin
# extracts into mystery_extracted/ next to the file
```

**Identificar** un archivo sin tocarlo — muestra qué vio cada detector y qué
manejador se ejecutaría:
```text
magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler
```

**Listar** el contenido de un archivo (sin extracción):
```text
magic-extractor list backup.7z
```

**Recursivo** — extrae los archivos encontrados dentro de la salida (p. ej. un .tar.gz, o un
instalador que contiene más archivos), hasta `--max-depth` niveles:
```text
magic-extractor extract app-1.0.tar.gz --recursive
```

**Bruteforce** — cuando la detección no es segura, prueba todos los manejadores que coincidieron en lugar
de detenerse en el primero:
```text
magic-extractor extract weird-archive.dat --bruteforce
```

**Carve** — extrae los archivos incrustados en algún desplazamiento dentro de un archivo más grande
(clásico en imágenes de firmware). Inspecciona primero y luego extrae:
```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
Una interfaz frontal opcional de tkinter (en `gui/`) envuelve la CLI — una ventana al estilo
Universal-Extractor con modos `extract`, `scan` y `carve`, arrastrar y soltar, una cola de lotes,
historial de ejecuciones y un diálogo de Preferencias. Bruteforce está disponible en las opciones de
ejecución. Hace una llamada al mismo `main.py`, por lo que la detección y la extracción se comportan de forma idéntica.
```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
```
Arrastrar y soltar necesita el paquete opcional `tkinterdnd2` (`pip install -r gui/requirements.txt`);
sin él, la ventana sigue funcionando, excepto el soporte de soltar. También puede registrar una entrada
de menú contextual del Explorador desde su diálogo de Preferencias.

## Compilación (Windows)
```bash
cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic
```
Luego copia `bin/`, `data/` y `config.ini` junto a `dist/magic-extractor.exe`.
CI lo hace automáticamente — consulta `.github/workflows/release.yml`.

## Licencia
MIT — consulta `LICENSE.txt`. Nota: los binarios de extractores/detectores de terceros
incluidos bajo `cli/bin/` conservan sus propias licencias (algunas son freeware propietario)
y no están cubiertos por MIT; verifica sus términos de redistribución antes de distribuirlos.

## Autores
- Desarrollador principal: DSR! — [email protected]
- Gracias a todos los colaboradores.