neuralprogram/qlcoderAgentic Framework zum Synthetisieren von CodeQL-Abfragen
Agentisches Framework zur Synthese von CodeQL-Abfragen
QLCoder ist ein Framework zur Verwendung von LLMs zur Synthese von End-to-End-CodeQL-Abfragen zur Schwachstellenerkennung. Ausgehend von den Metadaten einer vorhandenen CVE, einem LLM und einem Coding-Agenten synthetisiert QLCoder iterativ eine CodeQL-Abfrage zur Erkennung der vorhandenen CVE. Die Startabfrage ist eine CodeQL-Pfadabfragevorlage, die mit einem extrahierten AST des Diffs befüllt wird. Während der Synthese der Abfrage hat der Coding-Agent Zugriff auf Werkzeuge zur Schnittstelle mit einer RAG-Datenbank und dem CodeQL-Sprachserver. Anschließend kann die Abfrage für Multivarianten-Analyse, Regressionstests oder als Leitfaden zum Schreiben von CodeQL-Abfragen verwendet werden.
Hinweis – Im Paper wurde CodeQL Version 2.22.2 verwendet. Es kann jedoch jede Version (und Sprache) verwendet werden. QLCoder speichert die QL-Pakete der lokalen CodeQL-Version in der Vektordatenbank. Pfade werden in .env konfiguriert.
Laden Sie eine geeignete Version des CodeQL Action-Bundles von der CodeQL Action-Releases-Seite herunter.
Für die neueste Version: Besuchen Sie das neueste Release und laden Sie das passende Bundle für Ihr Betriebssystem herunter:
codeql-bundle-osx64.tar.gz für macOScodeql-bundle-linux64.tar.gz für LinuxFür eine bestimmte Version (z. B. 2.22.2):
Gehen Sie zur CodeQL Action-Releases-Seite, finden Sie das Release mit dem Tag codeql-bundle-v2.22.2 und laden Sie das passende Bundle für Ihre Plattform herunter.
Entpacken Sie nach ~/codeql (oder einen anderen Pfad – aktualisieren Sie CODEQL_HOME in .env entsprechend):
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
Klonen Sie den CodeQL-LSP-MCP-Server und bauen Sie ihn.
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
Füllen Sie Ihren API-Schlüssel und die CodeQL-Pfade in .env aus:
ANTHROPIC_API_KEY=...
# QL-Paketpfade hängen von Ihrer CodeQL-Version ab.
# Finden Sie die Versionsnummern mit:
# ls ~/codeql/qlpacks/codeql/java-queries/ → für SECURITY_QLPACK_PATH verwenden
# ls ~/codeql/qlpacks/codeql/java-all/ → für LIBRARY_QLPACK_PATH verwenden
SECURITY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-queries/<version>/Security/CWE
LIBRARY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-all/<version>/semmle/code/java
Starten Sie dann die QLCoder-App und ChromaDB:
docker compose up -d
Die CVE muss in data/project_info.csv aufgeführt sein. Dadurch wird das Repository beim fehlerhaften Commit geklont und der Fix-Diff erzeugt.
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# oder mehrere auf einmal:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# CVEs aus einer Datei verarbeiten (eine CVE-ID pro Zeile)
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# alle CVEs verarbeiten
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# vorhandene Diffs erneut erzeugen
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Datenbanken werden mit --build-mode=none erstellt – keine Build-Toolchain erforderlich.
# um die CodeQL-Datenbanken einer bestimmten CVE zu erstellen
docker compose run --rm app python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
Dadurch werden cves/CVE-2025-27818/CVE-2025-27818-vul und cves/CVE-2025-27818/CVE-2025-27818-fix erstellt.
# um die CodeQL-Datenbanken aller abgerufenen CVE-Repositories zu erstellen
docker compose run --rm app python3 scripts/build_codeql_dbs.py
Führen Sie diese Skripte aus, um die Vektordatenbank zu befüllen. codeql_docs_fetcher.py und cwe_fetcher.py sind einmalige Einrichtungen; cves_fetcher.py sollte nach dem Hinzufügen neuer CVEs erneut ausgeführt werden.
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
Hinweis – Im Paper wurde CodeQL Version 2.22.2 verwendet. Es kann jedoch jede Version (und Sprache) verwendet werden. QLCoder speichert die QL-Pakete der lokalen CodeQL-Version in der Vektordatenbank. Pfade werden in .env konfiguriert.
Laden Sie eine geeignete Version des CodeQL Action-Bundles von der CodeQL Action-Releases-Seite herunter.
Für die neueste Version: Besuchen Sie das neueste Release und laden Sie das passende Bundle für Ihr Betriebssystem herunter:
codeql-bundle-linux64.tar.gz für LinuxFür eine bestimmte Version (z. B. 2.22.2):
Gehen Sie zur CodeQL Action-Releases-Seite, finden Sie das Release mit dem Tag codeql-bundle-v2.22.2 und laden Sie das passende Bundle für Ihre Plattform herunter.
Nach dem Herunterladen entpacken Sie das Archiv im Projektstammverzeichnis:
tar -xzf codeql-bundle-<platform>.tar.gz
Dadurch sollte ein Unterverzeichnis codeql/ mit der ausführbaren Datei codeql darin erstellt werden.
Fügen Sie den Pfad dieser ausführbaren Datei zu Ihrer PATH-Umgebungsvariable hinzu:
export PATH="$PWD/codeql:$PATH"
Klonen Sie den CodeQL-LSP-MCP-Server und bauen Sie ihn.
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 konfigurierencp .env.example .env
Füllen Sie Ihren API-Schlüssel und die CodeQL-Pfade in .env aus:
ANTHROPIC_API_KEY=...
CODEQL_HOME=~/codeql
CODEQL_LSP_MCP_HOME=~/codeql-lsp-mcp
# QL-Paketpfade hängen von Ihrer CodeQL-Version ab.
# Finden Sie die Versionsnummern mit:
# ls ~/codeql/qlpacks/codeql/java-queries/ → für SECURITY_QLPACK_PATH verwenden
# ls ~/codeql/qlpacks/codeql/java-all/ → für LIBRARY_QLPACK_PATH verwenden
SECURITY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-queries/<version>/Security/CWE
LIBRARY_QLPACK_PATH=~/codeql/qlpacks/codeql/java-all/<version>/semmle/code/java
Die CVE muss in data/project_info.csv aufgeführt sein. Dadurch wird das Repository beim fehlerhaften Commit geklont und der Fix-Diff erzeugt.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# oder mehrere auf einmal:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# CVEs aus einer Datei verarbeiten (eine CVE-ID pro Zeile)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# alle CVEs verarbeiten
python3 scripts/get_cve_repos.py --all
# vorhandene Diffs erneut erzeugen
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Datenbanken werden mit --build-mode=none erstellt – keine Build-Toolchain erforderlich.
# um die CodeQL-Datenbanken einer bestimmten CVE zu erstellen
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# um die CodeQL-Datenbanken aller abgerufenen CVE-Repositories zu erstellen
python3 scripts/build_codeql_dbs.py
Dadurch werden cves/CVE-2025-27818/CVE-2025-27818-vul und cves/CVE-2025-27818/CVE-2025-27818-fix erstellt.
Starten Sie ChromaDB in einem separaten Terminal und lassen Sie es für diesen Schritt und bei jeder Ausführung des Agenten laufen.
chroma run --path data/chroma_db
Führen Sie diese Skripte aus, um die Vektordatenbank zu befüllen. codeql_docs_fetcher.py und cwe_fetcher.py sind einmalige Einrichtungen; cves_fetcher.py sollte nach dem Hinzufügen neuer CVEs erneut ausgeführt werden.
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
Nachdem Sie die Installationsanweisungen befolgt haben, führt Sie der Schnellstart durch ein Beispiel zur Synthese einer CodeQL-Abfrage für eine bestimmte 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
Zusätzliche Optionen können nach der CVE-ID übergeben werden:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
Im Folgenden sind die verfügbaren Konfigurationen für QLCoder aufgeführt.
Timeout: Jeder Agenten-Kontextfenster hat ein standardmäßiges Shell-Timeout (z. B. 300s). Erhöhen Sie das Timeout in der relevanten Backend-Ausführungsmethode, wenn Sie auf „Context window failed“-Fehler stoßen.
Hinweis: Die Agentenunterstützung wird gegen die in Paper-Umgebung aufgeführten Versionen getestet. Neuere Versionen von Coding-Agenten können Updates am Backend erfordern. Pull Requests, die Unterstützung für neuere Versionen, andere Coding-Agenten und weitere Modelle hinzufügen, sind willkommen!
Modelle (--model): sonnet-4 (Standard), sonnet-4.5 (Claude); gemini-2.5-pro, gemini-2.5-flash (Gemini); gpt-5 (Codex)
Agenten (--agent): claude (Standard), gemini (Gemini CLI), codex (OpenAI-Modelle und Open-Source-Modelle)
Ablationsmodi (--ablation-mode):
| Modus | Beschreibung | Verfügbare Agenten |
|---|---|---|
full | Alle QLCoder-Werkzeuge aktiviert (Standard) und AST-Extraktion | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_tools | Keine Werkzeuge und keine AST-Extraktion | Claude Code, Codex (GPT, GPT-OSS), Gemini |
no_lsp | Keine CodeQL-LSP-Werkzeuge | Claude Code |
no_docs | Keine CodeQL-Dokumentationsabfrage | Claude Code |
no_ast | Keine AST-Extraktion aus dem Diff | Claude Code |
Standardmäßig setzen wir den Reasoning-Aufwand auf mittel. Sie können dies in codex_backend.py überschreiben.
Wenn Chroma nicht zum Abrufen der CVE-Beschreibung verwendet wird, wird eine vorab abgerufene Beschreibung direkt über task.cve_description in den Prompt injiziert. Verwenden Sie scripts/cves_fetcher.py, um eine lokale JSON-Datei mit Beschreibungen zu befüllen:
python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json
Die Datei ordnet CVE-IDs ihren CVE-Beschreibungszeichenfolgen zu und wird bei jedem Lauf ergänzt (vorhandene Einträge werden übersprungen). Wenn Sie mit --ablation-mode no_tools oder --ablation-mode no_docs ausführen, lädt QLCoder diese Datei automatisch und setzt task.cve_description für die zu analysierende CVE.
Die folgenden Werkzeuge werden bei der Verwendung von QLCoder empfohlen:
Sammlungen aus QLCoder-Läufen löschen – zum Bereinigen von Chroma finden Sie hier ein Skript zum Löschen von Sammlungen aus der Verwendung von QLCoder.
chromadb-ops – CLI-Werkzeug zum Inspizieren und Verwalten von Chroma.
# nützlich zum Bereinigen von Chroma
chops db clean data/chroma_db
Hier sind Beispiele für MCP-Konfigurationen bei der Verwendung von QLCoder. Die Konfiguration sollte diesen Dateien im Arbeitsbereich des Agenten ähneln.
Die folgenden Versionen wurden verwendet, um die Ergebnisse im QLCoder-Paper zu erzielen.
| Werkzeug | Version |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
Wir begrüßen alle Beiträge, Pull Requests oder Issues! Wenn Sie beitragen möchten, reichen Sie bitte entweder einen neuen Pull Request oder ein Issue ein. Sie können auch gerne ein bestehendes Issue übernehmen.
QLCoder ist eine gemeinsame Anstrengung von Forschern der Cornell University, der Johns Hopkins University und der University of Pennsylvania. Kontaktieren Sie uns bitte bei Fragen.
Claire Wang – CS-Doktorandin an der University of Pennsylvania
Ziyang Li – Professor an der Johns Hopkins University
Saikat Dutta – Professor an der Cornell University
Mayur Naik – Professor an der University of Pennsylvania
Erwägen Sie, unser ICLR'26-Paper zu zitieren:
@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},
}
Die folgenden Projekte sind mit den QLCoder-Autoren verbunden. Schauen Sie sich diese gerne an.