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

مكتمل

يتعامل CodeQL مع التعليمات البرمجية مثل البيانات. يمكنك إنشاء قاعدة بيانات باستخدام البيانات القابلة للاستعلام التي تستخرجها من قاعدة التعليمات البرمجية الخاصة بك. ثم يمكنك تشغيل استعلامات CodeQL على قاعدة البيانات هذه لتحديد الثغرات الأمنية والأخطاء والأخطاء الأخرى. يمكنك كتابة استعلاماتك الخاصة أو تشغيل استعلامات CodeQL القياسية التي كتبها باحثو GitHub والمساهمون في المجتمع.

في هذه الوحدة، ستتعلم كيفية إنشاء قاعدة بيانات. هذه الخطوة مطلوبة قبل أن تتمكن من تحليل التعليمات البرمجية الخاصة بك. تحتاج إلى إنشاء قاعدة بيانات CodeQL تحتوي على جميع البيانات اللازمة لتشغيل الاستعلامات على التعليمات البرمجية الخاصة بك.

يعتمد تحليل CodeQL على استخراج البيانات الارتباطية من التعليمات البرمجية واستخدامها لإنشاء قاعدة بيانات CodeQL. تحتوي قواعد البيانات هذه على جميع المعلومات المهمة حول قاعدة التعليمات البرمجية.

يمكنك استخدام المنتج المستقل CodeQL CLI لتحليل التعليمات البرمجية وإنشاء تمثيل قاعدة بيانات لقاعدة التعليمات البرمجية. بعد أن تصبح قاعدة البيانات جاهزة، يمكنك الاستعلام عن قاعدة البيانات أو تشغيل مجموعة من الاستعلامات لإنشاء مجموعة من النتائج في Static Analysis Results Interchange Format (SARIF).

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

قبل إنشاء قاعدة بيانات CodeQL، تحتاج إلى تثبيت CodeQL CLI وإعداده. ثم تحتاج إلى التحقق من إصدار قاعدة التعليمات البرمجية التي تريد تحليلها.

بالنسبة للغات المحولة برمجيا، يجب أن يكون الدليل جاهزا للإنشاء، مع تثبيت جميع التبعيات بالفعل. يبدأ CodeQL باستخراج تمثيل علائقي واحد لكل ملف مصدر في قاعدة التعليمات البرمجية لإنشاء قاعدة بيانات. يمكنك استخدام قاعدة البيانات هذه لتحليل التعليمات البرمجية الخاصة بك.

بالنسبة للغات المفسرة، يعمل المستخرج مباشرة على التعليمات البرمجية المصدر. تمنحك هذه الإمكانية تمثيلا دقيقا لقاعدة التعليمات البرمجية وتحل أي تبعيات.

يعمل استخراج الملف المصدر من قاعدة التعليمات البرمجية عن طريق مراقبة عملية الإنشاء العادية للغات المحولة برمجيا. يقوم CodeQL بعمل نسخة من الملف المصدر في كل مرة تقوم فيها باستدعاء محول برمجي لمعالجة ملف مصدر. يجمع جميع المعلومات ذات الصلة حول التعليمات البرمجية المصدر مع كل ملف مصدر.

إعداد CLI

استخدم الخطوات التالية لإعداد CodeQL CLI.

1. تنزيل حزمة .zip حزمة CodeQL CLI

نوصي بتثبيت CodeQL CLI والاستعلامات عن طريق تنزيل الحزمة المجمعة. يساعد هذا الأسلوب على ضمان التوافق والأداء المحسن، بدلا من تنزيل CLI والاستعلامات بشكل منفصل.

حزمة تنزيل CodeQL CLI هي أرشيف .zip يحتوي على أدوات ونصوص وملفات مختلفة خاصة ب CodeQL. تتضمن المجموعة: CodeQL CLI، والإصدارات المتوافقة من الاستعلامات والمكتبات من مستودع CodeQL GitHub، والإصدارات المجمعة مسبقا من الاستعلامات المضمنة.

1. انتقل إلى صفحة Releases لمستودع CodeQL العام.
2. قم بتنزيل المجموعة الخاصة بالنظام الأساسي ضمن Assets.

في صفحة Releases، يمكنك أيضا عرض changelogs للإصدارات، بالإضافة إلى التنزيلات للإصدارات السابقة من حزمة CodeQL. إذا لزم الأمر، يمكنك تنزيل codeql-bundle.tar.gz، الذي يحتوي على CLI لجميع الأنظمة الأساسية المدعومة.

2. استخراج أرشيف .zip

إذا كنت تستخدم Linux أو Windows أو macOS، يمكنك استخراج أرشيف .zip في الدليل الذي تختاره.

