neuralprogram/qlcoderAgentic 프레임워크: CodeQL 쿼리 합성용
CodeQL 쿼리 합성을 위한 에이전트 기반 프레임워크
QLCoder는 LLM을 사용하여 취약점 탐지를 위한 종단 간 CodeQL 쿼리를 합성하는 프레임워크입니다. 기존 CVE의 메타데이터, LLM, 코딩 에이전트가 주어지면 QLCoder는 기존 CVE를 탐지하기 위한 CodeQL 쿼리를 반복적으로 합성합니다. 시작 쿼리는 diff의 추출된 AST로 채워진 CodeQL 경로 쿼리 템플릿입니다. 쿼리를 합성하는 동안 코딩 에이전트는 RAG 데이터베이스 및 CodeQL 언어 서버와 인터페이스하기 위한 도구에 접근할 수 있습니다. 이후 쿼리는 다변량 분석, 회귀 테스트 또는 CodeQL 쿼리 작성 지침으로 사용될 수 있습니다.
참고 - 논문에서는 CodeQL 버전 2.22.2를 사용했습니다. 그러나 모든 버전(및 언어)을 사용할 수 있습니다. QLCoder는 로컬 CodeQL 버전의 QL 팩을 벡터 데이터베이스에 저장합니다. 경로는 .env에서 구성됩니다.
CodeQL Action 릴리스 페이지에서 적절한 버전의 CodeQL Action 번들을 다운로드하세요.
최신 버전의 경우: 최신 릴리스를 방문하여 OS에 맞는 적절한 번들을 다운로드하세요:
codeql-bundle-osx64.tar.gzcodeql-bundle-linux64.tar.gz특정 버전(예: 2.22.2)의 경우:
CodeQL Action 릴리스 페이지로 이동하여 codeql-bundle-v2.22.2 태그가 붙은 릴리스를 찾고 플랫폼에 맞는 적절한 번들을 다운로드하세요.
~/codeql(또는 다른 경로 — .env의 CODEQL_HOME을 그에 맞게 업데이트)에 압축을 풉니다:
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
CodeQL LSP MCP 서버를 클론하고 빌드하세요.
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
.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
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
데이터베이스는 --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
벡터 데이터베이스를 채우려면 다음 스크립트를 실행하세요. codeql_docs_fetcher.py 및 cwe_fetcher.py는 일회성 설정입니다. cves_fetcher.py는 새 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
참고 - 논문에서는 CodeQL 버전 2.22.2를 사용했습니다. 그러나 모든 버전(및 언어)을 사용할 수 있습니다. QLCoder는 로컬 CodeQL 버전의 QL 팩을 벡터 데이터베이스에 저장합니다. 경로는 .env에서 구성됩니다.
CodeQL Action 릴리스 페이지에서 적절한 버전의 CodeQL Action 번들을 다운로드하세요.
최신 버전의 경우: 최신 릴리스를 방문하여 OS에 맞는 적절한 번들을 다운로드하세요:
codeql-bundle-linux64.tar.gz특정 버전(예: 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"
CodeQL LSP MCP 서버를 클론하고 빌드하세요.
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 구성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
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
데이터베이스는 --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가 생성됩니다.
별도의 터미널에서 ChromaDB를 시작하고 이 단계와 에이전트 실행 시 계속 실행 상태로 유지하세요.
chroma run --path data/chroma_db
벡터 데이터베이스를 채우려면 다음 스크립트를 실행하세요. codeql_docs_fetcher.py 및 cwe_fetcher.py는 일회성 설정입니다. cves_fetcher.py는 새 CVE를 추가한 후 다시 실행해야 합니다.
python3 scripts/codeql_docs_fetcher.py
python3 scripts/cwe_fetcher.py
python3 scripts/cves_fetcher.py
설치 지침을 따른 후, 빠른 시작은 주어진 CVE에 대한 CodeQL 쿼리 합성 예시를 안내합니다.
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
CVE ID 뒤에 추가 옵션을 전달할 수 있습니다:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
다음은 QLCoder에 사용 가능한 구성입니다.
시간 초과: 각 에이전트 컨텍스트 창에는 기본 셸 시간 초과(예: 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):
| 모드 | 설명 | 사용 가능한 에이전트 |
|---|---|---|
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 |
기본적으로 추론 노력을 중간(medium)으로 설정합니다. 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 사용 시 MCP 구성의 예시입니다. 구성은 에이전트 작업 공간의 이러한 파일과 유사해야 합니다.
QLCoder 논문의 결과를 생성하는 데 다음 버전이 사용되었습니다.
| 도구 | 버전 |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
모든 기여, 풀 리퀘스트 또는 이슈를 환영합니다! 기여하려면 새 풀 리퀘스트 또는 이슈를 제출하세요. 기존 이슈를 맡는 것도 자유롭게 하세요.
QLCoder는 Cornell University, Johns Hopkins University 및 University of Pennsylvania의 연구자들 간의 협력 프로젝트입니다. 질문이 있으시면 연락 주세요.
Claire Wang - University of Pennsylvania CS 박사 과정 학생
Ziyang Li - Johns Hopkins University 교수
Saikat Dutta - Cornell University 교수
Mayur Naik - University of Pennsylvania 교수
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},
}
다음은 QLCoder 저자와 관련된 프로젝트입니다. 확인해 보세요.