Deserializer

プロジェクトについて

• Deserializer は、Python エコシステム全体にわたる安全でないオブジェクト再構築および状態永続化のシンクを特定するために設計された、高度な抽象構文木 (AST) 静的解析エンジンです。AI、LLM、ロボティクス、データサイエンス、機械学習、深層学習の分野に特に重点を置いていますが、それらに限定されません。
• Deserializer は、アプリ、スクリプト、フレームワーク、ライブラリ、Python pip パッケージなど、Python ソースコードに基づくあらゆる種類のプロジェクトをスキャンおよび解析するために設計されました。

主要な技術的能力

従来のスキャナをはるかに超え、YAML、Msgpack、CBOR、カスタム JSON フックなど 120 以上のライブラリとフォーマットを監査するための汎用的で高性能なフレームワークを提供します。そこでは「安全な」シリアライゼーションへの従来の信頼が、ロジックベースの重大な RCE ベクターを隠蔽しています。インポート、エイリアス、複雑なドット付き属性を解決することで、本ツールは、現代の分散アーキテクチャや AI/ML リポジトリにおける危険なコードパスを優先する、高忠実度のシグナル増幅器として機能します。

本プロジェクトは、生の検出から深い技術監査へと移行する、モジュール式の多段階ワークフローを通じて動作します。初期の高速 SAST スキャンに続き、エコシステムは実行フローを追跡するための専用のリレーションシップマッパーと、詳細なセキュリティレポートを生成するための結果プロセッサを活用します。この体系的なアプローチにより、すべての発見がアプリケーションのより広範なアーキテクチャ内で文脈化され、大量のテレメトリが実用的な研究資産と、インフラストラクチャレベルの攻撃対象領域のマッピングを簡素化する構造化されたマイルストーンへと変換されます。

自律型 AI セキュリティエージェント

その最も高度な段階において、Deserializer は自律型 AI セキュリティエージェント (フェーズ 4) を統合しており、「自己コマンドインジェクション」の制約を回避し、HuggingFace 推論 API、ローカル LLM (llama.cpp など)、または OpenAI API 互換に基づいて、機能的な再現ガイドを合成するために明示的に設計されています。

プロジェクトが進化するにつれ、抽象構文木の静的解析、リレーションシップマッピング、レポーティング、および文書化された研究に基づく機能的なエクスプロイト開発の間のギャップを埋めることで、自動化された脆弱性研究のフロンティアを定義し続けています。

研究 (AI、ロボティクス、データサイエンス、機械学習、深層学習)

Deserializer は、Genesis World (v0.2.1)、MuJoCo (v3.7.0)、LeRobot (v0.5.1)、Brax (v0.14.2)、TensorFlow (v2.21.0)、LangGraph (v1.1.6)、VibeVoice (v0.0.1)、Hugging Face Hub (v1.11.0)、PyGlove (v0.4.5) など、さまざまな大規模 AI、ロボティクス、データサイエンスのプロジェクトや環境にわたる RCE および安全でないデシリアライゼーションのパスを特定することで、セキュリティ研究を直接支援します。

その機能は、業界をリードするフレームワークにおける重大な脆弱性の発見を直接支え、複雑な MLOps およびエージェント型 AI 環境の監査におけるその有効性を証明しています。

Deserializer の 4 つのフェーズ

本プロジェクトは 4 つの異なるフェーズで構成され、それぞれが大量の自動テレメトリから深い機能的なセキュリティ研究へと分析を移行するように設計されています:

フェーズ	タイトル	ツール / エンジン	目的
1	高速検出	deserializer.py (Triple-Pass)	潜在的なデシリアライゼーションシンクを特定するための大規模 SAST を実行します。
2	リレーションシップマッピング	結果プロセッサ / マッパー	実行フローとコンポーネントの相互依存関係を追跡することで、発見を文脈化します。
3	技術的統合	研究ドキュメント	発見を技術的な記事に形式化し、インフラストラクチャレベルの攻撃対象領域をマッピングします。
4	自律型 AI エージェント	AI セキュリティエージェント	HuggingFace 推論 API、ローカル LLM (llama.cpp など)、または OpenAI API 互換を使用して、0-day の発見を自動化し、機能的な再現ガイド / エクスプロイトを生成します。

