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):