CodeQL

CodeQL هي أداة التحليل الثابت من GitHub للعثور على ثغرات الأمان ومشاكل جودة الكود باستخدام الاستعلامات الدلالية والتحليل الدلالي.

التثبيت

macOS

# تثبيت Homebrew
brew install codeql

# التحميل اليدوي
wget https://github.com/github/codeql-cli-releases/releases/download/v2.16.0/codeql-osx64.zip
unzip codeql-osx64.zip
export PATH=$PATH:$HOME/codeql

Linux

# Ubuntu/Debian
wget https://github.com/github/codeql-cli-releases/releases/download/v2.16.0/codeql-linux64.zip
unzip codeql-linux64.zip
sudo mv codeql /usr/local/bin/

# التحقق من التثبيت
codeql --version

Windows

# التحميل من صفحة GitHub releases
# https://github.com/github/codeql-cli-releases/releases
# استخراج وإضافة إلى PATH

عمليات قاعدة البيانات

إنشاء قاعدة بيانات CodeQL

# إنشاء قاعدة بيانات لمستودع GitHub
codeql database create <database-name> --language=<language> --source-root=<path>

# مثال: إنشاء قاعدة بيانات JavaScript
codeql database create my-db --language=javascript --source-root=./src

# إنشاء قاعدة بيانات متعددة اللغات
codeql database create my-db --language=java,javascript --source-root=./src

# إنشاء قاعدة بيانات بأمر صريح
codeql database create my-db \
  --language=python \
  --command="python -m pip install -r requirements.txt" \
  --source-root=./

# مع مخطط قاعدة البيانات
codeql database create my-db \
  --language=cpp \
  --source-root=./src \
  --db-scheme=/custom/db-scheme.yml

إدارة قاعدة البيانات

# إدراج قواعس البيانات
codeql database list

# الحصول على معلومات قاعدة البيانات
codeql database info <database>

# تنظيف قواعس البيانات غير المستخدمة
codeql database cleanup <database>

# إزالة قاعدة البيانات
rm -rf <database-path>

# حزم قاعدة البيانات للمشاركة
codeql database bundle <database> --output=<bundle.zip>

# فك حزم قاعدة البيانات
codeql database unbundle <bundle.zip> --output=<database>

تشغيل الاستعلامات

تنفيذ الاستعلام الأساسي

# تشغيل استعلام واحد على قاعدة البيانات
codeql query run <query.ql> --database=<database>

# تشغيل مجموعة الاستعلام
codeql query run <query-suite.yaml> --database=<database>

# تشغيل الاستعلام وحفظ النتائج كـ CSV
codeql query run <query.ql> --database=<database> --output=<results.csv>

# التشغيل مع مخرجات JSON
codeql query run <query.ql> --database=<database> --output=<results.json> --format=json

استعلامات الأمان المدمجة

# تشغيل استعلامات الأمان والجودة الافتراضية
codeql database analyze <database> security-and-quality --format=sarif-latest --output=results.sarif

# التحليل مع مجموعة استعلام مخصصة
codeql database analyze <database> <path/to/queries> \
  --format=sarif-latest \
  --output=results.sarif

# تحليل لغة محددة
codeql database analyze <database> codeql/java-queries --format=csv --output=results.csv

# تحليل مركز على CWE
codeql database analyze <database> codeql-suites/javascript-security-and-quality.qls

الأوامر حسب اللغة

JavaScript/TypeScript

# إنشاء قاعدة بيانات JavaScript
codeql database create js-db --language=javascript --source-root=.

# تشغيل تحليل الأمان
codeql database analyze js-db codeql/javascript-queries:security-and-quality --format=sarif-latest

# فحص حقن SQL
codeql query run \
  --database=js-db \
  <path-to-query>/sql-injection.ql

Python

# إنشاء قاعدة بيانات Python
codeql database create py-db --language=python --source-root=.

# تحليل الأمان
codeql database analyze py-db codeql/python-queries:security --format=sarif-latest

# كشف اجتياز المسار
codeql query run \
  --database=py-db \
  <path-to-query>/path-injection.ql

Java

# إنشاء قاعدة بيانات Java مع Maven
codeql database create java-db \
  --language=java \
  --command="mvn clean install" \
  --source-root=.

# مع Gradle
codeql database create java-db \
  --language=java \
  --command="gradle build" \
  --source-root=.

# فحص الأمان
codeql database analyze java-db codeql/java-queries:security-and-quality

C/C++

# إنشاء قاعدة بيانات C++ مع make
codeql database create cpp-db \
  --language=cpp \
  --command="make" \
  --source-root=.

# مع CMake
codeql database create cpp-db \
  --language=cpp \
  --command="cmake . && make" \
  --source-root=.

تطوير الاستعلام

إنشاء استعلامات مخصصة

# بدء تطوير الاستعلام
cat > select-sinks.ql << 'EOF'
import cpp

from FunctionCall fc
where fc.getTarget().getName() = "printf"
select fc
EOF

# تشغيل الاستعلام المخصص
codeql query run select-sinks.ql --database=cpp-db

اختبار الاستعلامات

# تشغيل اختبارات الاستعلام
codeql test run <test-dir>

# الاختبار مع مخرجات مفصلة
codeql test run <test-dir> --verbose

# اختبار ملف اختبار معين
codeql test run <test-file.ql>

تكامل CI/CD

GitHub Actions

name: تحليل CodeQL
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: تهيئة CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: 'javascript,python'

      - name: بناء
        run: |
          npm install
          npm run build

      - name: تنفيذ تحليل CodeQL
        uses: github/codeql-action/analyze@v2

التكامل اليدوي مع CI

#!/bin/bash
set -e

# إنشاء قاعدة البيانات
codeql database create codeql-db --language=javascript --source-root=.

# تشغيل التحليل
codeql database analyze codeql-db security-and-quality --format=sarif-latest --output=results.sarif

# تحميل النتائج
curl -H "Authorization: token $GITHUB_TOKEN" \
  -F "payload=@results.sarif" \
  "https://api.github.com/repos/$GITHUB_REPOSITORY/code-scanning/sarif"

استكشاف الأخطاء

مشاكل شائعة

فشل إنشاء قاعدة البيانات

# التحقق من دعم اللغة
codeql describe languages

# التحقق من أمر البناء
codeql database create db \
  --language=java \
  --command="mvn clean install" \
  --source-root=. \
  --verbose

أفضل الممارسات

تخزين قواعس البيانات في التحكم بالإصدار لقابلية إعادة الإنتاج
استخدام إصدارات لغة وحزمة الاستعلام المتسقة
إدراج CodeQL في خطاطيف الالتزام المسبق للكشف المبكر
تحديث CodeQL CLI وحزم الاستعلام بانتظام
توثيق الاستعلامات المخصصة بتعليقات واضحة

الموارد

آخر تحديث: 2025-03-30