Vulnhalla

LLM分類による自動CodeQL分析

詳細な研究背景やVulnhallaの動機については、公式CyberArk脅威研究ブログ記事をご覧ください：

Vulnhalla: Picking the True Vulnerabilities from the CodeQL Haystack

Vulnhallaはセキュリティ分析パイプライン全体を自動化します：

1. リポジトリの取得：特定のプログラミング言語のGitHubリポジトリを取得
2. CodeQLデータベースのダウンロード：利用可能な場合、対応するCodeQLデータベースをダウンロード
3. CodeQLクエリの実行：それらのデータベースに対してCodeQLクエリを実行し、セキュリティやコード品質の問題を検出
4. LLMによる後処理：LLM（ChatGPT、Geminiなど）を使用して結果を分類・フィルタリング

🚀 クイックスタート

ステップ1：前提条件

開始する前に、以下を用意してください：

• Python 3.10 – 3.13（Python 3.11 または 3.12 推奨）

  • Python 3.14+ は非対応です（このツールはgrpcioを使用しており、Python 3.14+ではサポートされていません）
  • python.orgからダウンロード

• CodeQL CLI

  • CodeQL CLI releasesからダウンロード
  • codeql がPATHに含まれていることを確認するか、後述のステップ2で .env にパスを設定します

• （オプション）GitHub APIトークン

  • データベースダウンロード時のレート制限緩和のため
  • GitHub Settings > Tokensから取得

• LLM APIキー

  • OpenAI、Azure、Gemini、Bedrockのいずれかの認証情報（プロバイダに応じて）

ステップ2：環境設定

すべての設定は単一のファイル .env にまとめられています。

1. リポジトリをクローン：

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. .env.example を .env にコピー：

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. .env を編集し、値を入力：

OpenAIの例：

CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2

# オプション：ログ設定
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # オプション：ログファイルのパス（例：logs/vulnhalla.log）
LOG_FORMAT=default              # default または json
# LOG_VERBOSE_CONSOLE=false     # trueの場合、WARNING/ERRORが完全な形式（タイムスタンプ - ロガー - レベル - メッセージ）

📖 完全な設定リファレンスについては：下記の設定リファレンスを参照してください。サポートされているすべてのプロバイダ（OpenAI、Azure、Gemini、Bedrock）、必須/オプション変数、詳細な例が含まれています。

ステップ3：Poetryのインストール（推奨：pipx使用）

Windows (PowerShell)：

# 利用可能なPythonバージョンを表示
py -0p

# サポートされているPython: 3.10 / 3.11 / 3.12 / 3.13 から選択
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# ターミナルを閉じて再起動（必須）
pipx install poetry
poetry --version

macOS / Linux：

# Pythonバージョンを確認
python3 --version

# サポートされているPython: 3.10 / 3.11 / 3.12 / 3.13 から選択
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# ターミナルを再起動（必須）
pipx install poetry
poetry --version

ステップ4：依存関係のインストールとセットアップ

Windows (PowerShell)：

# インストール済みのサポートバージョンから1つ選択: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # 複数バージョンがインストールされている場合、Poetryにサポート対象のPythonバージョンを強制指定
poetry install
poetry run vulnhalla-setup

macOS / Linux：

# インストール済みのサポートバージョンから1つ選択: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # 複数バージョンがインストールされている場合、Poetryにサポート対象のPythonバージョンを強制指定
poetry install
poetry run vulnhalla-setup

ステップ5：パイプラインの実行

# 特定のリポジトリを分析（例）
poetry run vulnhalla redis/redis

# データベースが既に存在しても再ダウンロード
poetry run vulnhalla redis/redis --force

# ヘルプを表示
poetry run vulnhalla --help

これにより自動的に：

1. CodeQLデータベースを取得
2. ダウンロードしたすべてのデータベースに対してCodeQLクエリを実行
3. LLMで結果を分析し、output/results/ に保存
4. UIを開いて結果を閲覧

ローカルCodeQLデータベースの使用

すでにディスク上にCodeQLデータベースがある場合（手動で作成した、または以前の実行からのものなど）、--local / -l フラグを使用してGitHub取得ステップをスキップできます：

Windows (PowerShell)：

poetry run vulnhalla --local C:\path\to\my-codeql-db

macOS / Linux：

poetry run vulnhalla --local /path/to/my-codeql-db

注： --local フラグはソースコードフォルダではなく、CodeQL データベースディレクトリを期待します。フォルダに codeql-database.yml ファイルが含まれているか確認してください。

追加コマンド

# 既存の結果を表示するUIを開く（分析は実行しない）
poetry run vulnhalla-ui

