詳細な研究背景やVulnhallaの動機については、公式CyberArk脅威研究ブログ記事をご覧ください：
Vulnhalla: Picking the True Vulnerabilities from the CodeQL Haystack
開始する前に、以下を用意してください：
Python 3.10 – 3.13（Python 3.11 または 3.12 推奨）
CodeQL CLI
codeql がPATHに含まれていることを確認するか、後述のステップ2で .env にパスを設定します（オプション）GitHub APIトークン
LLM APIキー
すべての設定は単一のファイル .env にまとめられています。
git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla
.env.example を .env にコピー：cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)
.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）、必須/オプション変数、詳細な例が含まれています。
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
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
# 特定のリポジトリを分析（例）
poetry run vulnhalla redis/redis
# データベースが既に存在しても再ダウンロード
poetry run vulnhalla redis/redis --force
# ヘルプを表示
poetry run vulnhalla --help
これにより自動的に：
output/results/ に保存すでにディスク上に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
Vulnhallaには分析結果を閲覧・探索するための本格的なユーザーインターフェースが含まれています。
poetry run vulnhalla-ui
UIは上下2ペインのトップエリアと、下部のコントロールバーで構成されています：
トップエリア（左右並列、リサイズ可能）：
左パネル（問題一覧）
右パネル（詳細）
下部コントロールバー：
↑/↓ - 問題一覧を移動（1行ずつ）Tab / Shift+Tab - パネル間でフォーカスを切り替えEnter - 選択した問題の詳細を表示/ - 検索入力ボックスにフォーカス（左パネル）Esc - 検索をクリアし、問題テーブルにフォーカスを戻すr - 結果をディスクから再読み込み[ / ] - 左右パネルのサイズを調整（分割位置の変更）q - アプリケーションを終了[ で仕切りを左へ、] で右へ移動パイプライン実行後、結果は 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 には以下が含まれます：
各 *_raw.json には以下が含まれます：
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 ファイルの環境変数で管理されます。以下が完全なリファレンスです：
| 変数 | 必須対象 | 説明 |
|---|---|---|
CODEQL_PATH | すべて | CodeQL実行ファイルへのパス。CodeQLがPATHにあればデフォルトは codeql。PATHにない場合はフルパスを使用（Windowsの場合は例：C:\path\to\codeql\codeql.cmd） |
PROVIDER | すべて | LLMプロバイダ：openai、azure、gemini、bedrock、anthropic、mistral、groq、openrouter、ollama など |
MODEL | すべて | モデル名（例：gpt-4o、gpt-4-turbo、gemini-2.5-flash） |
OpenAI:
| 変数 | 説明 |
|---|---|
OPENAI_API_KEY | OpenAI APIキー（platform.openai.comから取得） |
Azure OpenAI:
| 変数 | 説明 |
|---|---|
AZURE_OPENAI_API_KEY または AZURE_API_KEY | Azure OpenAI APIキー |
AZURE_OPENAI_ENDPOINT または AZURE_API_BASE | Azure OpenAIエンドポイントURL（例：https://your-resource.openai.azure.com） |
AZURE_OPENAI_API_VERSION または AZURE_API_VERSION | APIバージョン（デフォルト：2024-08-01-preview） |
Gemini (Google):
| 変数 | 説明 |
|---|---|
GOOGLE_API_KEY | Google APIキー（Google AI Studioから取得） |