neuralprogram/qlcoderإطار عامل لتوليف استعلامات CodeQL
إطار عمل وكيل لتوليد استعلامات CodeQL
QLCoder هو إطار عمل لاستخدام نماذج اللغة الكبيرة (LLMs) لتوليد استعلامات CodeQL شاملة لاكتشاف الثغرات الأمنية. بالنظر إلى بيانات تعريف CVE موجودة، ونموذج لغوي كبير، ووكيل برمجي، يقوم QLCoder بتوليد استعلام CodeQL بشكل تكراري لاكتشاف الـ CVE الموجود. الاستعلام الابتدائي هو قالب استعلام مسار CodeQL يتم تعبئته بواسطة AST مستخرج من الـ diff. أثناء توليد الاستعلام، يمتلك الوكيل البرمجي أدوات للتفاعل مع قاعدة بيانات 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 ~/
قم باستنساخ خادم 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
قم بتعبئة مفتاح 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. يقوم هذا باستنساخ المستودع عند الالتزام الذي يحتوي على الخطأ وتوليد diff الإصلاح.
docker compose run --rm app python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# أو عدة CVEs دفعة واحدة:
docker compose run --rm app python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# معالجة CVEs من ملف (معرف CVE واحد في كل سطر)
docker compose run --rm app python3 scripts/get_cve_repos.py --cve-file cves.txt
# معالجة جميع CVEs
docker compose run --rm app python3 scripts/get_cve_repos.py --all
# فرض إعادة توليد الـ diffs الموجودة
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 بعد إضافة CVEs جديدة.
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"
قم باستنساخ خادم 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
.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. يقوم هذا باستنساخ المستودع عند الالتزام الذي يحتوي على الخطأ وتوليد diff الإصلاح.
python3 scripts/get_cve_repos.py --cve CVE-2025-27818
# أو عدة CVEs دفعة واحدة:
python3 scripts/get_cve_repos.py --cves CVE-2025-27818,CVE-2025-0851
# معالجة CVEs من ملف (معرف CVE واحد في كل سطر)
python3 scripts/get_cve_repos.py --cve-file cves.txt
# معالجة جميع CVEs
python3 scripts/get_cve_repos.py --all
# فرض إعادة توليد الـ diffs الموجودة
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 بعد إضافة CVEs جديدة.
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
يمكن تمرير خيارات إضافية بعد معرف CVE:
./run_cve.sh CVE-2025-27818 --model sonnet-4.5 --max-iteration 10
فيما يلي التكوينات المتاحة لـ QLCoder.
المهلة: تحتوي كل نافذة سياق وكيل على مهلة shell افتراضية (مثل 300 ثانية). قم بزيادة المهلة في طريقة التنفيذ الخاصة بالخلفية ذات الصلة إذا لزم الأمر عند مواجهة أخطاء "Context window failed".
ملاحظة: يتم اختبار دعم الوكيل مقابل الإصدارات المدرجة في بيئة الورقة البحثية. قد تتطلب الإصدارات الأحدث من الوكلاء البرمجيين تحديثات للخلفية. نرحب بطلبات السحب (PRs) التي تضيف دعمًا للإصدارات الأحدث، والوكلاء البرمجيين الآخرين، والمزيد من النماذج!
النماذج (--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 من الـ diff | 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
يقوم الملف بتعيين معرفات CVE إلى سلاسل وصف CVE الخاصة بها ويتم الإلحاق به في كل تشغيل (يتم تخطي الإدخالات الموجودة). عند التشغيل باستخدام --ablation-mode no_tools أو --ablation-mode no_docs، يقوم QLCoder تلقائيًا بتحميل هذا الملف وتعيين task.cve_description للـ CVE الذي يتم تحليله.
الأدوات التالية موصى بها أثناء استخدام QLCoder:
حذف المجموعات من تشغيلات QLCoder - لتنظيف Chroma، إليك برنامج نصي لحذف المجموعات من استخدام QLCoder.
chromadb-ops - أداة سطر أوامر لفحص وصيانة 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 |
نرحب بأي مساهمات أو طلبات سحب أو مشكلات! إذا كنت ترغب في المساهمة، يرجى إما تقديم طلب سحب جديد أو مشكلة. لا تتردد في تولي مشكلة موجودة أيضًا.
QLCoder هو جهد تعاوني بين باحثين في جامعة كورنيل، وجامعة جونز هوبكنز، وجامعة بنسلفانيا. يرجى التواصل معنا إذا كان لديك أي أسئلة.
Claire Wang - طالبة دكتوراه في علوم الحاسوب بجامعة بنسلفانيا
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. لا تتردد في الاطلاع عليها.