neuralprogram/qlcoderAgente Framework para Sintetizar Consultas CodeQL
Framework agéntico para sintetizar consultas CodeQL
QLCoder es un framework para usar LLMs con el fin de sintetizar consultas CodeQL de extremo a extremo para la detección de vulnerabilidades. Dados los metadatos de un CVE existente, un LLM y un agente de codificación, QLCoder sintetiza iterativamente una consulta CodeQL para detectar el CVE existente. La consulta inicial es una plantilla de consulta de ruta CodeQL poblada por un AST extraído del diff. Mientras sintetiza la consulta, el agente de codificación tiene acceso a herramientas para interactuar con una base de datos RAG y el servidor de lenguaje CodeQL. Posteriormente, la consulta puede utilizarse para análisis multivariante, pruebas de regresión o como guía para escribir consultas CodeQL.
Nota: en el artículo se utilizó la versión 2.22.2 de CodeQL. Sin embargo, se puede usar cualquier versión (e idioma). QLCoder almacena los paquetes QL de la versión local de CodeQL en la base de datos vectorial. Las rutas se configuran en .env.
Descargue una versión adecuada del paquete CodeQL Action desde la página de lanzamientos de CodeQL Action.
Para la versión más reciente: Visite el último lanzamiento y descargue el paquete adecuado para su sistema operativo:
codeql-bundle-osx64.tar.gz para macOScodeql-bundle-linux64.tar.gz para LinuxPara una versión específica (p. ej., 2.22.2):
Vaya a la página de lanzamientos de CodeQL Action, busque el lanzamiento etiquetado codeql-bundle-v2.22.2 y descargue el paquete adecuado para su plataforma.
Extraiga a ~/codeql (u otra ruta — actualice CODEQL_HOME en .env en consecuencia):
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
Clone el servidor MCP de CodeQL LSP y compílelo.
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
Complete su clave API y las rutas de CodeQL en .env:
ANTHROPIC_API_KEY=...
# Las rutas de los paquetes QL dependen de su versión de CodeQL.
# Encuentre los números de versión con:
# 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
Luego inicie la aplicación QLCoder y ChromaDB:
docker compose up -d
El CVE debe estar listado en data/project_info.csv. Esto clona el repositorio en el commit con el error y genera el diff de la corrección.
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# o varios a la vez:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# procesar CVEs desde un archivo (un ID de CVE por línea)
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# procesar todos los CVEs
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# forzar la regeneración de diffs existentes
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Las bases de datos se crean con --build-mode=none — no se requiere cadena de herramientas de compilación.
# para compilar las bases de datos CodeQL de un CVE específico
docker compose run --rm app python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
Esto crea cves/CVE-2025-27818/CVE-2025-27818-vul y cves/CVE-2025-27818/CVE-2025-27818-fix.
# para compilar las bases de datos CodeQL de todos los repositorios de CVEs obtenidos
docker compose run --rm app python3 scripts/build_codeql_dbs.py
Ejecute estos scripts para poblar la base de datos vectorial. codeql_docs_fetcher.py y cwe_fetcher.py son de configuración única; cves_fetcher.py debe volver a ejecutarse después de agregar nuevos 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: en el artículo se utilizó la versión 2.22.2 de CodeQL. Sin embargo, se puede usar cualquier versión (e idioma). QLCoder almacena los paquetes QL de la versión local de CodeQL en la base de datos vectorial. Las rutas se configuran en .env.
Descargue una versión adecuada del paquete CodeQL Action desde la página de lanzamientos de CodeQL Action.
Para la versión más reciente: Visite el último lanzamiento y descargue el paquete adecuado para su sistema operativo:
codeql-bundle-linux64.tar.gz para LinuxPara una versión específica (p. ej., 2.22.2):
Vaya a la página de lanzamientos de CodeQL Action, busque el lanzamiento etiquetado codeql-bundle-v2.22.2 y descargue el paquete adecuado para su plataforma.
Después de descargar, extraiga el archivo en el directorio raíz del proyecto:
tar -xzf codeql-bundle-<platform>.tar.gz
Esto debería crear un subdirectorio codeql/ con el ejecutable codeql dentro.
Agregue la ruta de este ejecutable a su variable de entorno PATH:
export PATH="$PWD/codeql:$PATH"
Clone el servidor MCP de CodeQL LSP y compílelo.
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
Complete su clave API y las rutas de CodeQL en .env:
ANTHROPIC_API_KEY=...
CODEQL_HOME=~/codeql
CODEQL_LSP_MCP_HOME=~/codeql-lsp-mcp
# Las rutas de los paquetes QL dependen de su versión de CodeQL.
# Encuentre los números de versión con:
# 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
El CVE debe estar listado en data/project_info.csv. Esto clona el repositorio en el commit con el error y genera el diff de la corrección.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# o varios a la vez:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# procesar CVEs desde un archivo (un ID de CVE por línea)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# procesar todos los CVEs
python3 scripts/get_cve_repos.py --all
# forzar la regeneración de diffs existentes
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Las bases de datos se crean con --build-mode=none — no se requiere cadena de herramientas de compilación.
# para compilar las bases de datos CodeQL de un CVE específico
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# para compilar las bases de datos CodeQL de todos los repositorios de CVEs obtenidos
python3 scripts/build_codeql_dbs.py
Esto crea cves/CVE-2025-27818/CVE-2025-27818-vul y cves/CVE-2025-27818/CVE-2025-27818-fix.
Inicie ChromaDB en una terminal separada y manténgala en ejecución para este paso y siempre que ejecute el agente.
chroma run --path data/chroma_db
Ejecute estos scripts para poblar la base de datos vectorial. codeql_docs_fetcher.py y cwe_fetcher.py son de configuración única; cves_fetcher.py debe volver a ejecutarse después de agregar nuevos CVEs.
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
Después de seguir las instrucciones de instalación, el inicio rápido recorre un ejemplo de síntesis de una consulta CodeQL para un CVE determinado.
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
Se pueden pasar opciones adicionales después del ID del CVE:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
A continuación se muestran las configuraciones disponibles para QLCoder.
Tiempo de espera: Cada ventana de contexto del agente tiene un tiempo de espera de shell predeterminado (p. ej., 300 s). Aumente el tiempo de espera en el método de ejecución del backend correspondiente si es necesario cuando encuentre errores de "Context window failed".
Nota: El soporte de agentes se prueba con las versiones listadas en Entorno del artículo. Las versiones más nuevas de los agentes de codificación pueden requerir actualizaciones en el backend. ¡Se aceptan PRs que agreguen soporte para versiones más nuevas, otros agentes de codificación y más modelos!
Modelos (--model): sonnet-4 (predeterminado), sonnet-4.5 (Claude); gemini-2.5-pro, gemini-2.5-flash (Gemini); gpt-5 (Codex)
Agentes (--agent): claude (predeterminado), gemini (Gemini CLI), codex (modelos de OpenAI y modelos de código abierto)
Modos de ablación (--ablation-mode):
| Modo | Descripción | Agentes disponibles |
|---|---|---|
full | Todas las herramientas de QLCoder habilitadas (predeterminado) y extracción de AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_tools | Sin herramientas y sin extracción de AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_lsp | Sin herramientas de CodeQL LSP | Claude Code |
no_docs | Sin recuperación de documentación de CodeQL | Claude Code |
no_ast | Sin extracción de AST del diff | Claude Code |
De forma predeterminada, establecemos el esfuerzo de razonamiento en medio. Puede anularlo en codex_backend.py.
Cuando Chroma no se usa para obtener la descripción del CVE, se inyecta una descripción precargada directamente en el prompt a través de task.cve_description. Use scripts/cves_fetcher.py para poblar un archivo JSON local de descripciones:
python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json
El archivo asigna los IDs de CVE a sus cadenas de descripción de CVE y se agrega en cada ejecución (las entradas existentes se omiten). Al ejecutar con --ablation-mode no_tools o --ablation-mode no_docs, QLCoder carga automáticamente este archivo y establece task.cve_description para el CVE que se está analizando.
Se recomiendan las siguientes herramientas al usar QLCoder:
Eliminar colecciones de ejecuciones de QLCoder - para limpiar Chroma, aquí hay un script para eliminar colecciones del uso de QLCoder.
chromadb-ops - herramienta CLI para inspeccionar y mantener Chroma.
# útil para limpiar chroma
chops db clean data/chroma_db
Aquí hay ejemplos de configuraciones MCP al usar QLCoder. La configuración debería ser similar a estos archivos en el espacio de trabajo del agente.
Las siguientes versiones se utilizaron para producir los resultados en el artículo de QLCoder.
| Herramienta | Versión |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
¡Agradecemos cualquier contribución, pull request o issue! Si desea contribuir, por favor presente un nuevo pull request o issue. También puede tomar un issue existente.
QLCoder es un esfuerzo colaborativo entre investigadores de la Universidad de Cornell, la Universidad Johns Hopkins y la Universidad de Pensilvania. Por favor, contáctenos si tiene alguna pregunta.
Claire Wang - Estudiante de doctorado en Ciencias de la Computación en la Universidad de Pensilvania
Ziyang Li - Profesor en la Universidad Johns Hopkins
Saikat Dutta - Profesor en la Universidad de Cornell
Mayur Naik - Profesor en la Universidad de Pensilvania
Considere citar nuestro artículo de 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},
}
Los siguientes son proyectos afiliados con los autores de QLCoder. No dude en revisarlos.