يحتاج مستخدمو macOS Catalina (أو الأحدث) إلى اتخاذ خطوات إضافية. لمزيد من المعلومات، راجع وثائق CodeQL حول بدء استخدامCLI .

3. تشغيل عمليات CodeQL

بعد الاستخراج، اتخذ إحدى الخطوات التالية لاستخدام الملف القابل للتنفيذ codeql لتشغيل عمليات CodeQL:

• قم بتشغيل <extraction-root>/codeql/codeql، حيث <extraction-root> هو المجلد الذي قمت باستخراج حزمة CodeQL CLI فيه.
• أضف <extraction-root>/codeql إلى إدخال PATH، بحيث يمكنك تشغيل الملف القابل للتنفيذ codeqlفقط .

الآن يمكنك تشغيل أوامر CodeQL.

التحقق من إعداد CLI

يمكنك تشغيل أوامر CodeQL CLI الفرعية للتحقق من إعداد CLI بشكل صحيح ويمكن تحليل قواعد البيانات:

• قم بتشغيل codeql resolve packs (إذا أضفت codeql إلى PATH) لإظهار حزم CodeQL التي يمكن أن يعثر عليها CLI. وإلا، استخدم /<extraction-root>/codeql/codeql resolve packs. يعرض هذا الأمر أسماء حزم CodeQL المضمنة في حزمة CodeQL CLI، الموضحة في الخطوات السابقة ك <extraction-root>.

  إذا تعذر على CodeQL CLI العثور على حزم CodeQL للغات المتوقعة، فتحقق من تنزيل حزمة CodeQL وليس نسخة مستقلة من CodeQL CLI.

• قم بتشغيل codeql resolve languages لإظهار اللغات التي تدعمها حزمة CodeQL CLI بشكل افتراضي.

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

إنشاء قاعدة بيانات CodeQL عن طريق تشغيل هذا الأمر من جذر السداد مع الخروج لمشروعك:

codeql database create <database> --language=<language-identifier>

في الأمر:

• استبدل <database> بالمسار إلى قاعدة البيانات الجديدة التي سيتم إنشاؤها.
• استبدل <language-identifier> بمعرف اللغة التي تستخدمها لإنشاء قاعدة البيانات. يمكنك استخدام هذا المعرف مع --db-cluster لقبول القوائم المفصولة بفواصل، أو يمكنك تحديده أكثر من مرة.

يمكنك أيضا تحديد الخيارات التالية. تعتمد هذه الخيارات على موقع الملف المصدر، أو ما إذا كانت التعليمات البرمجية الخاصة بك بحاجة إلى التحويل البرمجي، أو ما إذا كنت تريد إنشاء قواعد بيانات CodeQL لأكثر من لغة واحدة.

• استخدم --source-root لتعريف المجلد الجذر لملفات المصدر الأساسية لإنشاء قاعدة البيانات.
• استخدم --db-cluster لقاعدة التعليمات البرمجية متعددة اللغات عندما تريد إنشاء قواعد بيانات لأكثر من لغة واحدة.
• استخدم --command عند إنشاء قاعدة بيانات لواحدة أو أكثر من اللغات المحولة برمجيا. لا تحتاج إلى هذا الخيار إذا كنت تستخدم Python وJavaScript فقط.
• استخدم --no-run-unnecessary-builds جنبا إلى جنب مع --db-cluster لمنع أمر الإنشاء للغات حيث لا يحتاج CodeQL CLI إلى مراقبة البنية.

بعد إنشاء قاعدة البيانات بنجاح، يظهر دليل جديد في المسار المحدد في الأمر . إذا استخدمت الخيار --db-cluster لإنشاء أكثر من قاعدة بيانات واحدة، يتم إنشاء دليل فرعي لكل لغة.

يحتوي كل دليل قاعدة بيانات CodeQL على أدلة فرعية متعددة، بما في ذلك البيانات الارتباطية المستخدمة للتحليل وأرشيف المصدر. الأرشيف المصدر هو نسخة من الملفات المصدر التي تم إجراؤها في الوقت الذي قمت فيه بإنشاء قاعدة البيانات. يستخدمه CodeQL لعرض نتائج التحليل.

مستخرجات

أداة الاستخراج هي أداة تنتج البيانات الارتباطية ومرجع المصدر لكل ملف إدخال، يمكن من خلاله إنشاء قاعدة بيانات CodeQL. تحتوي كل لغة يدعمها CodeQL على مستخرج واحد. تضمن هذه البنية أن تكون عملية الاستخراج دقيقة قدر الإمكان.

يحدد كل مستخرج مجموعة خيارات التكوين الخاصة به. يؤدي إدخال codeql resolve extractor --format=betterjson إلى بيانات منسقة مثل المثال التالي:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

