QLCoder

إطار عمل وكيل لتوليد استعلامات CodeQL

جدول المحتويات

• نظرة عامة
• التثبيت
  • Docker (موصى به)
  • التثبيت المحلي (Linux)
• الاستخدام
• بدء سريع
• أدوات التطوير
• أمثلة
• بيئة الورقة البحثية
• المساهمات
• الفريق
• الاستشهاد
• المشاريع المرتبطة

نظرة عامة

QLCoder هو إطار عمل لاستخدام نماذج اللغة الكبيرة (LLMs) لتوليد استعلامات CodeQL شاملة لاكتشاف الثغرات الأمنية. بالنظر إلى بيانات تعريف CVE موجودة، ونموذج لغوي كبير، ووكيل برمجي، يقوم QLCoder بتوليد استعلام CodeQL بشكل تكراري لاكتشاف الـ CVE الموجود. الاستعلام الابتدائي هو قالب استعلام مسار CodeQL يتم تعبئته بواسطة AST مستخرج من الـ diff. أثناء توليد الاستعلام، يمتلك الوكيل البرمجي أدوات للتفاعل مع قاعدة بيانات RAG وخادم لغة CodeQL. بعد ذلك، يمكن استخدام الاستعلام لتحليل متعدد المتغيرات، أو اختبار الانحدار، أو كدليل لكتابة استعلامات CodeQL.

التثبيت

Docker (موصى به)

الخطوة 1: تثبيت CodeQL

ملاحظة - في الورقة البحثية، تم استخدام إصدار CodeQL 2.22.2. ومع ذلك، يمكن استخدام أي إصدار (وأي لغة). يخزن QLCoder حزم QL الخاصة بإصدار CodeQL المحلي في قاعدة البيانات المتجهة. يتم تكوين المسارات في .env.

قم بتنزيل إصدار مناسب من حزمة CodeQL Action من صفحة إصدارات CodeQL Action.

• للإصدار الأحدث: قم بزيارة أحدث إصدار وقم بتنزيل الحزمة المناسبة لنظام التشغيل الخاص بك:

  • codeql-bundle-osx64.tar.gz لنظام macOS
  • codeql-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 ~/

الخطوة 2: تثبيت خادم CodeQL LSP MCP

قم باستنساخ خادم CodeQL LSP MCP وبناؤه.

git clone https://github.com/neuralprogram/codeql-lsp-mcp ~/codeql-lsp-mcp
cd ~/codeql-lsp-mcp
npm install
npm run build

الخطوة 3: تكوين وبدء الخدمات

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

الخطوة 4: استرجاع مستودعات CVE

يجب أن يكون الـ 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

الخطوة 5: إنشاء قواعد بيانات CodeQL

يتم إنشاء قواعد البيانات باستخدام --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

الخطوة 6: تعبئة قاعدة بيانات RAG

قم بتشغيل هذه البرامج النصية لتعبئة قاعدة البيانات المتجهة. 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

التثبيت المحلي (Linux)

الخطوة 1: تثبيت CodeQL

ملاحظة - في الورقة البحثية، تم استخدام إصدار 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"

الخطوة 2: تثبيت خادم CodeQL LSP MCP

قم باستنساخ خادم CodeQL LSP MCP وبناؤه.

git clone https://github.com/neuralprogram/codeql-lsp-mcp
cd codeql-lsp-mcp
npm install
npm run build

الخطوة 3: إعداد بيئة Conda

conda env create -f environment.yml
conda activate qlcoder

الخطوة 4: تكوين .env

cp .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

الخطوة 5: استرجاع مستودعات CVE

يجب أن يكون الـ 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

الخطوة 6: إنشاء قواعد بيانات CodeQL

يتم إنشاء قواعد البيانات باستخدام --build-mode=none — لا حاجة لأدوات البناء.

# لبناء قواعد بيانات CodeQL لـ CVE محدد
python3 scripts/build_codeql_dbs.py --cve-id CVE-2025-27818

# لبناء قواعد بيانات CodeQL لجميع مستودعات CVE المسترجعة
python3 scripts/build_codeql_dbs.py