neuralprogram/qlcoder# Estrutura Agêntica para Sintetizar Consultas CodeQL
Framework Agêntico para Sintetizar Consultas CodeQL
QLCoder é um framework para usar LLMs na síntese de consultas CodeQL de ponta a ponta para detecção de vulnerabilidades. Dados os metadados de uma CVE existente, um LLM e um agente de codificação, o QLCoder sintetiza iterativamente uma consulta CodeQL para detectar a CVE existente. A consulta inicial é um template de consulta de caminho CodeQL preenchido por uma AST extraída do diff. Durante a síntese da consulta, o agente de codificação tem acesso a ferramentas para interagir com um banco de dados RAG e o servidor de linguagem CodeQL. Posteriormente, a consulta pode ser usada para análise multivariante, testes de regressão ou como orientação para escrever consultas CodeQL.
Nota - No artigo, foi usada a versão 2.22.2 do CodeQL. No entanto, qualquer versão (e linguagem) pode ser usada. O QLCoder armazena os pacotes QL da versão local do CodeQL no banco de dados vetorial. Os caminhos são configurados em .env.
Baixe uma versão apropriada do bundle de ações do CodeQL na página de releases do CodeQL Action.
Para a versão mais recente: Visite o último release e baixe o bundle apropriado para o seu SO:
codeql-bundle-osx64.tar.gz para macOScodeql-bundle-linux64.tar.gz para LinuxPara uma versão específica (ex.: 2.22.2):
Vá para a página de releases do CodeQL Action, encontre o release marcado como codeql-bundle-v2.22.2 e baixe o bundle apropriado para a sua plataforma.
Extraia para ~/codeql (ou outro caminho — atualize CODEQL_HOME em .env de acordo):
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
Clone o servidor MCP do CodeQL LSP e compile-o.
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
Preencha sua chave de API e os caminhos do CodeQL em .env:
ANTHROPIC_API_KEY=...
# Os caminhos dos pacotes QL dependem da sua versão do CodeQL.
# Encontre os números de versão com:
# ls ~/codeql/qlpacks/codeql/java-queries/ → use para SECURITY_QLPACK_PATH
# ls ~/codeql/qlpacks/codeql/java-all/ → use para 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
Em seguida, inicie o aplicativo QLCoder e o ChromaDB:
docker compose up -d
A CVE deve estar listada em data/project_info.csv. Isso clona o repositório no commit com bug e gera o diff da correção.
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# ou várias de uma vez:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# processar CVEs de um arquivo (um ID de CVE por linha)
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# processar todas as CVEs
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# forçar a regeneração de diffs existentes
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Os bancos de dados são criados com --build-mode=none — nenhuma toolchain de build é necessária.
# para construir os bancos de dados CodeQL de uma CVE específica
docker compose run --rm app python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
Isso cria cves/CVE-2025-27818/CVE-2025-27818-vul e cves/CVE-2025-27818/CVE-2025-27818-fix.
# para construir os bancos de dados CodeQL de todos os repositórios de CVEs obtidos
docker compose run --rm app python3 scripts/build_codeql_dbs.py
Execute estes scripts para popular o banco de dados vetorial. codeql_docs_fetcher.py e cwe_fetcher.py são configurações únicas; cves_fetcher.py deve ser executado novamente após adicionar novas CVEs.
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
Nota - No artigo, foi usada a versão 2.22.2 do CodeQL. No entanto, qualquer versão (e linguagem) pode ser usada. O QLCoder armazena os pacotes QL da versão local do CodeQL no banco de dados vetorial. Os caminhos são configurados em .env.
Baixe uma versão apropriada do bundle de ações do CodeQL na página de releases do CodeQL Action.
Para a versão mais recente: Visite o último release e baixe o bundle apropriado para o seu SO:
codeql-bundle-linux64.tar.gz para LinuxPara uma versão específica (ex.: 2.22.2):
Vá para a página de releases do CodeQL Action, encontre o release marcado como codeql-bundle-v2.22.2 e baixe o bundle apropriado para a sua plataforma.
Após o download, extraia o arquivo no diretório raiz do projeto:
tar -xzf codeql-bundle-<platform>.tar.gz
Isso deve criar um subdiretório codeql/ com o executável codeql dentro.
Adicione o caminho deste executável à sua variável de ambiente PATH:
export PATH="$PWD/codeql:$PATH"
Clone o servidor MCP do CodeQL LSP e compile-o.
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
.envcp .env.example .env
Preencha sua chave de API e os caminhos do CodeQL em .env:
ANTHROPIC_API_KEY=...
CODEQL_HOME=~/codeql
CODEQL_LSP_MCP_HOME=~/codeql-lsp-mcp
# Os caminhos dos pacotes QL dependem da sua versão do CodeQL.
# Encontre os números de versão com:
# ls ~/codeql/qlpacks/codeql/java-queries/ → use para SECURITY_QLPACK_PATH
# ls ~/codeql/qlpacks/codeql/java-all/ → use para 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
A CVE deve estar listada em data/project_info.csv. Isso clona o repositório no commit com bug e gera o diff da correção.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# ou várias de uma vez:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# processar CVEs de um arquivo (um ID de CVE por linha)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# processar todas as CVEs
python3 scripts/get_cve_repos.py --all
# forçar a regeneração de diffs existentes
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Os bancos de dados são criados com --build-mode=none — nenhuma toolchain de build é necessária.
# para construir os bancos de dados CodeQL de uma CVE específica
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# para construir os bancos de dados CodeQL de todos os repositórios de CVEs obtidos
python3 scripts/build_codeql_dbs.py
Isso cria cves/CVE-2025-27818/CVE-2025-27818-vul e cves/CVE-2025-27818/CVE-2025-27818-fix.
Inicie o ChromaDB em um terminal separado e mantenha-o em execução para esta etapa e sempre que executar o agente.
chroma run --path data/chroma_db
Execute estes scripts para popular o banco de dados vetorial. codeql_docs_fetcher.py e cwe_fetcher.py são configurações únicas; cves_fetcher.py deve ser executado novamente após adicionar novas CVEs.
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
Após seguir as instruções de Instalação, o início rápido percorre um exemplo de síntese de uma consulta CodeQL para uma determinada CVE.
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
Opções adicionais podem ser passadas após o ID da CVE:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
Abaixo estão as configurações disponíveis para o QLCoder.
Timeout: Cada janela de contexto do agente tem um timeout de shell padrão (ex.: 300s). Aumente o timeout no método de execução do backend relevante, se necessário, ao encontrar erros de "Context window failed".
Nota: O suporte a agentes é testado contra as versões listadas em Ambiente do Artigo. Versões mais novas de agentes de codificação podem exigir atualizações no backend. PRs adicionando suporte para versões mais novas, outros agentes de codificação e mais modelos são bem-vindos!
Modelos (--model): sonnet-4 (padrão), sonnet-4.5 (Claude); gemini-2.5-pro, gemini-2.5-flash (Gemini); gpt-5 (Codex)
Agentes (--agent): claude (padrão), gemini (Gemini CLI), codex (modelos OpenAI e modelos open source)
Modos de ablação (--ablation-mode):
| Modo | Descrição | Agentes Disponíveis |
|---|---|---|
full | Todas as ferramentas QLCoder habilitadas (padrão) e extração de AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_tools | Sem ferramentas e sem extração de AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_lsp | Sem ferramentas CodeQL LSP | Claude Code |
no_docs | Sem recuperação de documentação CodeQL | Claude Code |
no_ast | Sem extração de AST do diff | Claude Code |
Por padrão, definimos o esforço de raciocínio como médio. Você pode substituir isso em codex_backend.py.
Quando o Chroma não é usado para buscar a descrição da CVE, uma descrição pré-buscada é injetada diretamente no prompt via task.cve_description. Use scripts/cves_fetcher.py para popular um arquivo JSON local de descrições:
python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json
O arquivo mapeia IDs de CVE para suas strings de descrição de CVE e é anexado a cada execução (entradas existentes são ignoradas). Ao executar com --ablation-mode no_tools ou --ablation-mode no_docs, o QLCoder carrega automaticamente este arquivo e define task.cve_description para a CVE que está sendo analisada.
As seguintes ferramentas são recomendadas ao usar o QLCoder:
Excluir coleções de execuções do QLCoder - para limpar o Chroma, aqui está um script para excluir coleções do uso do QLCoder.
chromadb-ops - ferramenta CLI para inspecionar e manter o Chroma.
# útil para limpar o chroma
chops db clean data/chroma_db
Aqui estão exemplos de configurações MCP ao usar o QLCoder. A configuração deve ser semelhante a estes arquivos no workspace do agente.
As seguintes versões foram usadas para produzir os resultados no artigo do QLCoder.
| Ferramenta | Versão |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
Aceitamos quaisquer contribuições, pull requests ou issues! Se você gostaria de contribuir, por favor abra um novo pull request ou issue. Sinta-se à vontade para assumir uma issue existente também.
QLCoder é um esforço colaborativo entre pesquisadores da Cornell University, Johns Hopkins University e University of Pennsylvania. Entre em contato conosco se tiver alguma dúvida.
Claire Wang - Estudante de Doutorado em Ciência da Computação na University of Pennsylvania
Ziyang Li - Professor na Johns Hopkins University
Saikat Dutta - Professor na Cornell University
Mayur Naik - Professor na University of Pennsylvania
Considere citar nosso artigo do 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},
}
Os seguintes são projetos afiliados aos autores do QLCoder. Sinta-se à vontade para conferi-los.