ZombieGuard

一款用于检测 ZIP 压缩包中结构元数据规避行为的防御性扫描器。

ZombieGuard 检测 ZIP 本地文件头、中央目录记录与负载特性之间的矛盾。这些矛盾可用于让压缩包内容对一个解析器显示为空或无害，而另一个解析器仍能访问到负载。

它结合了一个有界 ZIP 解析器与一个小型 LightGBM 模型。它不会解压或执行压缩包内容。

[!IMPORTANT] ZombieGuard 检测的是压缩包规避信号，而非恶意软件。干净的结果并不能证明压缩包内的文件是安全的。

60 秒快速上手

ZombieGuard 支持 Python 3.11 和 3.12。

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

发布模型随包安装。使用 zombieguard scan --help 可查看输入大小限制、JSON/SARIF 输出以及目录扫描选项。

如需开发，请以可编辑模式安装仓库：

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

检测内容

ZombieGuard 将每个 ZIP 视为一致性问题，而不是寻找恶意软件签名：

• 本地文件头与中央目录的一致性；
• 压缩方法、大小、偏移量和 CRC 的一致性；
• 声明的压缩方式与负载熵之间的对比；
• 格式错误、截断、加密和不支持的结构；
• 对所有条目进行可疑行为检测，而不仅仅是第一个条目。

扫描器会输出判定结果及支持性原因代码。解析失败会被报告为不确定或可疑情况；绝不会静默转换为干净结果。

架构

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

结构验证错误会产生明确的“无法扫描”结果。成功解析的压缩包由模型评分，观察到的差异以原因代码形式返回。模型元数据记录了特征模式、训练配置、源哈希和模型校验和。

经核实的评估

发布评估刻意保持范围狭窄且可复现。它并不声称能够检测真实世界恶意软件或跨格式泛化。

当前制品报告如下：

混淆矩阵为 TN=1,565、FP=3、FN=0、TP=1,150。权威结果见 artifacts/metrics.json；该文件还包含按变体划分的折汇总、数据源哈希、泄漏断言、模型校验和以及精确配置。如果在简历、论文或演示文稿中引用指标，请将其范围描述为合成嵌套逐变体留出特征评估。

阴性行包括 686 个源自 PyPI、478 个生成的强阴性、400 个生成的小型良性以及 4 个源自 Office 的特征行。阴性来源族分布在各个折中，而不是整族留出。置信区间描述的是该基准内的行级不确定性；它们不估计部署不确定性或领域偏移。LightGBM 输出以未校准分数形式报告，而非概率。阈值策略是使用嵌套折评估的开发运行点；在将其测量的假阳性率视为生产环境证据之前，仍需要用当前版本解析新的良性压缩包。

为什么要使用合成阳性样本？针对这一狭窄规避技术，公开且经独立验证的实例十分稀少。生成方式使每次结构突变都明确且可重复。合成性能证明检测器能够识别这些突变；但它不能替代独立标注的真实世界基准。

有关来源、标签语义和失败模式，请参阅数据卡和模型卡。

复现发布

安装核心依赖并验证已提交的制品。额外的生成和刷新步骤可复现所有安全的合成阳性样本，并确认它们已提交的特征在重新训练前仍与当前解析器匹配：

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

训练读取已提交的特征和标签表，并写入：

• src/zombieguard/assets/zombieguard_lgbm.txt — 可移植 LightGBM 模型；
• src/zombieguard/assets/zombieguard_lgbm.metadata.json — 模式与完整性元数据；
• artifacts/metrics.json — 机器可读的评估报告。

持续集成运行代码检查、依赖项与静态安全审计、字节编译、带覆盖率的测试、Python 3.11 和 3.12 上的包构建、生成器/解析器对齐、已提交制品验证，以及独立的训练并检查冒烟测试。

仓库结构

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

原始恶意软件、下载的语料库、凭据以及本地训练的临时模型不属于仓库的一部分。

范围与限制

• ZIP 是唯一支持的压缩包格式。不声称支持 RAR、7z、APK 和 JAR 的性能。
• 模型基于生成的规避变体和良性标记特征行训练。新的解析器差异可能与学习到的特征分布不匹配。
• 无法检查加密内容。目录递归会发现嵌套文件夹中的 ZIP 文件；但不会扫描嵌入在其他压缩包中的压缩包。
• 结果应输入隔离或审查工作流，而不是替代防病毒引擎、沙箱、内容扫描器或人工分析师。
• 对抗性压缩包可能消耗内存或 CPU。请保持启用 --max-size-mb 输入上限，并在生产部署中添加进程级内存和时间限制。

贡献与安全

在修改解析器、数据集或评估协议之前，请阅读 CONTRIBUTING.md。不要提交没有可复现制品的恶意软件样本、API 凭据或基准声明。

如需报告漏洞或解析器绕过问题，请遵循 SECURITY.md。请不要在公开 issue 中附加真实恶意软件。

许可证

根据 Apache License 2.0 许可证授权。

数据卡 · 模型卡 · 安全政策 · 贡献指南 · CI