neuralprogram/qlcoderAgentic Framework для синтеза CodeQL-запросов
Агентный фреймворк для синтеза CodeQL-запросов
QLCoder — это фреймворк для использования LLM с целью синтеза сквозных CodeQL-запросов для обнаружения уязвимостей. Имея метаданные существующей CVE, LLM и кодирующий агент, QLCoder итеративно синтезирует CodeQL-запрос для обнаружения данной CVE. Начальный запрос — это шаблон CodeQL path-запроса, заполненный извлечённым AST диффа. Во время синтеза запроса кодирующий агент имеет доступ к инструментам для взаимодействия с RAG-базой данных и языковым сервером CodeQL. Впоследствии запрос может использоваться для мультивариантного анализа, регрессионного тестирования или в качестве руководства при написании CodeQL-запросов.
Примечание — В статье использовалась версия CodeQL 2.22.2. Однако можно использовать любую версию (и язык). QLCoder хранит QL-пакеты локальной версии CodeQL в векторной базе данных. Пути настраиваются в .env.
Загрузите подходящую версию пакета CodeQL Action со страницы релизов CodeQL Action.
Для последней версии: Посетите последний релиз и загрузите подходящий пакет для вашей ОС:
codeql-bundle-osx64.tar.gz для macOScodeql-bundle-linux64.tar.gz для LinuxДля конкретной версии (например, 2.22.2):
Перейдите на страницу релизов CodeQL Action, найдите релиз с тегом codeql-bundle-v2.22.2 и загрузите подходящий пакет для вашей платформы.
Распакуйте в ~/codeql (или в другой путь — обновите CODEQL_HOME в .env соответствующим образом):
tar -xzf codeql-bundle-<platform>.tar.gz -C ~/
Клонируйте MCP-сервер CodeQL LSP и соберите его.
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
Заполните ваш API-ключ и пути CodeQL в .env:
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. Это клонирует репозиторий на коммите с ошибкой и генерирует дифф исправления.
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 из файла (по одному ID CVE в строке)
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
# принудительная регенерация существующих диффов
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Базы данных создаются с --build-mode=none — инструментарий сборки не требуется.
# для создания баз данных CodeQL для конкретной CVE
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.
# для создания баз данных CodeQL для всех полученных репозиториев CVE
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 хранит QL-пакеты локальной версии CodeQL в векторной базе данных. Пути настраиваются в .env.
Загрузите подходящую версию пакета CodeQL Action со страницы релизов CodeQL Action.
Для последней версии: Посетите последний релиз и загрузите подходящий пакет для вашей ОС:
codeql-bundle-linux64.tar.gz для LinuxДля конкретной версии (например, 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"
Клонируйте MCP-сервер CodeQL LSP и соберите его.
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
Заполните ваш API-ключ и пути CodeQL в .env:
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. Это клонирует репозиторий на коммите с ошибкой и генерирует дифф исправления.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# или несколько сразу:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# обработка CVE из файла (по одному ID CVE в строке)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# обработка всех CVE
python3 scripts/get_cve_repos.py --all
# принудительная регенерация существующих диффов
python3 scripts/get_cve_repos.py --cve CVE-2018-9159 --force
Базы данных создаются с --build-mode=none — инструментарий сборки не требуется.
# для создания баз данных CodeQL для конкретной CVE
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818
# для создания баз данных CodeQL для всех полученных репозиториев CVE
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
После выполнения инструкций по установке быстрый старт проведёт вас через пример синтеза CodeQL-запроса для заданной 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
Дополнительные параметры можно передать после ID CVE:
./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 | Без извлечения AST из диффа | Claude Code |
По умолчанию мы устанавливаем уровень рассуждений на средний. Вы можете переопределить это в codex_backend.py.
Когда Chroma не используется для получения описания CVE, предварительно загруженное описание внедряется непосредственно в промпт через task.cve_description. Используйте scripts/cves_fetcher.py для заполнения локального JSON-файла с описаниями:
python scripts/cves_fetcher.py --descriptions-file data/cve_descriptions.json
Файл сопоставляет ID CVE с их строками описания CVE и дополняется при каждом запуске (существующие записи пропускаются). При запуске с --ablation-mode no_tools или --ablation-mode no_docs QLCoder автоматически загружает этот файл и устанавливает task.cve_description для анализируемой CVE.
При использовании QLCoder рекомендуются следующие инструменты:
Удаление коллекций из запусков QLCoder — для очистки Chroma, вот скрипт для удаления коллекций после использования QLCoder.
chromadb-ops — CLI-инструмент для проверки и обслуживания Chroma.
# полезно для очистки chroma
chops db clean data/chroma_db
Вот примеры конфигураций MCP при использовании QLCoder. Конфигурация должна быть аналогична этим файлам в рабочем пространстве агента.
Следующие версии использовались для получения результатов в статье QLCoder.
| Инструмент | Версия |
|---|---|
| CodeQL | 2.22.2 |
| Claude Code | 1.0.120 |
| Gemini CLI | 0.6.0 |
| Codex CLI | 0.38.0 |
Мы приветствуем любые вклады, pull request'ы и issues! Если вы хотите внести вклад, пожалуйста, создайте новый pull request или issue. Также можете взять на себя существующий issue.
QLCoder — это совместная работа исследователей из Корнеллского университета, Университета Джонса Хопкинса и Пенсильванского университета. Пожалуйста, свяжитесь с нами, если у вас есть вопросы.
Claire Wang — аспирантка CS в Пенсильванском университете
Ziyang Li — профессор Университета Джонса Хопкинса
Saikat Dutta — профессор Корнеллского университета
Mayur Naik — профессор Пенсильванского университета
Рассмотрите возможность цитирования нашей статьи 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. Не стесняйтесь ознакомиться с ними.