プロジェクト構造

リポジトリの構成と、各専門ディレクトリの技術的な目的の概要:

• agent/
  フェーズ 4 の AI セキュリティエージェントの実装。深い分析、再現ガイドの合成、LLM との対話のためのオーケストレーションロジックを含みます。
• docs/
  プロジェクトのドキュメント、アーキテクチャ図、ブランディング資産、および補足的な高レベル技術資料の中央リポジトリ。
• exploit_development/
  機能的なエクスプロイトのエンジニアリング、デシリアライゼーションプリミティブ (フック / メソッド) の研究、およびクロスプラットフォームのオーケストレーション技術の文書化のための専用スペース。
• modules/
  ツールチェーンの検出フェーズとリレーションシップマッピングフェーズを支えるコアロジックコンポーネント、補助ユーティリティ関数、およびスキャナ拡張。
• reports/
  多段階のプロジェクト評価中にスキャナによって生成された、構造化されたセキュリティ分析出力、テレメトリ、および監査結果の保管場所。
• research/
  高忠実度の脆弱性記事、検証済みの概念実証 (PoC) スクリプト、および現代の AI/ML フレームワークに対して実施された深い監査のコレクション。
• templates/
  脆弱性記事と相関レポート全体で技術的な一貫性を維持するために使用される、標準化されたレポーティングおよび研究テンプレート。

パフォーマンスとマルチプロセッシング

このスキャナは、Python の concurrent.futures.ProcessPoolExecutor 上に構築された高性能な並列実行エンジンを備えています。利用可能なすべての CPU コアにわたってスケールするように設計されており (-j または --concurrency フラグで制御可能)、数万のファイルを数秒でスキャンできます。

• ノンブロッキング UI: 安定したドッキング型プログレスバーを備え、結果をクリーンに表示するための 1 行のギャップがあります。
• ネイティブシグナルハンドリング: Windows では、ctypes を介してネイティブの SetConsoleCtrlHandler を利用し、負荷の高い処理中でも Ctrl+C が 100% 応答することを保証します。
• サイレントトレースバック: ワーカープロセスはサイレント化され、割り込みや内部エラーが技術的な出力を乱さないようにします。
• ネイティブ Windows UI サポート: 最新の CMD および PowerShell 環境でネイティブの ANSI カラーサポートを実現するために、ctypes を介して Virtual Terminal Processing を自動的に有効化します。

[!WARNING] パフォーマンス警告: 極端に大きいまたは複雑なファイル (例: サイズが 1MB、2MB、または 3MB を超えるもの) を分析する場合、深い AST ツリーを解析する際にツールが大幅に遅くなる、または「スタック」しているように見えることがあります。そのようなボトルネックに遭遇した場合は、--timeout (遅いファイルをスキップ) および --max-size (巨大なファイルをスキップ) フラグの使用を検討して、スキャン速度を維持してください。

機能

• Triple-Pass スキャンエンジン: 「壊れない」多層アプローチを実装します:
  • パス 1 (AST): 正確な分析のための高忠実度の文法的分解。
  • パス 2 (トークンフォールバック): 構文エラーや解析不能なセクションに遭遇した場合の、ストリームベースのトークナイザへの自動フォールバック。
  • パス 3 (正規表現緊急対応): 極めて敵対的または断片化されたソースファイルでもカバレッジを確保する最終的なパターンマッチング層。
• ネイティブテンプレート無効化: Jinja2 および Mako タグのサニタイズを組み込みでサポートし、スキャナが非 Python 構文で詰まることなく Web テンプレートやコード生成ファイルを処理できるようにします。
• 呼び出しと参照の検出: 直接的な実行シンク (例: pickle.loads()) だけでなく、危険な関数参照 (例: func = pickle.load) も特定し、ローカル名前空間全体にわたる代入を追跡します。
• 以下のような呼び出しを解決するためにインポート / エイリアスを追跡します:
  • import pickle as p → p.loads(...)
  • import torch as t → t.load(...)
  • pkg.pickle.loads(...) や torch.serialization.load(...) のような深い属性
