ZombieGuard

Un escáner defensivo para la evasión de metadatos estructurales en archivos ZIP.

ZombieGuard detecta contradicciones entre los encabezados de archivos locales ZIP, los registros del directorio central y las características de la carga útil. Estas contradicciones pueden utilizarse para hacer que el contenido de un archivo comprimido parezca vacío o inofensivo para un analizador, mientras que otro analizador sigue accediendo a la carga útil.

Combina un analizador ZIP acotado con un pequeño modelo LightGBM. No extrae ni ejecuta el contenido del archivo comprimido.

[!IMPORTANT] ZombieGuard detecta señales de evasión en archivos comprimidos, no malware. Un resultado limpio no es prueba de que los archivos dentro de un archivo comprimido sean seguros.

Inicio rápido en 60 segundos

ZombieGuard es compatible con Python 3.11 y 3.12.

git clone https://github.com/mdshoaibuddinchanda/zombieguard.git
cd zombieguard
python -m pip install .
zombieguard scan suspicious.zip --include-features

El modelo de la versión se instala con el paquete. Use zombieguard scan --help para conocer el límite de tamaño de entrada, la salida JSON/SARIF y las opciones de escaneo de directorios.

Para desarrollo, instale el repositorio en modo editable:

python -m pip install -e ".[dev]"
python -m pytest

Qué comprueba

ZombieGuard trata cada ZIP como un problema de coherencia en lugar de buscar firmas de malware:

• concordancia entre el encabezado de archivo local y el directorio central;
• coherencia del método de compresión, tamaño, offset y CRC;
• compresión declarada frente a entropía de la carga útil;
• estructuras malformadas, truncadas, cifradas y no admitidas;
• comportamiento sospechoso en todas las entradas y no solo en la primera.

El escáner emite un veredicto con códigos de motivo de respaldo. Los fallos de análisis se notifican como condiciones indeterminadas o sospechosas; nunca se convierten silenciosamente en un resultado limpio.

Arquitectura

Untrusted ZIP bytes
       │
       ▼
Bounded structural parser ──► explicit parse/limit failures
       │
       ▼
Per-entry consistency features
       │
       ▼
Versioned LightGBM model
       │
       ▼
verdict + score + reasons

Los errores de validación estructural producen un resultado explícito de no escaneable. Los archivos comprimidos analizados correctamente reciben una puntuación del modelo y las incoherencias observadas se devuelven como códigos de motivo. Los metadatos del modelo registran el esquema de características, la configuración de entrenamiento, los hashes de origen y la suma de verificación del modelo.

Evaluación verificada

La evaluación de la versión es deliberadamente acotada y reproducible. No pretende detección de malware en el mundo real ni generalización entre formatos.

El artefacto actual informa:

La matriz de confusión es TN=1,565, FP=3, FN=0, TP=1,150. Los resultados de referencia se encuentran en artifacts/metrics.json; ese archivo también contiene resúmenes de pliegues por variante, hashes de las fuentes de datos, afirmaciones de fuga de datos, suma de verificación del modelo y la configuración exacta. Si se utiliza una métrica en un currículum, artículo o presentación, cite su alcance como evaluación sintética anidada de características con exclusión de una variante.

Las filas negativas comprenden 686 filas de características derivadas de PyPI, 478 negativas difíciles generadas, 400 benignas de pequeño tamaño generadas y 4 derivadas de Office. Las familias de fuentes negativas se distribuyen entre los pliegues en lugar de reservarse como familias. Los intervalos describen la incertidumbre a nivel de fila dentro de este benchmark; no estiman la incertidumbre de despliegue ni el cambio de dominio. La salida de LightGBM se notifica como una puntuación no calibrada, no como una probabilidad. La política de umbral es un punto de operación de desarrollo evaluado con pliegues anidados; aún se requieren archivos comprimidos benignos nuevos analizados por la versión actual antes de tratar su tasa de falsos positivos medida como evidencia de producción.

¿Por qué usar positivos sintéticos? Los ejemplos públicos e independientemente verificados de esta técnica de evasión específica son escasos. La generación hace que cada mutación estructural sea explícita y repetible. El rendimiento sintético es evidencia de que el detector reconoce esas mutaciones; no sustituye a un benchmark del mundo real etiquetado de forma independiente.

Consulte la ficha de datos y la ficha del modelo para conocer la procedencia, la semántica de las etiquetas y los modos de fallo.

Reproducir la versión

Instale las dependencias principales y verifique los artefactos confirmados. Los pasos adicionales de generación y actualización reproducen todos los positivos sintéticos seguros y confirman que sus características confirmadas siguen coincidiendo con el analizador actual antes de volver a entrenar:

python -m pip install -e .
python -m zombieguard.evaluate --check
python data/scripts/generate_zombie_samples.py
python scripts/refresh_synthetic_features.py
python -m zombieguard.evaluate --train --check

El entrenamiento lee las tablas de características y etiquetas confirmadas y escribe:

• src/zombieguard/assets/zombieguard_lgbm.txt — modelo LightGBM portátil;
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — metadatos de esquema e integridad;
• artifacts/metrics.json — informe de evaluación legible por máquina.

La integración continua ejecuta linting, auditoría de dependencias y seguridad estática, compilación a bytecode, pruebas con cobertura, compilación de paquetes en Python 3.11 y 3.12, alineación generador/analizador, verificación de artefactos confirmados y una prueba de humo aislada de entrenamiento y verificación.

Estructura del repositorio

src/zombieguard/        installable scanner package and release assets
tests/                  self-contained unit, adversarial, and CLI tests
data/processed/         committed feature table and labels
data/scripts/           safe synthetic-data builders
scripts/                dataset curation and audit helpers
artifacts/metrics.json  reproducible release metrics
docs/                   data and model cards

El malware sin procesar, los corpus descargados, las credenciales y los modelos de prueba entrenados localmente no forman parte del repositorio.

Alcance y limitaciones

• ZIP es el único formato de archivo comprimido compatible. No se afirma rendimiento con RAR, 7z, APK ni JAR.
• El modelo se entrena con variantes de evasión generadas y filas de características etiquetadas como benignas. Las diferencias novedosas de analizadores pueden no coincidir con la distribución de características aprendida.
• El contenido cifrado no se puede inspeccionar. La recursión de directorios descubre archivos ZIP en carpetas anidadas; no escanea archivos comprimidos incrustados dentro de otros archivos comprimidos.
• Los resultados deben alimentar un flujo de trabajo de cuarentena o revisión, no reemplazar un motor antivirus, un sandbox, un escáner de contenido ni un analista humano.
• Los archivos adversariales pueden consumir memoria o CPU. Mantenga habilitado el límite de entrada --max-size-mb y añada límites de memoria y tiempo a nivel de proceso en los despliegues de producción.

Contribuciones y seguridad

Lea CONTRIBUTING.md antes de modificar el analizador, el conjunto de datos o el protocolo de evaluación. No confirme muestras de malware, credenciales de API ni afirmaciones de benchmark sin un artefacto reproducible.

Para informar de una vulnerabilidad o de un bypass del analizador, siga SECURITY.md. No adjunte malware activo a una incidencia pública.

Licencia

Con licencia Apache License 2.0.

Ficha de datos · Ficha del modelo · Política de seguridad · Contribuciones · CI