CodeQLクエリを合成するためのエージェント型フレームワーク
QLCoderは、LLMを使用して脆弱性検出のためのエンドツーエンドのCodeQLクエリを合成するためのフレームワークです。既存のCVEのメタデータ、LLM、およびコーディングエージェントが与えられると、QLCoderは既存のCVEを検出するためのCodeQLクエリを反復的に合成します。初期クエリは、抽出されたdiffのASTによって生成されたCodeQLパスクエリテンプレートです。クエリの合成中、コーディングエージェントはRAGデータベースおよびCodeQL言語サーバーとインターフェースするためのツールにアクセスできます。その後、クエリは多変量解析、回帰テスト、またはCodeQLクエリ作成のガイダンスに使用できます。
注 - 論文ではCodeQLバージョン2.22.2を使用しました。ただし、任意のバージョン（および言語）を使用できます。QLCoderはローカルのCodeQLバージョンのQLパックをベクターデータベースに保存します。パスは.envで設定されます。
CodeQL Action releases pageから適切なバージョンのCodeQL Actionバンドルをダウンロードしてください。
最新バージョンの場合: 最新リリースにアクセスし、お使いのOSに適したバンドルをダウンロードしてください:
codeql-bundle-osx64.tar.gzcodeql-bundle-linux64.tar.gz特定のバージョン（例: 2.22.2）の場合:
CodeQL Action releases pageにアクセスし、codeql-bundle-v2.22.2というタグが付いたリリースを見つけて、お使いのプラットフォームに適したバンドルをダウンロードしてください。
~/codeqlに展開します（または別のパス — それに応じて.envのCODEQL_HOMEを更新してください）:
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
CodeQL LSP MCP serverをクローンしてビルドします。
git clone https://github.com/neuralprogram/codeql-lsp-mcp ~/codeql-lsp-mcp
cd ~/codeql-lsp-mcp
npm install
npm run build
cp .env.example .env
echo "APP_UID=$(id -u)" >> .env
echo "APP_GID=$(id -g)" >> .env
.envにAPIキーとCodeQLパスを入力してください:
ANTHROPIC_API_KEY=...
# QLパックのパスはCodeQLのバージョンによって異なります。
# バージョン番号は以下で確認できます:
# ls ~/codeql/qlpacks/codeql/java-queries/ → SECURITY_QLPACK_PATHに使用
# ls ~/codeql/qlpacks/codeql/java-all/ → LIBRARY_QLPACK_PATHに使用
SECURITY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-queries/<version>/Security/CWE
LIBRARY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-all/<version>/semmle/code/java
次にQLCoderアプリとChromaDBを起動します:
docker compose up -d
CVEはdata/project_info.csvにリストされている必要があります。これにより、バグのあるコミットでリポジトリがクローンされ、修正diffが生成されます。
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# または複数を一度に:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# ファイルからCVEを処理（1行に1つのCVE ID）
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# すべてのCVEを処理
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# 既存のdiffを強制的に再生成
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
データベースは--build-mode=noneで作成されます — ビルドツールチェーンは不要です。
# 特定のCVEのCodeQLデータベースをビルドする場合
docker compose run --rm app python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
これにより、cves/CVE-2025-27818/CVE-2025-27818-vulとcves/CVE-2025-27818/CVE-2025-27818-fixが作成されます。
# 取得したすべてのCVEリポジトリのCodeQLデータベースをビルドする場合
docker compose run --rm app python3 scripts/build_codeql_dbs.py
これらのスクリプトを実行してベクターデータベースを構築します。codeql_docs_fetcher.pyとcwe_fetcher.pyは一度だけのセットアップです。cves_fetcher.pyは新しいCVEを追加した後に再実行する必要があります。
docker compose run --rm app python3 scripts/codeql_docs_fetcher.py
docker compose run --rm app python3 scripts/cwe_fetcher.py
docker compose run --rm app python3 scripts/cves_fetcher.py
注 - 論文ではCodeQLバージョン2.22.2を使用しました。ただし、任意のバージョン（および言語）を使用できます。QLCoderはローカルのCodeQLバージョンのQLパックをベクターデータベースに保存します。パスは.envで設定されます。
CodeQL Action releases pageから適切なバージョンのCodeQL Actionバンドルをダウンロードしてください。
最新バージョンの場合: 最新リリースにアクセスし、お使いのOSに適したバンドルをダウンロードしてください:
codeql-bundle-linux64.tar.gz特定のバージョン（例: 2.22.2）の場合:
CodeQL Action releases pageにアクセスし、codeql-bundle-v2.22.2というタグが付いたリリースを見つけて、お使いのプラットフォームに適したバンドルをダウンロードしてください。
ダウンロード後、プロジェクトのルートディレクトリでアーカイブを展開します:
tar -xzf codeql-bundle-<platform>.tar.gz
これにより、実行可能ファイルcodeqlを含むサブディレクトリcodeql/が作成されます。
この実行可能ファイルのパスをPATH環境変数に追加します:
export PATH="$PWD/codeql:$PATH"
CodeQL LSP MCP serverをクローンしてビルドします。
git clone https://github.com/neuralprogram/codeql-lsp-mcp
cd codeql-lsp-mcp
npm install
npm run build
conda env create -f environment.yml
conda activate qlcoder
.envの設定cp .env.example .env
.envにAPIキーとCodeQLパスを入力してください:
ANTHROPIC_API_KEY=...
CODEQL_HOME=~/codeql
CODEQL_LSP_MCP_HOME=~/codeql-lsp-mcp
# QLパックのパスはCodeQLのバージョンによって異なります。
# バージョン番号は以下で確認できます:
# ls ~/codeql/qlpacks/codeql/java-queries/ → SECURITY_QLPACK_PATHに使用
# ls ~/codeql/qlpacks/codeql/java-all/ → LIBRARY_QLPACK_PATHに使用
SECURITY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-queries/<version>/Security/CWE
LIBRARY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-all/<version>/semmle/code/java
CVEはdata/project_info.csvにリストされている必要があります。これにより、バグのあるコミットでリポジトリがクローンされ、修正diffが生成されます。
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# または複数を一度に:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# ファイルからCVEを処理（1行に1つのCVE ID）
python3 scripts/get_cve_repos.py --cve-file cves.txt
# すべてのCVEを処理
python3 scripts/get_cve_repos.py --all
# 既存のdiffを強制的に再生成
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
データベースは--build-mode=noneで作成されます — ビルドツールチェーンは不要です。
# 特定のCVEのCodeQLデータベースをビルドする場合
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# 取得したすべてのCVEリポジトリのCodeQLデータベースをビルドする場合
python3 scripts/build_codeql_dbs.py
これにより、cves/CVE-2025-27818/CVE-2025-27818-vulとcves/CVE-2025-27818/CVE-2025-27818-fixが作成されます。
別のターミナルでChromaDBを起動し、このステップとエージェント実行中は起動したままにしてください。
chroma run --path data/chroma_db
これらのスクリプトを実行してベクターデータベースを構築します。codeql_docs_fetcher.pyとcwe_fetcher.pyは一度だけのセットアップです。cves_fetcher.pyは新しいCVEを追加した後に再実行する必要があります。
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
インストール手順に従った後、クイックスタートでは特定のCVEに対するCodeQLクエリの合成例を説明します。
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
python3 scripts/cves_fetcher.py
./run_cve.sh CVE-2025-27818
CVE IDの後に追加のオプションを渡すことができます:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
以下はQLCoderで利用可能な設定です。
タイムアウト: 各エージェントのコンテキストウィンドウにはデフォルトのシェルタイムアウト（例: 300秒）があります。「Context window failed」エラーが発生した場合は、必要に応じて関連するバックエンドの実行メソッドでタイムアウトを増やしてください。
注: エージェントのサポートは論文環境に記載されているバージョンに対してテストされています。新しいバージョンのコーディングエージェントではバックエンドの更新が必要になる場合があります。新しいバージョン、他のコーディングエージェント、およびより多くのモデルのサポートを追加するPRは歓迎します!
モデル（--model）: sonnet-4（デフォルト）、sonnet-4.5（Claude）; gemini-2.5-pro、gemini-2.5-flash（Gemini）; gpt-5（Codex）
エージェント（--agent）: claude（デフォルト）、gemini（Gemini CLI）、codex（OpenAIモデルおよびオープンソースモデル）
アブレーションモード（--ablation-mode）: