QLCoder

用于合成 CodeQL 查询的智能体框架

概述

QLCoder 迭代优化

QLCoder 是一个利用 LLM 合成端到端 CodeQL 查询以进行漏洞检测的框架。给定现有 CVE 的元数据、LLM 和编码智能体，QLCoder 会迭代地合成一个 CodeQL 查询来检测该现有 CVE。初始查询是一个由提取的 diff AST 填充的 CodeQL 路径查询模板。在合成查询的过程中，编码智能体可以访问与 RAG 数据库和 CodeQL 语言服务器交互的工具。之后，该查询可用于多变量分析、回归测试或作为编写 CodeQL 查询的指导。

安装

Docker（推荐）

步骤 1：安装 CodeQL

注意——论文中使用的是 CodeQL 2.22.2 版本。不过，任何版本（和语言）都可以使用。QLCoder 会将本地 CodeQL 版本的 QL 包存储在向量数据库中。路径在 .env 中配置。

从 CodeQL Action 发布页面下载合适版本的 CodeQL Action 捆绑包。

对于最新版本： 访问最新发布并下载适合您操作系统的捆绑包：
- codeql-bundle-osx64.tar.gz 适用于 macOS
- codeql-bundle-linux64.tar.gz 适用于 Linux
对于特定版本（例如 2.22.2）： 前往 CodeQL Action 发布页面，找到标记为 codeql-bundle-v2.22.2 的发布版本，并下载适合您平台的捆绑包。

解压到 ~/codeql（或其他路径——相应地更新 .env 中的 CODEQL_HOME）：

tar -xzf codeql-bundle-<platform>.tar.gz -C ~/

步骤 2：安装 CodeQL LSP MCP 服务器

克隆 CodeQL LSP MCP 服务器并构建它。

git clone https://github.com/neuralprogram/codeql-lsp-mcp ~/codeql-lsp-mcp
cd ~/codeql-lsp-mcp
npm install
npm run build

步骤 3：配置并启动服务

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

步骤 4：获取 CVE 仓库

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（每行一个 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

步骤 5：创建 CodeQL 数据库

数据库使用 --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

步骤 6：填充 RAG 数据库

运行这些脚本以填充向量数据库。codeql_docs_fetcher.py 和 cwe_fetcher.py 是一次性设置；添加新的 CVE 后应重新运行 cves_fetcher.py。

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

原生安装（Linux）

步骤 1：安装 CodeQL

从 CodeQL Action 发布页面下载合适版本的 CodeQL Action 捆绑包。

对于最新版本： 访问最新发布并下载适合您操作系统的捆绑包：
- codeql-bundle-linux64.tar.gz 适用于 Linux
对于特定版本（例如 2.22.2）： 前往 CodeQL Action 发布页面，找到标记为 codeql-bundle-v2.22.2 的发布版本，并下载适合您平台的捆绑包。

下载后，在项目根目录中解压归档文件：

tar -xzf codeql-bundle-<platform>.tar.gz

这应该会创建一个包含可执行文件 codeql 的子目录 codeql/。

将此可执行文件的路径添加到您的 PATH 环境变量中：

export PATH="$PWD/codeql:$PATH"

步骤 2：安装 CodeQL LSP MCP 服务器

克隆 CodeQL LSP MCP 服务器并构建它。

git clone https://github.com/neuralprogram/codeql-lsp-mcp
cd codeql-lsp-mcp
npm install
npm run build

步骤 3：设置 Conda 环境

conda env create -f environment.yml
conda activate qlcoder

