Magic Extractor

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 para ver la lista completa.

Inicio rápido

Descarga la última versión, descomprímela y ejecuta:

magic-extractor.exe extract mystery.bin

Consulta Ejemplos 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).
• 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 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 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, 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). Para ejecutar desde el código fuente: se requiere Python 3.12 o superior.

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

Uso

Magic Extractor utiliza subcomandos:

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

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:

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:

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

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:

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:

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:

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.

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)

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.