mdshoaibuddinchanda/zombieguardML-basierte Erkennung von Zombie-ZIP-Archiv-Header-Umgehungsangriffen (CVE-2026-0866)
# ZombieGuard
**Ein defensiver Scanner für strukturelle Metadaten-Umgehung in ZIP-Archiven.**
[](https://github.com/mdshoaibuddinchanda/zombieguard/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
[](#scope-and-limitations)
ZombieGuard erkennt Widersprüche zwischen lokalen ZIP-Dateiköpfen, Central-Directory-Einträgen
und Payload-Eigenschaften. Diese Widersprüche können genutzt werden, um Archivinhalte für einen
Parser leer oder harmlos erscheinen zu lassen, während ein anderer Parser die Payload weiterhin
erreicht.
Es kombiniert einen begrenzten ZIP-Parser mit einem kleinen LightGBM-Modell. Es extrahiert keine Archivinhalte und führt sie nicht aus.
> [!IMPORTANT]
> ZombieGuard erkennt Signale für Archiv-Umgehung, nicht Malware. Ein sauberes Ergebnis ist
> kein Beweis dafür, dass die Dateien in einem Archiv sicher sind.
## 60-Sekunden-Schnellstart
ZombieGuard unterstützt Python 3.11 und 3.12.
```bash
git clone https://github.com/mdshoaibuddinchanda/zombieguard.git
cd zombieguard
python -m pip install .
zombieguard scan suspicious.zip --include-features
```
Das Release-Modell wird zusammen mit dem Paket installiert. Verwenden Sie `zombieguard scan --help` für das
Eingabegrößenlimit, die JSON/SARIF-Ausgabe und die Optionen zum Scannen von Verzeichnissen.
Für die Entwicklung installieren Sie das Repository im bearbeitbaren Modus:
```bash
python -m pip install -e ".[dev]"
python -m pytest
```
## Was geprüft wird
ZombieGuard behandelt jedes ZIP als Konsistenzproblem, anstatt nach Malware-Signaturen zu suchen:
- Übereinstimmung zwischen Local-File-Header und Central Directory;
- Konsistenz von Kompressionsmethode, Größe, Offset und CRC;
- deklarierte Kompression im Vergleich zur Payload-Entropie;
- fehlerhafte, abgeschnittene, verschlüsselte und nicht unterstützte Strukturen;
- verdächtiges Verhalten über alle Einträge hinweg statt nur beim ersten Eintrag.
Der Scanner meldet einen Befund mit unterstützenden Begründungscodes. Parsing-Fehler werden
als unbestimmbar oder verdächtig gemeldet; sie werden niemals stillschweigend in ein sauberes
Ergebnis umgewandelt.
## Architektur
```text
Untrusted ZIP bytes
│
▼
Bounded structural parser ──► explicit parse/limit failures
│
▼
Per-entry consistency features
│
▼
Versioned LightGBM model
│
▼
verdict + score + reasons
```
Strukturvalidierungsfehler erzeugen ein explizites, nicht scannbares Ergebnis. Erfolgreich geparste
Archive werden vom Modell bewertet und beobachtete Inkonsistenzen als Begründungscodes zurückgegeben.
Die Modellmetadaten erfassen das Feature-Schema, die Trainingskonfiguration, Quell-Hashes und die
Modellprüfsumme.
## Verifizierte Evaluierung
Die Release-Evaluierung ist bewusst eng gefasst und reproduzierbar. Sie erhebt **keinen** Anspruch
auf Malware-Erkennung in der Praxis oder auf Generalisierung über Formate hinweg.
| Eigenschaft | Release-Protokoll |
|---|---|
| Umfang | Feature-Benchmark für synthetisch-positive ZIP-Strukturumgehung |
| Zulässiger Korpus | 1,150 generierte Positivfälle und 1,568 deduplizierte, als gutartig gekennzeichnete Feature-Zeilen |
| Positiv-Holdout | Eine vollständige Angriffsvariante pro Fold ausgelassen (8 Varianten) |
| Gutartig-Holdout | Deterministische SHA-256-Aufteilung; jede Stichprobe wird genau einmal ausgewertet |
| Entscheidungsschwelle | Verschachtelte gruppierte Kalibrierung nur auf äußeren Trainingszeilen; 0.5% Budget für gutartige FPR |
| Gemeldete Vorhersagen | Nur Vorhersagen der äußeren Folds; zurückgehaltene Zeilen legen ihre Schwelle nie selbst fest |
| Von den Angaben ausgeschlossen | Von MalwareBazaar abgeleitete und anderweitig nicht verifizierte Positiv-Labels |
| Konfidenz | Wilson-95-%-Intervalle zusammen mit aggregierten Metriken |
Das aktuelle Artefakt weist aus:
| Metrik | Ergebnis | 95-%-Wilson-Intervall |
|---|---:|---:|
| Accuracy | 99.89% (2,715 / 2,718) | 99.68–99.96% |
| Precision | 99.74% | 99.24–99.91% |
| Recall | 100% (1,150 / 1,150) | 99.67–100% |
| F1 | 99.87% | — |
| ROC-AUC | 99.90% | — |
| False-Positive-Rate | 0.191% (3 / 1,568) | 0.065–0.561% |
Die Konfusionsmatrix lautet TN=1,565, FP=3, FN=0, TP=1,150. Die maßgeblichen Ergebnisse finden sich in
[artifacts/metrics.json](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/artifacts/metrics.json); diese Datei enthält außerdem Fold-Zusammenfassungen pro Variante,
Hashes der Datenquellen, Leakage-Prüfungen, die Modellprüfsumme und die exakte Konfiguration. Wenn eine Metrik
in einem Lebenslauf, Paper oder einer Präsentation verwendet wird, geben Sie ihren Geltungsbereich als **synthetische
verschachtelte Leave-One-Variant-Out-Feature-Evaluierung** an.
Die negativen Zeilen umfassen 686 von PyPI abgeleitete, 478 generierte Hard-Negative-, 400 generierte
Small-Benign- und 4 von Office abgeleitete Feature-Zeilen. Negative Quellfamilien werden über die Folds
verteilt und nicht als Familien zurückgehalten. Die Intervalle beschreiben die Unsicherheit auf Zeilenebene
innerhalb dieses Benchmarks; sie schätzen weder die Bereitstellungsunsicherheit noch Domain-Shift.
Die LightGBM-Ausgabe wird als unkalibrierter Score berichtet, nicht als Wahrscheinlichkeit.
Die Schwellenwertstrategie ist ein Entwicklungs-Arbeitspunkt, der mit verschachtelten Folds evaluiert wird;
frische gutartige Archive, die mit der aktuellen Version geparst werden, sind weiterhin erforderlich, bevor
die gemessene False-Positive-Rate als Produktionsbeleg behandelt wird.
Warum synthetische Positivfälle verwenden? Öffentliche, unabhängig verifizierte Beispiele dieser eng umrissenen
Umgehungstechnik sind rar. Die Generierung macht jede strukturelle Mutation explizit und wiederholbar.
Synthetische Leistung ist ein Beleg dafür, dass der Detektor diese Mutationen erkennt; sie ist kein Ersatz
für einen unabhängig annotierten Realwelt-Benchmark.
Siehe [Datenkarte](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/docs/DATA_CARD.md) und [Modellkarte](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/docs/MODEL_CARD.md) für Herkunft, Label-Semantik und Fehlermodi.
## Release reproduzieren
Installieren Sie die Kernabhängigkeiten und verifizieren Sie die eingecheckten Artefakte. Die zusätzlichen
Generierungs- und Aktualisierungsschritte reproduzieren alle sicheren synthetischen Positivfälle und bestätigen,
bevor neu trainiert wird, dass ihre eingecheckten Features weiterhin mit dem aktuellen Parser übereinstimmen:
```bash
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
```
Das Training liest die eingecheckten Feature- und Label-Tabellen und schreibt:
- `src/zombieguard/assets/zombieguard_lgbm.txt` — portables LightGBM-Modell;
- `src/zombieguard/assets/zombieguard_lgbm.metadata.json` — Schema- und Integritätsmetadaten;
- `artifacts/metrics.json` — maschinenlesbarer Evaluierungsbericht.
Die kontinuierliche Integration führt Linting, Abhängigkeits- und statische Sicherheitsaudits, Byte-Kompilierung,
Tests mit Abdeckung, Paket-Builds unter Python 3.11 und 3.12, Generator-Parser-Abgleich, Verifizierung
eingecheckter Artefakte und einen isolierten Train-and-Check-Smoke-Test durch.
## Repository-Struktur
```text
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
```
Rohe Malware, heruntergeladene Korpora, Anmeldedaten und lokal trainierte Wegwerfmodelle sind nicht Teil des Repositorys.
## Umfang und Einschränkungen
- ZIP ist das einzige unterstützte Archivformat. Für RAR, 7z, APK und JAR wird keine Leistung beansprucht.
- Das Modell wird mit generierten Umgehungsvarianten und gutartig gekennzeichneten Feature-Zeilen trainiert. Neuartige Parser-Unterschiede entsprechen möglicherweise nicht der gelernten Feature-Verteilung.
- Verschlüsselte Inhalte können nicht untersucht werden. Die Verzeichnisrekursion findet ZIP-Dateien in verschachtelten Ordnern; sie scannt keine Archive, die in anderen Archiven eingebettet sind.
- Ergebnisse sollten in einen Quarantäne- oder Prüf-Workflow einfließen und keine Antiviren-Engine, Sandbox, keinen Inhalts-Scanner und keinen menschlichen Analysten ersetzen.
- Adversariale Archive können Speicher oder CPU verbrauchen. Lassen Sie das Eingabelimit `--max-size-mb` aktiviert und fügen Sie in Produktionsumgebungen Speicher- und Zeitlimits auf Prozessebene hinzu.
## Mitwirken und Sicherheit
Lesen Sie [CONTRIBUTING.md](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/CONTRIBUTING.md), bevor Sie den Parser, den Datensatz oder das Evaluierungsprotokoll ändern.
Committen Sie keine Malware-Exemplare, API-Anmeldedaten oder Benchmark-Angaben ohne ein reproduzierbares Artefakt.
Für einen Schwachstellen- oder Parser-Bypass-Bericht folgen Sie [SECURITY.md](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/SECURITY.md). Bitte hängen Sie keine
echten Malware-Exemplare an ein öffentliches Issue an.
## Lizenz
Lizenziert unter der [Apache License 2.0](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/LICENSE).
---
[Datenkarte](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/docs/DATA_CARD.md) · [Modellkarte](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/docs/MODEL_CARD.md) ·
[Sicherheitsrichtlinie](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/SECURITY.md) · [Mitwirken](https://github.com/mdshoaibuddinchanda/zombieguard/blob/main/CONTRIBUTING.md) ·
[CI](https://github.com/mdshoaibuddinchanda/zombieguard/actions/workflows/ci.yml)