• 発見を JSONL として出力します。1 行につき 1 オブジェクトで、以下を含みます:
  • ファイルパス + 位置 (lineno、col_offset)
  • module、name、qualified_name
  • category および severity (追加フィールド、後方互換)
  • parser: どのエンジンパスが発見を行ったかを示すメタデータ (ast、tokenize_fallback、または regex_fallback)。
• 以下によって病的な入力から保護します:
  • 最大ファイルサイズ (MAX_FILE_BYTES)
  • 最大訪問 AST ノード数 (MAX_AST_NODES)
• オプション: rules.json からカスタムルールセットを読み込み、不正なエントリやタイポについて警告します。

インストール

最小 Python バージョン 3.9 以上を推奨、3.10 以上でテスト済み。

python --version
# Python 3.9+ recommended

セットアップ要件:

• 環境: プロバイダに応じて、ルートディレクトリに .env ファイルを作成します:

  # For Hugging Face provider
  HF_TOKEN=your_token_here
  
  # For OpenAI / Local LLM provider
  HA_LLM_TOKEN=your_jwt_token_here
  

スキャナを実行する前に、依存関係をインストールする必要があります:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

使用方法

推奨される使用方法:

AI エージェントなし

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl

AI エージェントあり (ローカル LLM)

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1

AI エージェントあり (OpenAI / ローカル LLM)

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

AI セキュリティエージェントによる AI 駆動の深い分析 (フェーズ 4)

このフェーズでは、専門の AI セキュリティエージェントを統合して、深いコードレビューを実行し、複雑な 0-day RCE ベクターをマッピングします。エージェントは発見を分析して「自己コマンドインジェクション」のコンテキストを逆転させ、マルチプラットフォーム (例: 攻撃者 UNIX/Raspberry 対 被害者 Windows) に焦点を当てた技術的な再現ガイドを生成します。注: このフェーズは --agent フラグが指定された場合にのみ実行されます。

推論プロバイダ:

• Hugging Face (デフォルト): MiniMax-M2.5 などのクラウドベースの API モデルを使用します。
  • .env ファイルまたは環境変数に HF_TOKEN が必要です。
  • コマンド: python deserializer.py --path /path/to/repo --agent --agent-provider huggingface
• ローカル LLM (llama.cpp): ローカルの REST サーバ (llama-server.exe) を使用します。
  • サーバを起動するコマンド例: .\llama-server.exe --model .\models\model.gguf --host 127.0.0.1 --port 8181 --ctx-size 600000 --jinja
  • コマンド: python deserializer.py --path /path/to/repo --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1
• OpenAI 互換:
  • .env に HA_LLM_TOKEN (または OPENAI_API_KEY) が必要です。
  • コマンド: python deserializer.py --path /path/to/repo --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

1. 基本スキャン

現在のディレクトリをスキャンし、発見をターミナルに出力します (デフォルトでは JSONL を stdout に書き込みます):

python deserializer.py

2. 対象を絞った監査

特定のリポジトリをスキャンし、発見を JSONL ファイルに保存します:

python deserializer.py --path /path/to/my-repo --out audit_results.jsonl

3. ターボモード (パフォーマンスチューニング)

8 つの並列プロセスとファイルごとに 5 秒のタイムアウトを使用して、スキャンを進めます:

python deserializer.py -j 8 --timeout 5 --out findings.jsonl

4. CI/CD とパイプライン統合

バナーを無効化し、パイプ処理のために JSONL を直接 stdout にストリームします (人間向けのログは stderr に出力されます):

python deserializer.py --no-banner --out - | jq .

5. 堅牢化 / 安全スキャン

処理を 1MB 未満のファイルに制限し、特定のデータディレクトリをスキップします:

python deserializer.py --max-size 1048576 --skip-dirs "data,samples,tests"