VulnAgentX 研究プロトタイプ

VulnAgentX は、論文の再現を目的としたマルチエージェントの脆弱性・欠陥検出プロトタイプです。ローカルリポジトリまたは diff を入力として、構造化された findings、エビデンスチェーン、位置特定結果、信頼度、実験ログを出力します。

コア機能

入力形式：repo path または unified diff
ワークフロー：screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
出力フィールド：
- issue_type
- location(file + line range)
- evidence_summary
- confidence
- severity
- optional_cwe
- fix_hint
- evidence_chain
- counter_evidence
インターフェース：CLI + FastAPI
再現可能な実験：pytest / mypy / ruff + Docker 実行サポート

ワークフロー概要

screening：疑わしい領域を高速スクリーニング（ルール + メタデータシグナル）
context_expansion：「必要最小限のコンテキスト」を取得（疑わしい位置に基づきウィンドウを抽出）
scheduler：信頼度とリスクに基づくエスカレーション戦略（early_exit / expert_review / verification）
router_agent：各疑わしい領域に専門エージェントを割り当てる
semantic/security/logic：異なる視点から構造化された主張とエビデンスを提供
sceptic_agent：反証とペナルティシグナルを生成
verification：オプションの動的検証（現在は安全なプレースホルダー実装）
evidence_fusion：統一的に融合し、最終的な findings を出力

インストールと実行チュートリアル

1) 環境準備

要件：Python 3.11+（現在はより新しいバージョンでも実行可能）

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) CLI の使用

リポジトリ全体を分析：

.venv/bin/vulnagentx analyze --repo /path/to/repo --output json

diff ファイルを分析：

.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json

簡潔な出力：

.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary

3) API の使用

サービスを起動：

.venv/bin/uvicorn vulnagentx.app.api:app --reload

ヘルスチェック：

curl http://127.0.0.1:8000/health

分析を実行：

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path":"/path/to/repo"}'

4) Docker での実行

docker compose -f docker/docker-compose.yml up --build

5) 品質チェックとテスト

.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest

出力例

{
  "run_id": "...",
  "findings": [
    {
      "issue_type": "command_injection",
      "location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
      "evidence_summary": "Command execution surface detected...",
      "confidence": 0.87,
      "severity": "critical",
      "optional_cwe": "CWE-78",
      "fix_hint": "Avoid shell command composition...",
      "source_agents": ["security_agent", "semantic_agent"],
      "evidence_chain": [],
      "counter_evidence": []
    }
  ],
  "metrics": {
    "runtime_seconds": 0.07
  },
  "logs": []
}

ファイルの用途説明（ファイル別）

ルートディレクトリとプロジェクトファイル

ファイル	用途
`.env.example`	環境変数テンプレート（ログレベルなどのオプション設定）。
`pyproject.toml`	プロジェクトのビルド、依存関係、スクリプトエントリポイント、pytest/ruff/mypy 設定。
`README.md`	メイン README（言語切り替えボタン付き、デフォルトは中国語）。
`README.zh.md`	中国語の完全版ドキュメント。
`README.en.md`	英語の完全版ドキュメント。
`docker/Dockerfile`	API サービスコンテナイメージのビルドファイル。
`docker/docker-compose.yml`	ローカルでワンクリック起動するコンテナサービス。
`rules/semgrep/vulnagentx-rules.yml`	内蔵 Semgrep ルールセット（コマンドインジェクション/SQLインジェクション/デシリアライゼーション/安全でないC API）。
`scripts/run_experiment.py`	データセットのバッチ実験実行スクリプト。予測 JSONL を出力。
`scripts/evaluate.py`	実験出力を読み取り、検出/位置特定/効率の指標を計算。
`scripts/run_ablation.py`	アブレーション実験スクリプト（no_semgrep/no_treesitter/no_sceptic/no_verification）。

コアソースコード（`src/vulnagentx`）