# 設定を検証：CodeQL、LLM、ログ設定（分析は実行しない）
poetry run vulnhalla-validate

# 分析済みリポジトリとその問題数を一覧表示
poetry run vulnhalla-list

# サンプルパイプラインを実行（videolan/vlc と redis/redis を分析）
poetry run vulnhalla-example

🖥️ ユーザーインターフェース（UI）

Vulnhallaには分析結果を閲覧・探索するための本格的なユーザーインターフェースが含まれています。

UIの起動

poetry run vulnhalla-ui

UIレイアウト

UIは上下2ペインのトップエリアと、下部のコントロールバーで構成されています：

トップエリア（左右並列、リサイズ可能）：

• 左パネル（問題一覧）

  • データテーブル表示：ID、Repo、Issue Name、File、LLM decision、Manual decision
  • 問題数とソートインジケーター
  • 下部の検索入力ボックス。入力に応じてリアルタイムフィルタリング（大文字小文字区別なし）

• 右パネル（詳細）

  • LLM判定セクション：LLMの分類（True Positive、False Positive、Needs More Data）
  • メタデータセクション：問題名、リポジトリ、ファイル、行、タイプ、関数名
  • コードセクション：
    • 📌 初期コードコンテキスト（LLMが見た最初のコードスニペット）
    • 📥 追加コード（LLMが会話中に要求したコード） - 追加コードがある場合のみ表示
    • 脆弱行を赤色でハイライト
  • サマリーセクション：LLMの最終回答/判定
  • 手動判定セレクト：下部のドロップダウンで手動判定を設定（True Positive、False Positive、Uncertain、Not Set）

下部コントロールバー：

• 言語：C（現時点で唯一サポートされている言語）
• LLM判定フィルタードロップダウン：すべて、True Positive、False Positive、Needs more Info to decide
• アクションボタン：リフレッシュ、分析実行
• キーバインドヘルプテキスト

キーバインド

• ↑/↓ - 問題一覧を移動（1行ずつ）
• Tab / Shift+Tab - パネル間でフォーカスを切り替え
• Enter - 選択した問題の詳細を表示
• / - 検索入力ボックスにフォーカス（左パネル）
• Esc - 検索をクリアし、問題テーブルにフォーカスを戻す
• r - 結果をディスクから再読み込み
• [ / ] - 左右パネルのサイズを調整（分割位置の変更）
• q - アプリケーションを終了

インタラクティブ機能

カラムソート

• 任意のカラムヘッダーをクリックすると、そのカラムでソート
• デフォルトソート：リポジトリ（昇順）、次にID（昇順）

リサイズ可能なパネル

• 問題一覧と詳細パネルの間の仕切りはドラッグ可能
• マウス：仕切りをクリック＆ドラッグしてリサイズ
• キーボード：[ で仕切りを左へ、] で右へ移動
• 分割位置はセッション中保持されます

📊 出力構造

パイプライン実行後、結果は output/results/<LANG>/<ISSUE_TYPE>/ に整理されます：

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # 元のCodeQL問題データ
├── 1_final.json    # LLM会話と分類
├── 2_raw.json
├── 2_final.json
└── ...

各 *_final.json には以下が含まれます：

• LLMの会話全体（システムプロンプト、ユーザーメッセージ、アシスタント応答、ツールコール）
• 最終ステータスコード（1337 = 脆弱、1007 = 安全、7331/3713 = 情報不足）

各 *_raw.json には以下が含まれます：

• 元のCodeQL問題データ
• 関数コンテキスト
• データベースパス（組織/リポジトリ情報を含む：output/databases/<LANG>/<ORG>/<REPO>）
• 問題の場所

🛠 トラブルシューティング

• CodeQL CLIが見つからない場合：
  .env ファイルの CODEQL_PATH にCodeQL実行ファイルのフルパスを設定してください。 Windowsの場合：パスは .cmd で終わる必要があります（例：C:\path\to\codeql\codeql.cmd）。

• GitHubのレート制限に引っかかる場合：
  .env ファイルに GITHUB_TOKEN を設定してください（トークンは https://github.com/settings/tokens から取得）。

• LLMの問題が発生する場合：
  .env ファイルのAPIキーが選択したプロバイダと一致しているか確認してください。

• UIでインポートエラーが発生する場合：
  プロジェクトルートディレクトリから実行していることを確認するか、パス設定を自動処理する python examples/ui_example.py を使用してください。

⚙️ 設定リファレンス

環境変数

すべての設定は .env ファイルの環境変数で管理されます。以下が完全なリファレンスです：

必須変数

プロバイダ固有の必須変数

OpenAI:

Azure OpenAI:

