ZombieGuard

Uno scanner difensivo per l'evasione dei metadati strutturali negli archivi ZIP.

ZombieGuard rileva contraddizioni tra le intestazioni locali dei file ZIP, i record della directory centrale e le caratteristiche del payload. Queste contraddizioni possono essere usate per far apparire i contenuti dell'archivio vuoti o innocui a un parser mentre un altro parser raggiunge comunque il payload.

Combina un parser ZIP vincolato con un piccolo modello LightGBM. Non estrae né esegue il contenuto degli archivi.

[!IMPORTANT] ZombieGuard rileva segnali di evasione degli archivi, non malware. Un risultato pulito non è la prova che i file all'interno di un archivio siano sicuri.

Avvio rapido in 60 secondi

ZombieGuard supporta Python 3.11 e 3.12.

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

Il modello di rilascio viene installato insieme al pacchetto. Usa zombieguard scan --help per il limite di dimensione dell'input, l'output JSON/SARIF e le opzioni di scansione delle directory.

Per lo sviluppo, installa il repository in modalità modificabile:

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

Cosa controlla

ZombieGuard tratta ogni ZIP come un problema di coerenza invece di cercare firme di malware:

• concordanza tra intestazione locale del file e directory centrale;
• coerenza di metodo di compressione, dimensione, offset e CRC;
• compressione dichiarata rispetto all'entropia del payload;
• strutture malformate, troncate, crittografate e non supportate;
• comportamento sospetto su tutte le voci, non solo sulla prima.

Lo scanner restituisce un verdetto con i relativi codici di motivazione. I fallimenti di parsing vengono segnalati come condizioni indeterminate o sospette; non vengono mai convertiti silenziosamente in un risultato pulito.

Architettura

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

Gli errori di validazione strutturale producono un risultato esplicito di non scansionabilità. Gli archivi parsati correttamente vengono valutati dal modello e le incongruenze osservate vengono restituite come codici di motivazione. I metadati del modello registrano lo schema delle feature, la configurazione di addestramento, gli hash delle sorgenti e il checksum del modello.

Valutazione verificata

La valutazione di rilascio è volutamente ristretta e riproducibile. Non pretende la rilevazione di malware nel mondo reale né la generalizzazione tra formati.

L'artefatto corrente riporta:

La matrice di confusione è TN=1.565, FP=3, FN=0, TP=1.150. I risultati di riferimento sono artifacts/metrics.json; quel file contiene anche i riepiloghi dei fold per variante, gli hash delle sorgenti dati, le asserzioni di leakage, il checksum del modello e la configurazione esatta. Se una metrica viene usata in un curriculum, in un articolo o in una presentazione, citane l'ambito come valutazione sintetica annidata delle feature con esclusione di una variante per fold.

Le righe negative comprendono 686 righe di feature derivate da PyPI, 478 hard-negative generate, 400 piccole benigne generate e 4 derivate da Office. Le famiglie di origine negative sono distribuite tra i fold piuttosto che escluse come famiglie. Gli intervalli descrivono l'incertezza a livello di riga all'interno di questo benchmark; non stimano l'incertezza di deployment né il domain shift. L'output di LightGBM viene riportato come punteggio non calibrato, non come probabilità. La politica di soglia è un punto operativo di sviluppo valutato con fold annidati; servono ancora archivi benigni nuovi parsati dalla versione corrente prima di considerare il tasso di falsi positivi misurato come evidenza in produzione.

Perché usare positivi sintetici? Gli esempi pubblici e verificati in modo indipendente di questa tecnica di evasione specifica sono scarsi. La generazione rende ogni mutazione strutturale esplicita e ripetibile. Le prestazioni sintetiche sono la prova che il rilevatore riconosce quelle mutazioni; non sostituiscono un benchmark reale con etichette indipendenti.

Consulta la data card e la model card per provenienza, semantica delle etichette e modalità di errore.

Riprodurre il rilascio

Installa le dipendenze principali e verifica gli artefatti committati. I passaggi aggiuntivi di generazione e aggiornamento riproducono tutti i positivi sintetici sicuri e confermano che le feature committate corrispondono ancora al parser attuale prima del riaddestramento:

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'addestramento legge le tabelle di feature ed etichette committate e scrive:

• src/zombieguard/assets/zombieguard_lgbm.txt — modello LightGBM portabile;
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — schema e metadati di integrità;
• artifacts/metrics.json — report di valutazione leggibile da macchina.

L'integrazione continua esegue linting, audit delle dipendenze e della sicurezza statica, compilazione in bytecode, test con copertura, build dei pacchetti su Python 3.11 e 3.12, allineamento generatore/parser, verifica degli artefatti committati e uno smoke test isolato di addestramento e verifica.

Struttura del repository

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

Malware grezzi, corpora scaricati, credenziali e modelli di prova addestrati localmente non fanno parte del repository.

Ambito e limitazioni

• ZIP è l'unico formato di archivio supportato. Le prestazioni su RAR, 7z, APK e JAR non sono dichiarate.
• Il modello è addestrato su varianti di evasione generate e righe di feature con etichetta benigna. Nuovi differenziali di parser potrebbero non corrispondere alla distribuzione delle feature apprese.
• Il contenuto crittografato non può essere ispezionato. La ricorsione delle directory individua i file ZIP nelle cartelle annidate; non scansiona archivi incorporati all'interno di altri archivi.
• I risultati dovrebbero alimentare un flusso di lavoro di quarantena o revisione, non sostituire un motore antivirus, una sandbox, uno scanner di contenuti o un analista umano.
• Gli archivi avversari possono consumare memoria o CPU. Mantieni abilitato il limite massimo di input --max-size-mb e aggiungi limiti di memoria e tempo a livello di processo nelle distribuzioni in produzione.

Contributi e sicurezza

Leggi CONTRIBUTING.md prima di modificare il parser, il dataset o il protocollo di valutazione. Non committare campioni di malware, credenziali API o affermazioni di benchmark senza un artefatto riproducibile.

Per una segnalazione di vulnerabilità o bypass del parser, segui SECURITY.md. Non allegare malware reali a un issue pubblico.

Licenza

Concesso in licenza con Apache License 2.0.

Data card · Model card · Politica di sicurezza · Contributi · CI