ファイル	用途
`src/vulnagentx/__init__.py`	パッケージのバージョンとエクスポート定義。
`src/vulnagentx/app/__init__.py`	`app` サブパッケージの初期化。
`src/vulnagentx/app/cli.py`	CLI エントリポイント（`vulnagentx analyze`）。
`src/vulnagentx/app/api.py`	FastAPI サービスエントリポイント（`/health`、`/analyze`）。
`src/vulnagentx/app/schemas.py`	API リクエスト/レスポンスの Pydantic Schema。
`src/vulnagentx/core/__init__.py`	`core` サブパッケージの初期化。
`src/vulnagentx/core/state.py`	グローバル状態モデル：領域、エビデンス、エージェント出力、Finding、ログ、指標。
`src/vulnagentx/core/screening.py`	第1フェーズの高速スクリーニング。疑わしい領域を抽出。
`src/vulnagentx/core/context_expansion.py`	コンテキスト拡張：特定位置に基づき最小限のコードウィンドウを抽出。
`src/vulnagentx/core/scheduler.py`	信頼度を考慮したエスカレーション戦略（early_exit/expert_review/verification）。
`src/vulnagentx/core/verification.py`	オプションの動的検証モジュール（現在は安全なプレースホルダー版）。
`src/vulnagentx/core/evidence_fusion.py`	マルチエージェントのエビデンス融合。最終 findings を出力。
`src/vulnagentx/core/workflow.py`	エンドツーエンドのオーケストレーションエントリポイント `VulnAgentWorkflow`。
`src/vulnagentx/agents/__init__.py`	エージェントのエクスポート集約。
`src/vulnagentx/agents/base.py`	エージェント抽象基底クラスとコンテキスト取得ユーティリティ。
`src/vulnagentx/agents/router_agent.py`	ルーティングエージェント：各疑わしい領域に専門エージェントを割り当てる。
`src/vulnagentx/agents/semantic_agent.py`	セマンティックエージェント：意味層のリスク（例：ヌルポインタ、デシリアライゼーション、例外の握りつぶし）。
`src/vulnagentx/agents/security_agent.py`	セキュリティエージェント：セキュリティ脆弱性ルール（コマンドインジェクション、SQLインジェクション、範囲外アクセスなど）。
`src/vulnagentx/agents/logic_bug_agent.py`	ロジックエージェント：ビジネス/制御フローの欠陥（境界、ゼロ除算、認可の欠落など）。
`src/vulnagentx/agents/sceptic_agent.py`	懐疑者エージェント：反証、矛盾ペナルティ、信頼度低下を生成。
`src/vulnagentx/adapters/__init__.py`	アダプターサブパッケージの初期化。
`src/vulnagentx/adapters/sandbox_adapter.py`	制限付きサブプロセスサンドボックス実行器（タイムアウト、シェルなし）。verification 用。
`src/vulnagentx/adapters/semgrep_adapter.py`	Semgrep CLI アダプター（オプションで有効化）。
`src/vulnagentx/adapters/treesitter_adapter.py`	実際の Tree-sitter アダプター（利用可能な場合は AST と呼び出し/インポート関係を解析し、利用不可の場合はフォールバック）。
`src/vulnagentx/adapters/llm/__init__.py`	LLM アダプターエクスポートの集約。
`src/vulnagentx/adapters/llm/base.py`	LLM アダプターのプロトコルインターフェース。
`src/vulnagentx/adapters/llm/mock_adapter.py`	オフラインでテスト可能な Mock LLM。
`src/vulnagentx/adapters/llm/openai_adapter.py`	OpenAI 公式 SDK アダプター。
`src/vulnagentx/adapters/llm/local_adapter.py`	ローカルモデルアダプター（Ollama HTTP API）。
`src/vulnagentx/adapters/llm/factory.py`	設定に基づき LLM アダプターを自動選択し、最終的に Mock にフォールバック。
`src/vulnagentx/retrieval/repo_graph.py`	コードグラフインデックスと近隣ファイル検索（AST シンボルの重複に基づく）。
`src/vulnagentx/datasets/base.py`	汎用データセットのサンプル構造と JSONL/CSV 読み込み。
`src/vulnagentx/datasets/devign.py`	Devign データロードエントリポイント。
`src/vulnagentx/datasets/bigvul.py`	Big-Vul データロードエントリポイント。
`src/vulnagentx/datasets/primevul.py`	PrimeVul データロードエントリポイント。
`src/vulnagentx/datasets/jit.py`	JIT データロードエントリポイント。
`src/vulnagentx/eval/detection_metrics.py`	検出指標（Precision/Recall/F1/Accuracy）。
`src/vulnagentx/eval/localization_metrics.py`	位置特定指標（Top-1/Top-3/MRR）。
`src/vulnagentx/eval/efficiency_metrics.py`	効率指標（平均処理時間、P95、平均 findings）。
`src/vulnagentx/eval/ablations.py`	アブレーション実験の実行ロジック。
`src/vulnagentx/utils/config.py`	ワークフロー設定センター（env/CLI/API スイッチ）。

テストファイル（`tests`）

ファイル	用途
`tests/test_agents.py`	単体テスト：各エージェントの構造化出力と反証ロジック。
`tests/test_end_to_end.py`	エンドツーエンドテスト：入力リポジトリから最終 findings までのメインフロー。
`tests/test_research_modules.py`	新規モジュールのテスト：Tree-sitter グラフ構築、verification 実行チェーン、評価指標。

今回実装した拡張モジュール

実際の LLM アダプター：OpenAI + ローカル Ollama + 自動ファクトリー切り替え
実際の Tree-sitter AST とコードグラフ：関数/インポート/呼び出し関係を解析し、近隣ファイルのコンテキスト拡張をサポート
実際の Semgrep ルールセット：内蔵ルールファイルを screening フェーズに組み込み
verification サンドボックス実行チェーン：タスク計画、制限付き実行、タイムアウト制御、構造化結果の書き戻し
データセット評価とアブレーション：データローダー、指標モジュール、実験・アブレーションスクリプト

Vlun-Agent-X

人気

VulnAgentX 研究プロトタイプ

コア機能

ワークフロー概要

インストールと実行チュートリアル

1) 環境準備

2) CLI の使用

3) API の使用

4) Docker での実行

5) 品質チェックとテスト

出力例

ファイルの用途説明（ファイル別）

ルートディレクトリとプロジェクトファイル

コアソースコード（`src/vulnagentx`）

テストファイル（`tests`）

今回実装した拡張モジュール

Vlun-Agent-X

人気

VulnAgentX 研究プロトタイプ

コア機能

ワークフロー概要

インストールと実行チュートリアル

1) 環境準備

2) CLI の使用

3) API の使用

4) Docker での実行

5) 品質チェックとテスト

出力例

ファイルの用途説明（ファイル別）

ルートディレクトリとプロジェクトファイル

コアソースコード（src/vulnagentx）

テストファイル（tests）

今回実装した拡張モジュール

コアソースコード（`src/vulnagentx`）

テストファイル（`tests`）