neuralprogram/qlcoderFramework agente per la sintesi di query CodeQL
Framework agentico per la sintesi di query CodeQL
QLCoder è un framework per l'utilizzo di LLM nella sintesi di query CodeQL end-to-end per il rilevamento di vulnerabilità. Data la metadati di una CVE esistente, un LLM e un agente di codifica, QLCoder sintetizza iterativamente una query CodeQL per rilevare la CVE esistente. La query iniziale è un template di query di percorso CodeQL popolato da un AST estratto dal diff. Durante la sintesi della query, l'agente di codifica ha accesso a strumenti per interfacciarsi con un database RAG e con il language server CodeQL. Successivamente, la query può essere utilizzata per analisi multivariante, test di regressione o come guida per la scrittura di query CodeQL.
Nota - Nell'articolo è stata utilizzata la versione 2.22.2 di CodeQL. Tuttavia, è possibile utilizzare qualsiasi versione (e linguaggio). QLCoder memorizza i QL pack della versione locale di CodeQL nel database vettoriale. I percorsi sono configurati in .env.
Scarica una versione appropriata del bundle CodeQL Action dalla pagina delle release di CodeQL Action.
Per la versione più recente: Visita la release più recente e scarica il bundle appropriato per il tuo sistema operativo:
codeql-bundle-osx64.tar.gz per macOScodeql-bundle-linux64.tar.gz per LinuxPer una versione specifica (es. 2.22.2):
Vai alla pagina delle release di CodeQL Action, trova la release taggata codeql-bundle-v2.22.2 e scarica il bundle appropriato per la tua piattaforma.
Estrai in ~/codeql (o in un altro percorso — aggiorna CODEQL_HOME in .env di conseguenza):
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
Clona il server MCP CodeQL LSP e compilalo.
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
Inserisci la tua chiave API e i percorsi CodeQL in .env:
ANTHROPIC_API_KEY=...
# I percorsi dei QL pack dipendono dalla versione di CodeQL.
# Trova i numeri di versione con:
# ls ~/codeql/qlpacks/codeql/java-queries/ → usa per SECURITY_QLPACK_PATH
# ls ~/codeql/qlpacks/codeql/java-all/ → usa per 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
Quindi avvia l'app QLCoder e ChromaDB:
docker compose up -d
La CVE deve essere elencata in data/project_info.csv. Questo clona il repository al commit difettoso e genera il diff della correzione.
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# oppure più di una alla volta:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# elabora le CVE da un file (un ID CVE per riga)
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# elabora tutte le CVE
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# forza la rigenerazione dei diff esistenti
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
I database vengono creati con --build-mode=none — nessuna toolchain di compilazione richiesta.
# per creare i database CodeQL di una CVE specifica
docker compose run --rm app python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
Questo crea cves/CVE-2025-27818/CVE-2025-27818-vul e cves/CVE-2025-27818/CVE-2025-27818-fix.
# per creare i database CodeQL di tutti i repository CVE recuperati
docker compose run --rm app python3 scripts/build_codeql_dbs.py
Esegui questi script per popolare il database vettoriale. codeql_docs_fetcher.py e cwe_fetcher.py sono configurazioni una tantum; cves_fetcher.py deve essere rieseguito dopo l'aggiunta di nuove 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
Nota - Nell'articolo è stata utilizzata la versione 2.22.2 di CodeQL. Tuttavia, è possibile utilizzare qualsiasi versione (e linguaggio). QLCoder memorizza i QL pack della versione locale di CodeQL nel database vettoriale. I percorsi sono configurati in .env.
Scarica una versione appropriata del bundle CodeQL Action dalla pagina delle release di CodeQL Action.
Per la versione più recente: Visita la release più recente e scarica il bundle appropriato per il tuo sistema operativo:
codeql-bundle-linux64.tar.gz per LinuxPer una versione specifica (es. 2.22.2):
Vai alla pagina delle release di CodeQL Action, trova la release taggata codeql-bundle-v2.22.2 e scarica il bundle appropriato per la tua piattaforma.
Dopo il download, estrai l'archivio nella directory principale del progetto:
tar -xzf codeql-bundle-<platform>.tar.gz
Questo dovrebbe creare una sottodirectory codeql/ con l'eseguibile codeql al suo interno.
Aggiungi il percorso di questo eseguibile alla tua variabile d'ambiente PATH:
export PATH="$PWD/codeql:$PATH"
Clona il server MCP CodeQL LSP e compilalo.
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
Inserisci la tua chiave API e i percorsi CodeQL in .env:
ANTHROPIC_API_KEY=...
CODEQL_HOME=~/codeql
CODEQL_LSP_MCP_HOME=~/codeql-lsp-mcp
# I percorsi dei QL pack dipendono dalla versione di CodeQL.
# Trova i numeri di versione con:
# ls ~/codeql/qlpacks/codeql/java-queries/ → usa per SECURITY_QLPACK_PATH
# ls ~/codeql/qlpacks/codeql/java-all/ → usa per 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
La CVE deve essere elencata in data/project_info.csv. Questo clona il repository al commit difettoso e genera il diff della correzione.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# oppure più di una alla volta:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# elabora le CVE da un file (un ID CVE per riga)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# elabora tutte le CVE
python3 scripts/get_cve_repos.py --all
# forza la rigenerazione dei diff esistenti
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
I database vengono creati con --build-mode=none — nessuna toolchain di compilazione richiesta.
# per creare i database CodeQL di una CVE specifica
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# per creare i database CodeQL di tutti i repository CVE recuperati
python3 scripts/build_codeql_dbs.py
Questo crea cves/CVE-2025-27818/CVE-2025-27818-vul e cves/CVE-2025-27818/CVE-2025-27818-fix.
Avvia ChromaDB in un terminale separato e mantienilo in esecuzione per questo passaggio e ogni volta che esegui l'agente.
chroma run --path data/chroma_db
Esegui questi script per popolare il database vettoriale. codeql_docs_fetcher.py e cwe_fetcher.py sono configurazioni una tantum; cves_fetcher.py deve essere rieseguito dopo l'aggiunta di nuove CVE.
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
Dopo aver seguito le istruzioni di Installazione, l'avvio rapido illustra un esempio di sintesi di una query CodeQL per una data 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
È possibile passare opzioni aggiuntive dopo l'ID CVE:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
Di seguito sono riportate le configurazioni disponibili per QLCoder.
Timeout: Ogni finestra di contesto dell'agente ha un timeout di shell predefinito (es. 300s). Aumenta il timeout nel metodo di esecuzione del backend pertinente se necessario quando si verificano errori "Context window failed".
Nota: Il supporto degli agenti è testato rispetto alle versioni elencate in Ambiente dell'Articolo. Le versioni più recenti degli agenti di codifica potrebbero richiedere aggiornamenti al backend. Sono benvenute PR che aggiungono supporto per versioni più recenti, altri agenti di codifica e più modelli!
Modelli (--model): sonnet-4 (predefinito), sonnet-4.5 (Claude); gemini-2.5-pro, gemini-2.5-flash (Gemini); gpt-5 (Codex)
Agenti (--agent): claude (predefinito), gemini (Gemini CLI), codex (modelli OpenAI e modelli open source)
Modalità di ablazione (--ablation-mode):
| Modalità | Descrizione | Agenti Disponibili |
|---|---|---|
full | Tutti gli strumenti QLCoder abilitati (predefinito) ed estrazione AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_tools | Nessuno strumento e nessuna estrazione AST | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_lsp | Nessuno strumento CodeQL LSP | Claude Code |
no_docs | Nessun recupero della documentazione CodeQL | Claude Code |
no_ast | Nessuna estrazione AST dal diff | Claude Code |
Per impostazione predefinita impostiamo lo sforzo di ragionamento su medio. Puoi sovrascriverlo in codex_backend.py.
Quando Chroma non viene utilizzato per recuperare la descrizione della CVE, una descrizione pre-recuperata viene iniettata direttamente nel prompt tramite task.cve_description. Usa scripts/cves_fetcher.py per popolare un file JSON locale di descrizioni:
python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json
Il file mappa gli ID CVE alle relative stringhe di descrizione CVE e viene aggiornato a ogni esecuzione (le voci esistenti vengono saltate). Quando si esegue con --ablation-mode no_tools o --ablation-mode no_docs, QLCoder carica automaticamente questo file e imposta task.cve_description per la CVE in analisi.
I seguenti strumenti sono consigliati durante l'utilizzo di QLCoder:
Elimina le collection dalle esecuzioni QLCoder - per pulire Chroma, ecco uno script per eliminare le collection derivanti dall'utilizzo di QLCoder.
chromadb-ops - strumento CLI per ispezionare e mantenere Chroma.
# utile per pulire chroma
chops db clean data/chroma_db
Ecco esempi di configurazioni MCP quando si utilizza QLCoder. La configurazione dovrebbe essere simile a questi file nello spazio di lavoro dell'agente.
Le seguenti versioni sono state utilizzate per produrre i risultati nell'articolo QLCoder.
| Strumento | Versione |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
Accogliamo con piacere qualsiasi contributo, pull request o segnalazione di problemi! Se desideri contribuire, apri una nuova pull request o un nuovo issue. Sentiti libero di prendere in carico anche un issue esistente.
QLCoder è uno sforzo collaborativo tra ricercatori della Cornell University, della Johns Hopkins University e della University of Pennsylvania. Contattaci se hai domande.
Claire Wang - Dottoranda in Informatica alla University of Pennsylvania
Ziyang Li - Professore alla Johns Hopkins University
Saikat Dutta - Professore alla Cornell University
Mayur Naik - Professore alla University of Pennsylvania
Considera di citare il nostro articolo 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},
}
I seguenti sono progetti affiliati agli autori di QLCoder. Sentiti libero di darci un'occhiata.