Gemini (Google):

AWS Bedrock:

* 認証方法：AWS_PROFILE または AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY（＋必要に応じて AWS_SESSION_TOKEN）を使用します。

Bedrock .env の例（SSO）：

PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=your-profile

⚠️ 前提条件：

• Bedrockモデルの呼び出し権限を持つAWS認証情報（SSO、IAMプロファイル、アクセスキー）が設定されている必要があります
• SSOユーザー向け： Vulnhalla使用前に aws sso login --profile your-profile を実行してください

🔧 重要 - モデル選択： Bedrockモデルを選択する際は、ツール呼び出し/関数呼び出しに対応していることを確認してください（すべてのBedrockモデルが対応しているわけではありません）。ツール呼び出しはVulnhallaの分析フローの重要な部分であり、互換性のあるモデルを選択することで機能性と結果に大きな違いが生じます。対応モデル：Claude 3.x、Mistral、Cohere Command R など。

オプション変数

⚠️ 重要： LLM_TEMPERATURE や LLM_TOP_P は、影響を完全に理解している場合を除き、値を上げないでください。低い値はモデルを安定・決定論的に保ち、セキュリティ分析には重要です。高い値はモデルの一貫性を損ない、創造的になったり結果を幻覚する可能性があります。

📝 注： 追加設定例については、プロジェクトルートの .env.example ファイルを参照してください。

設定の検証

Vulnhallaは起動時に設定を検証します。必須変数が欠けていたり無効な場合、何を修正すべきか明確なエラーメッセージが表示されます。

よくある検証エラー：

• 選択したプロバイダのAPIキーがない
• 無効なプロバイダ名（PROVIDER でサポートされている値を確認）
• Azureエンドポイントの欠如（Azureプロバイダに必須）
• AWS認証情報またはリージョンの欠如（Bedrockプロバイダに必須）
• 無効なCodeQLパス（CODEQL_PATH が設定されているがファイルが存在しない場合）

📝 ステータスコード

LLMは以下のステータスコードを使用します：

• 1337：セキュリティ脆弱性を検出（True Positive）
• 1007：コードは安全、脆弱性なし（False Positive）
• 7331：セキュリティ検証にはさらなるコード/情報が必要
• 3713：セキュリティ問題ではない可能性が高いが、さらなる情報が必要（7331と併用）

UIではこれらを次のように表示します：

• 1337 → "True Positive"
• 1007 → "False Positive"
• 7331 または 3713 → "Needs More Data"

🔧 開発

テストの実行

このプロジェクトにはpytestを使用した基本的なテスト基盤が含まれています：

# すべてのテストを実行
poetry run pytest

# 詳細出力で実行
poetry run pytest -v

テストスイートには、テスト基盤が正しくセットアップされていることを確認するスモークテストが含まれています。

型チェック

プロジェクトはmypyを使用した静的型チェックを行っています：

poetry run mypy src

型チェックの設定は pyproject.toml の [tool.mypy] にあります。 設定は保守的なベースラインを使用し、モジュールごとのオーバーライドにより段階的な導入を可能にしています。

プロジェクト依存関係

依存関係は pyproject.toml でPoetryにより管理されています：

• requests - GitHub APIへのHTTPリクエスト
• pySmartDL - CodeQLデータベースのスマートダウンロードマネージャー
• litellm - 複数プロバイダをサポートする統合LLMインターフェース
• python-dotenv - 環境変数管理
• PyYAML - CodeQLパックファイルのYAML解析
• textual - ターミナルUIフレームワーク
• pytest - テストフレームワーク（開発依存）
• mypy - 静的型チェッカー（開発依存）

CodeQLクエリ

CodeQLクエリは data/queries/<LANG>/ に整理されています：

• issues/ - セキュリティ問題検出クエリ
• tools/ - ヘルパークエリ（関数ツリー、クラス、グローバル変数、マクロ）

各ディレクトリにはCodeQLパックを定義する qlpack.yml ファイルが含まれています。

📄 ライセンス

Copyright (c) 2025 CyberArk Software Ltd. All rights reserved.

このリポジトリはApache License, Version 2.0の下でライセンスされています。詳細は LICENSE.txt をご覧ください。

🤝 貢献

このリポジトリへのあらゆる種類の貢献を歓迎します。開始方法と開発ワークフローの説明については、貢献ガイドをご覧ください。

行動規範

行動規範を読み、従ってください。すべての貢献者にとって歓迎的で包括的な環境を提供することに取り組んでいます。

📧 お問い合わせ

機能リクエストやプロジェクトに関する問題がある場合は、GitHub Issuesからお気軽にお問い合わせください。