لمعرفة الخيارات المتوفرة لمستخرج اللغة، أدخل codeql resolve languages --format=betterjson أو codeql resolve extractor --format=betterjson. يوفر تنسيق إخراج betterjson أيضا جذر المستخرج وخيارات أخرى خاصة باللغة.

البيانات في قاعدة بيانات CodeQL

قاعدة بيانات CodeQL هي دليل واحد يحتوي على جميع البيانات المطلوبة للتحليل. تتضمن هذه البيانات بيانات ارتباطية وملفات مصدر منسوخة ومخطط قاعدة بيانات خاصة باللغة يحدد العلاقات المتبادلة في البيانات. تستورد CodeQL هذه البيانات بعد الاستخراج.

توفر قواعد بيانات CodeQL لقطة لبيانات لغة معينة قابلة للاستعلام تم استخراجها من قاعدة تعليمات برمجية. هذه البيانات هي تمثيل هرمي كامل للتعليمات البرمجية. يتضمن تمثيلا لشجرة بناء الجملة المجردة، والرسم البياني لتدفق البيانات، والرسم البياني لتدفق التحكم.

يتم إنشاء قواعد البيانات لغة واحدة في كل مرة لقاعدة التعليمات البرمجية متعددة اللغات. لكل لغة مخطط قاعدة بيانات فريد خاص بها. يوفر المخطط واجهة بين التحليل المعجمي الأولي أثناء عملية الاستخراج والتحليل المعقد من خلال CodeQL.

تتضمن قاعدة بيانات CodeQL جدولين رئيسيين:

• يحتوي جدول expressions على صف لكل تعبير في التعليمات البرمجية المصدر التي حللها CodeQL أثناء عملية الإنشاء.
• يحتوي جدول statements على صف لكل عبارة في التعليمات البرمجية المصدر التي حللها CodeQL أثناء عملية الإنشاء.

تحدد مكتبة CodeQL الفئات لتوفير طبقة من التجريد على كل جدول من هذه الجداول. تتضمن هذه الطبقة الجداول المساعدة ذات الصلة ExprStmt.

حالات النقص المحتملة في CodeQL

إنشاء قاعدة البيانات في سير عمل مسح التعليمات البرمجية لديه بعض أوجه القصور المحتملة. يناقش هذا القسم على وجه التحديد استخدام إجراء GitHub CodeQL.

تحتاج إلى استخدام مصفوفة لغة autobuild لإنشاء كل لغة من اللغات المحولة برمجيا المدرجة في المصفوفة. يمكنك استخدام مصفوفة لإنشاء وظائف لأكثر من إصدار معتمد واحد من لغة برمجة أو نظام تشغيل أو أداة.

إذا لم تستخدم مصفوفة، autobuild يحاول إنشاء اللغة المحولة برمجيا المدعومة مع معظم الملفات المصدر في المستودع. غالبا ما يفشل تحليل اللغات المحولة برمجيا، بخلاف Go، إلا إذا قمت بتوفير أوامر صريحة لإنشاء التعليمات البرمجية قبل تنفيذ خطوة التحليل.

يختلف سلوك خطوة autobuild اعتمادا على نظام التشغيل الذي يعمل عليه مستخرج اللغة. تحاول خطوة autobuild الكشف تلقائيا عن أسلوب بناء مناسب للغة استنادا إلى نظام التشغيل. يمكن أن يؤدي هذا السلوك إلى نتائج غير موثوق بها للغات المحولة برمجيا، ويمكن أن يؤدي في كثير من الأحيان إلى فشل التشغيل.

نوصي بتكوين خطوة بناء داخل ملف سير عمل مسح التعليمات البرمجية الذي يتم تشغيله قبل التحليل، بدلا من السماح autobuild محاولة إنشاء لغات مجمعة. بهذه الطريقة، يتم تصميم ملف سير العمل وفقا لمتطلبات بناء النظام والمشروع لإجراء عمليات فحص أكثر موثوقية.

يمكنك قراءة المزيد حول لغات معينة وخطوات autobuild في وثائق الإنشاء التلقائي CodeQL.

ملحق VS Code

يمكنك استخدام Visual Studio Code (VS Code) وملحق CodeQL لتجميع الاستعلامات وتشغيلها، طالما كنت تستخدم VS Code 1.39 أو أحدث. يمكنك تنزيل الملحق من Visual Studio Code Marketplace أو عن طريق تنزيل ملف CodeQL VSIX.

يستخدم الملحق CLI المثبت الذي تم العثور عليه في PATH إذا كان متوفرا. إذا لم يكن الأمر كما هو، فإن الملحق يدير تلقائيا الوصول إلى الملف القابل للتنفيذ ل CLI نيابة عنك. تضمن الإدارة التلقائية أن CLI متوافق مع ملحق CodeQL.