ZIPアーカイブにおける構造的メタデータ回避のための防御型スキャナ。
ZombieGuardは、ZIPのローカルファイルヘッダー、セントラルディレクトリレコード、およびペイロード特性の間の矛盾を検出します。これらの矛盾は、あるパーサーにはアーカイブの内容が空または無害に見える一方で、別のパーサーはペイロードに到達できるようにするために使用される可能性があります。
制限付きZIPパーサーと小型のLightGBMモデルを組み合わせています。アーカイブの内容を抽出したり実行したりすることはありません。
[!IMPORTANT] ZombieGuardはアーカイブ回避シグナルを検出するものであり、マルウェアを検出するものではありません。クリーンな結果は、アーカイブ内のファイルが安全であることの証明にはなりません。
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
リリースモデルはパッケージに同梱されています。入力サイズ制限、JSON/SARIF出力、ディレクトリスキャンオプションについては zombieguard scan --help を参照してください。
開発の場合は、リポジトリを編集可能モードでインストールします:
python -m pip install -e ".[dev]"
python -m pytest
ZombieGuardは、マルウェアシグネチャを探すのではなく、各ZIPを整合性の問題として扱います:
スキャナは、根拠となる理由コードとともに判定結果を報告します。パース失敗は、判定不能または疑わしい状態として報告され、クリーンな結果に黙って変換されることはありません。
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 にあります。このファイルには、バリアント別のフォールド要約、データソースのハッシュ、リーク検証、モデルのチェックサム、正確な設定も含まれています。履歴書、論文、プレゼンテーションで指標を使用する場合は、その範囲を合成ネスト型リーブワンバリアントアウト特徴評価として引用してください。
ネガティブ行は、PyPI由来686行、生成されたハードネガティブ478行、生成された小型良性400行、Office由来4行の特徴行で構成されています。ネガティブソースファミリは、ファミリ単位でホールドアウトされるのではなく、フォールド全体に分散されます。区間は、このベンチマーク内の行レベルの不確実性を表しており、デプロイ時の不確実性やドメインシフトを推定するものではありません。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
生のマルウェア、ダウンロードしたコーパス、認証情報、ローカルでトレーニングされたスクラッチモデルはリポジトリの一部ではありません。
--max-size-mb 入力上限を有効に保ち、本番デプロイではプロセスレベルのメモリと時間制限を追加してください。パーサー、データセット、評価プロトコルを変更する前に CONTRIBUTING.md をお読みください。再現可能な成果物なしに、マルウェアサンプル、API認証情報、ベンチマークの主張をコミットしないでください。
脆弱性またはパーサーバイパスの報告については、SECURITY.md に従ってください。公開されたissueに生きたマルウェアを添付しないでください。
Apache License 2.0 の下でライセンスされています。
データカード · モデルカード · セキュリティポリシー · コントリビューション · CI
| 項目 | リリースプロトコル |
|---|
| 対象範囲 | 合成陽性ZIP構造回避特徴ベンチマーク |
| 対象コーパス | 生成された陽性1,150件と重複排除済みの良性ラベル付き特徴行1,568件 |
| 陽性ホールドアウト | 各フォールドから完全な攻撃バリアントを1つ除外（8バリアント） |
| 良性ホールドアウト | 決定論的SHA-256分割。各サンプルは一度だけ評価される |
| 決定しきい値 | 外部トレーニング行のみに対するネストされたグループ較正。良性FPR予算0.5% |
| 報告される予測 | 外部フォールド予測のみ。ホールドアウト行がしきい値を設定することはない |
| 主張から除外 | MalwareBazaar由来およびその他の未検証の陽性ラベル |
| 信頼性 | 集計指標と併せたWilson 95%区間 |
| 指標 | 結果 | 95% Wilson区間 |
|---|
| 正解率 | 99.89% (2,715 / 2,718) | 99.68–99.96% |
| 適合率 | 99.74% | 99.24–99.91% |
| 再現率 | 100% (1,150 / 1,150) | 99.67–100% |
| F1 | 99.87% | — |
| ROC-AUC | 99.90% | — |
| 偽陽性率 | 0.191% (3 / 1,568) | 0.065–0.561% |