VulTriage

大規模言語モデルと静的コード解析に基づくインテリジェントな脆弱性検出フレームワークで、複数データセットによる評価とアブレーション研究に対応しています。

📋 目次

• Introduction
• Key Features
• System Requirements
• Quick Start
• Usage
• Datasets & Models
• FAQ

はじめに

このプロジェクトは、GPT-4o と BGE-M3 モデルに基づくインテリジェントな脆弱性検出フレームワークであり、以下を組み合わせています:

• 静的構造解析: 制御フローグラフ(CFG)、データフローグラフ(DFG)、抽象構文木(AST)
• 検索拡張生成(RAG): CWE ナレッジベースに基づく脆弱性パターンマッチング
• コード理解: 大規模言語モデルを用いた意味解析
• ペア/単一サンプル検出: 複数の評価モードに対応

主な特徴

• ✅ PrimeVul および Kotlin データセットに対応
• ✅ CWE 脆弱性ナレッジベース検索を統合
• ✅ 設定可能なアブレーション研究
• ✅ リアルタイムのメトリクス追跡
• ✅ 柔軟なハイパーパラメータ実験に対応

システム要件

• Python >= 3.9
• CUDA(オプション、GPU アクセラレーション用)

クイックスタート

1. 依存関係のインストール

pip install -r requirements.txt

2. リソースの準備

BGE-M3 モデルのダウンロード

モデルは自動的にダウンロードされます。手動でダウンロードすることもできます:

git clone https://huggingface.co/BAAI/bge-m3
# 注: BGE-M3 関連の依存関係は FlagEmbedding でインストールできます。詳細は: pip install -U FlagEmbedding を参照してください。

CWE データの準備

プロジェクトのルートディレクトリに cwec_latest.xml/cwec_v4.19.1.xml と 1435.csv/1435_filtered_columns.csv(CWE インデックスデータ)ファイルが存在することを確認してください。

注: このプロジェクトは CWE Top 25 Most Dangerous Software Weaknesses を使用しています。関連ファイルはプロジェクトのルートディレクトリにすでに含まれています。

データセットの準備

以下のファイルをプロジェクトのルートディレクトリに配置してください:

• primevul_test_paired.jsonl(PrimeVul データセット)
• LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv(Kotlin データセット)

3. API キーの設定

main.py または hyperparam_exp.py の OpenAI API 設定を変更します:

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.poixe.com/v1"
)

注: 現在の URL https://api.poixe.com/v1 は解析に失敗しました。サポートされていない Web ページタイプ、またはリンク切れの可能性があります。リンクの有効性を確認するか、別の API プロバイダーに切り替えてください。

4. 脆弱性検出の実行

基本モード(全機能)

python main.py --wotask all --jsonl_file primevul_test_paired.jsonl

アブレーション研究モード

# 制御フロー情報なし
python main.py --wotask wo_ctrl_info_pth --jsonl_file primevul_test_paired.jsonl
# RAG 知識なし
python main.py --wotask wo_rag_pth --jsonl_file primevul_test_paired.jsonl
# コード理解なし
python main.py --wotask wo_exp_pth --jsonl_file primevul_test_paired.jsonl
# 補助情報なし
python main.py --wotask nan --jsonl_file primevul_test_paired.jsonl

ハイパーパラメータ実験

# ペア評価モード
python hyperparam_exp.py --mode pairwise --input_file primevul_test_paired.jsonl --detail_level C --info_comb all --desc_level concise --max_vuln 2
# 単一サンプル評価モード
python hyperparam_exp.py --mode single --input_file LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv

5. 結果の確認

検出結果はリアルタイムで metrics_log.txt に保存され、最終的な評価サマリーがターミナルに出力されます:

• 評価メトリクスには、正確度、再現率、偽陽性率などが含まれます。
• アブレーション研究の結果は、各モード間の性能差を比較し、各モジュールの貢献度を分析します。

使い方

主要スクリプト概要

パラメータ説明

main.py のパラメータ

hyperparam_exp.py のパラメータ

データセットとモデル

📊 データセット

1. PrimeVul データセット

• 引用: Yangruibo Ding, Yanjun Fu, Omniyyah Ibrahim, Chawin Sitawarin, Xinyun Chen, Basel Alomair, David Wagner, Baishakhi Ray, and Yizheng Chen. 2025. Vulnerability detection with code language models: How far are we? ISSTA 2025 (2025).
• 目的: ペア脆弱性検出ベンチマーク
• 形式: JSONL(func フィールドと target フィールドを含む)
• 出典: ISSTA 2025 会議(ISSTA 公式サイト)。データセットへのアクセス権限については原著論文を参照してください。

2. Kotlin データセット

• 引用: Triet Huynh Minh Le, M Ali Babar, and Tung Hoang Thai. 2024. Software vulnerability prediction in low-resource languages: An empirical study of codebert and chatgpt. In Proceedings of the 28th International Conference on Evaluation and Assessment in Software Engineering, 679–685.
• 目的: 低リソース言語における脆弱性予測研究
• 形式: CSV(code 列と label 列を含む)
• 出典: EASE 2024 会議(EASE 2024 公式サイト)。データセットへのアクセス権限については原著論文を参照してください。

3. CWE データベース

• バージョン: CWE v4.19.1
• 出典: MITRE CWE
• 目的: 脆弱性パターンナレッジベースおよび検索拡張
• 注記: CWE は研究、開発、商用目的で自由に使用できます。MITRE への著作権表示を保持する必要があります。

🤖 モデル

1. BGE-M3 埋め込みモデル

• 開発元: BAAI(北京智源人工智能研究院)
• HuggingFace: BAAI/bge-m3
• ライセンス: MIT ライセンス(注: 現在のモデルライセンスページの解析に失敗しました。FlagEmbedding プロジェクトのライセンスを参照してください。MIT ライセンスです)
• 目的: 高密度・スパースベクトルのハイブリッド検索。多言語、多粒度(最大入力長 8192 トークン)、多機能検索をサポート
• 関連プロジェクト: FlagEmbedding(BGE シリーズモデルのオープンソースリポジトリ)

2. GPT-4o

• 開発元: OpenAI
• モデルバージョン: gpt-4o-2024-11-20
• ライセンス: OpenAI 利用規約に従います(2026 年 1 月 1 日有効)
• 目的: コード理解、脆弱性の識別、推論と判断
• 注記: 使用にあたっては OpenAI 利用規約に準拠する必要があります。違法または有害な活動、モデルのリバースエンジニアリングは禁止されています。

📦 依存ライブラリ

FAQ

Q1: OpenAI API プロバイダーを変更するにはどうすればよいですか?

main.py または hyperparam_exp.py の base_url と api_key を変更してください。

Q2: 検索結果が不正確なのはなぜですか?

1. 1435.csv/1435_filtered_columns.csv が正しく読み込まれているか確認し、CWE インデックスデータの形式が正しいことを確認してください;
2. BGE-M3 モデルが正しくダウンロードされていることを確認してください。git clone https://huggingface.co/BAAI/bge-m3 で手動ダウンロードできます;

Q3: 評価メトリクスをカスタマイズするにはどうすればよいですか?

metrics_tracker.py の update_pair_metrics メソッドを変更して、メトリクス計算ロジックを追加または調整してください。

Q4: BGE-M3 モデルのダウンロードに失敗した場合はどうすればよいですか?

HuggingFace のウェブサイトからモデルファイルを直接ダウンロードし、プロジェクトのルートディレクトリに展開するか、ネットワーク接続を確認して git clone https://huggingface.co/BAAI/bge-m3 コマンドを再実行してください。