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.