步骤 4：配置 `.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

步骤 5：获取 CVE 仓库

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（每行一个 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

步骤 6：创建 CodeQL 数据库

数据库使用 --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。

步骤 7：启动 ChromaDB

在单独的终端中启动 ChromaDB，并在本步骤以及运行智能体时保持其运行。

chroma run --path data/chroma_db

步骤 8：填充 RAG 数据库

运行这些脚本以填充向量数据库。codeql_docs_fetcher.py 和 cwe_fetcher.py 是一次性设置；添加新的 CVE 后应重新运行 cves_fetcher.py。

python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py

快速开始

按照安装说明操作后，快速开始将演示为给定 CVE 合成 CodeQL 查询的示例。

获取 CVE 仓库和 CVE 修复 diff。

python3 scripts/get_cve_repos.py --cve CVE-2025-27818

为该 CVE 创建 CodeQL 数据库。

python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818

填充或更新 RAG 数据库。

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 的可用配置。

超时： 每个智能体上下文窗口都有默认的 shell 超时时间（例如 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）：

模型特定说明（GPT-5）

默认情况下，我们将推理努力级别设置为中等。您可以在 codex_backend.py 中覆盖此设置。

无工具、无文档模式（论文特定）

当不使用 Chroma 获取 CVE 描述时，预获取的描述会通过 task.cve_description 直接注入到提示中。使用 scripts/cves_fetcher.py 填充本地 JSON 描述文件：

python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json

该文件将 CVE ID 映射到其 CVE 描述字符串，并在每次运行时追加（现有条目会被跳过）。当使用 --ablation-mode no_tools 或 --ablation-mode no_docs 运行时，QLCoder 会自动加载此文件并为正在分析的 CVE 设置 task.cve_description。

开发工具

使用 QLCoder 时推荐以下工具：

删除 QLCoder 运行产生的集合 - 用于清理 Chroma，这里有一个脚本可以删除使用 QLCoder 产生的集合。

chromadb-ops - 用于检查和维护 Chroma 的 CLI 工具。

# 用于清理 chroma
chops db clean data/chroma_db

示例

QLCoder 生成的查询示例

Java
C

QLCoder MCP 配置

以下是使用 QLCoder 时的 MCP 配置示例。配置应与智能体工作区中的这些文件类似。

论文环境

以下版本用于生成 QLCoder 论文中的结果。

工具	版本
CodeQL	2.22.2
Claude Code	1.0.120
Gemini CLI	0.6.0
Codex CLI	0.38.0

贡献

我们欢迎任何贡献、拉取请求或问题！如果您想贡献，请提交新的拉取请求或问题。也欢迎您接手现有的问题。

团队

QLCoder 是康奈尔大学、约翰霍普金斯大学和宾夕法尼亚大学研究人员之间的合作成果。如有任何问题，请随时联系我们。

Claire Wang - 宾夕法尼亚大学计算机科学博士生

Ziyang Li - 约翰霍普金斯大学教授

Saikat Dutta - 康奈尔大学教授

Mayur Naik - 宾夕法尼亚大学教授

引用

请考虑引用我们的 ICLR'26 论文：

@misc{wang2025qlcoderquerysynthesizerstatic,
      title={QLCoder: A Query Synthesizer For Static Analysis of Security Vulnerabilities}, 
      author={Claire Wang and Ziyang Li and Saikat Dutta and Mayur Naik},
      year={2025},
      eprint={2511.08462},
      archivePrefix={arXiv},
      primaryClass={cs.CR},
      url={https://arxiv.org/abs/2511.08462}, 
}

Arxiv 链接

关联项目

以下是与 QLCoder 作者相关的项目。欢迎查看。

IRIS - 将 LLM 识别的源/汇点附加到给定仓库的现有 CodeQL 安全查询中。QLCoder 是 IRIS 部分思想的扩展。Arxiv 链接
CWE-Bench-Java - 包含 CVE 元数据、仓库和源/汇点标签的 Java 安全漏洞基准。

`full`	启用所有 QLCoder 工具（默认）和 AST 提取	Claude Code、Codex（GPT、GPT-OSS）、Gemini
`no_tools`	无工具且无 AST 提取	Claude Code、Codex（GPT、GPT-OSS）、Gemini
`no_lsp`	无 CodeQL LSP 工具	Claude Code
`no_docs`	无 CodeQL 文档检索	Claude Code
`no_ast`	无 diff 的 AST 提取	Claude Code

qlcoder

最受欢迎

QLCoder

目录

概述

安装

Docker（推荐）

步骤 1：安装 CodeQL

步骤 2：安装 CodeQL LSP MCP 服务器

步骤 3：配置并启动服务

步骤 4：获取 CVE 仓库

步骤 5：创建 CodeQL 数据库

步骤 6：填充 RAG 数据库

原生安装（Linux）

步骤 1：安装 CodeQL

步骤 2：安装 CodeQL LSP MCP 服务器

步骤 3：设置 Conda 环境

步骤 4：配置 .env

步骤 5：获取 CVE 仓库

步骤 6：创建 CodeQL 数据库

步骤 7：启动 ChromaDB

步骤 8：填充 RAG 数据库

快速开始

使用方法

模型特定说明（GPT-5）

无工具、无文档模式（论文特定）

开发工具

示例

QLCoder 生成的查询示例

QLCoder MCP 配置

论文环境

贡献

团队

引用

关联项目

步骤 4：配置 `.env`