ZombieGuard

Un scanner défensif pour le contournement des métadonnées structurelles dans les archives ZIP.

ZombieGuard détecte les contradictions entre les en-têtes de fichiers locaux ZIP, les enregistrements du répertoire central et les caractéristiques des charges utiles. Ces contradictions peuvent être utilisées pour faire apparaître le contenu d'une archive comme vide ou inoffensif pour un analyseur tandis qu'un autre analyseur atteint toujours la charge utile.

Il combine un analyseur ZIP borné avec un petit modèle LightGBM. Il n'extrait ni n'exécute le contenu des archives.

[!IMPORTANT] ZombieGuard détecte des signaux de contournement d'archive, pas des logiciels malveillants. Un résultat propre ne prouve pas que les fichiers contenus dans une archive sont sûrs.

Démarrage rapide en 60 secondes

ZombieGuard prend en charge Python 3.11 et 3.12.

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

Le modèle de version est installé avec le paquet. Utilisez zombieguard scan --help pour la limite de taille d'entrée, la sortie JSON/SARIF et les options d'analyse de répertoire.

Pour le développement, installez le dépôt en mode éditable :

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

Ce qu'il vérifie

ZombieGuard traite chaque ZIP comme un problème de cohérence plutôt que de rechercher des signatures de logiciels malveillants :

• accord entre l'en-tête de fichier local et le répertoire central ;
• cohérence de la méthode de compression, de la taille, du décalage et du CRC ;
• compression déclarée par rapport à l'entropie de la charge utile ;
• structures malformées, tronquées, chiffrées et non prises en charge ;
• comportement suspect sur l'ensemble des entrées et non seulement sur la première entrée.

Le scanner rapporte un verdict accompagné de codes de raison justificatifs. Les échecs d'analyse sont signalés comme des conditions indéterminées ou suspectes ; ils ne sont jamais silencieusement convertis en résultat propre.

Architecture

Octets ZIP non fiables
       │
       ▼
Analyseur structurel borné ──► échecs explicites d'analyse/de limite
       │
       ▼
Caractéristiques de cohérence par entrée
       │
       ▼
Modèle LightGBM versionné
       │
       ▼
verdict + score + raisons

Les erreurs de validation structurelle produisent un résultat explicite non analysable. Les archives analysées avec succès sont notées par le modèle, et les incohérences observées sont renvoyées comme codes de raison. Les métadonnées du modèle enregistrent le schéma des caractéristiques, la configuration d'entraînement, les hachages des sources et la somme de contrôle du modèle.

Évaluation vérifiée

L'évaluation de la version est volontairement étroite et reproductible. Elle ne prétend pas à la détection de logiciels malveillants dans le monde réel ni à une généralisation multi-formats.

L'artefact actuel rapporte :

La matrice de confusion est TN=1 565, FP=3, FN=0, TP=1 150. Les résultats faisant autorité se trouvent dans artifacts/metrics.json ; ce fichier contient également les résumés par pli et par variante, les hachages des sources de données, les assertions de fuite, la somme de contrôle du modèle et la configuration exacte. Si une métrique est utilisée dans un CV, un article ou une présentation, citez sa portée comme évaluation de caractéristiques synthétiques imbriquées avec exclusion d'une variante par pli.

Les lignes négatives comprennent 686 lignes de caractéristiques dérivées de PyPI, 478 négatives difficiles générées, 400 petites bénignes générées et 4 lignes de caractéristiques dérivées d'Office. Les familles de sources négatives sont réparties entre les plis plutôt que retenues en tant que familles. Les intervalles décrivent l'incertitude au niveau des lignes dans ce benchmark ; ils n'estiment ni l'incertitude de déploiement ni le décalage de domaine. La sortie LightGBM est rapportée comme un score non calibré, pas comme une probabilité. La politique de seuil est un point de fonctionnement de développement évalué avec des plis imbriqués ; de nouvelles archives bénignes analysées par la version actuelle restent nécessaires avant de considérer le taux de faux positifs mesuré comme une preuve en production.

Pourquoi utiliser des positifs synthétiques ? Les exemples publics et vérifiés de manière indépendante de cette technique étroite de contournement sont rares. La génération rend chaque mutation structurelle explicite et reproductible. La performance synthétique prouve que le détecteur reconnaît ces mutations ; elle ne remplace pas un benchmark du monde réel étiqueté de manière indépendante.

Consultez la fiche de données et la fiche de modèle pour la provenance, la sémantique des étiquettes et les modes de défaillance.

Reproduire la version

Installez les dépendances principales et vérifiez les artefacts validés. Les étapes supplémentaires de génération et d'actualisation reproduisent tous les positifs synthétiques sûrs et confirment que leurs caractéristiques validées correspondent toujours à l'analyseur actuel avant le réentraînement :

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

L'entraînement lit les tables de caractéristiques et d'étiquettes validées et écrit :

• src/zombieguard/assets/zombieguard_lgbm.txt — modèle LightGBM portable ;
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — schéma et métadonnées d'intégrité ;
• artifacts/metrics.json — rapport d'évaluation lisible par machine.

L'intégration continue exécute le linting, l'audit de sécurité des dépendances et statique, la compilation en octets, les tests avec couverture, les constructions de paquets sur Python 3.11 et 3.12, l'alignement générateur/analyseur, la vérification des artefacts validés et un test fumée isolé d'entraînement et de vérification.

Structure du dépôt

src/zombieguard/        paquet scanner installable et ressources de version
tests/                  tests unitaires, adversariaux et CLI autonomes
data/processed/         table de caractéristiques et étiquettes validées
data/scripts/           générateurs de données synthétiques sûrs
scripts/                aides à la curation et à l'audit des jeux de données
artifacts/metrics.json  métriques de version reproductibles
docs/                   fiches de données et de modèle

Les logiciels malveillants bruts, les corpus téléchargés, les identifiants et les modèles d'essai entraînés localement ne font pas partie du dépôt.

Portée et limites

• ZIP est le seul format d'archive pris en charge. Les performances sur RAR, 7z, APK et JAR ne sont pas revendiquées.
• Le modèle est entraîné sur des variantes de contournement générées et des lignes de caractéristiques bénignes étiquetées. De nouveaux écarts d'analyseurs peuvent ne pas correspondre à la distribution de caractéristiques apprise.
• Le contenu chiffré ne peut pas être inspecté. La récursivité de répertoire découvre les fichiers ZIP dans les dossiers imbriqués ; elle n'analyse pas les archives contenues dans d'autres archives.
• Les résultats doivent alimenter un flux de quarantaine ou de revue, et non remplacer un moteur antivirus, un bac à sable, un scanner de contenu ou un analyste humain.
• Les archives adversariales peuvent consommer de la mémoire ou du CPU. Conservez la limite d'entrée --max-size-mb activée et ajoutez des limites de mémoire et de temps au niveau du processus dans les déploiements en production.

Contribution et sécurité

Lisez CONTRIBUTING.md avant de modifier l'analyseur, le jeu de données ou le protocole d'évaluation. Ne validez pas d'échantillons de logiciels malveillants, d'identifiants API ou d'affirmations de benchmark sans artefact reproductible.

Pour signaler une vulnérabilité ou un contournement de l'analyseur, suivez SECURITY.md. Merci de ne pas joindre de logiciels malveillants actifs à un ticket public.

Licence

Sous licence Apache 2.0.

Fiche de données · Fiche de modèle · Politique de sécurité · Contribuer · CI