قم بتخصيص سير عمل مسح الرمز الخاص بك باستخدام CodeQL - الجزء 1

  • 10 دقائق

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

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

يمكنك تشغيل استعلامات إضافية إذا كانت جزءا من حزمة CodeQL (بيتا) المنشورة في سجل حاوية GitHub، أو حزمة QL مخزنة في مستودع.

يوجد خياران لتحديد الاستعلامات التي تريد تشغيلها باستخدام مسح كود CodeQL:

  • استخدام سير عمل مسح الرمز الخاص بك
  • استخدام ملف تكوين مخصص

في هذه الوحدة، ستتعلم كيفية تحرير ملف سير عمل للإشارة إلى استعلامات إضافية، وكيفية استخدام الاستعلامات من حزم الاستعلام، وكيفية دمج الاستعلامات من ملف سير عمل وملف تكوين مخصص.

تحديد استعلامات إضافية في ملف سير عمل

الخيارات المتوفرة لتحديد الاستعلامات الإضافية التي تريد تشغيلها هي:

  • packsلتثبيت حزمة استعلام CodeQL واحدة أو أكثر (تجريبية) وتشغيل مجموعة أو استعلامات الاستعلام الافتراضية لتلك الحزم.
  • queries لتحديد ملف واحد .ql أو دليل يحتوي على ملفات .ql متعددة .qls أو ملف تعريف مجموعة استعلام أو أي مجموعة.

يمكنك استخدام كل من الحزم والاستعلامات في نفس سير العمل.

لا نوصي بالرجوع إلى مجموعات الاستعلام مباشرة من github/codeqlالمستودع، مثلgithub/codeql/cpp/ql/src@main. قد لا يتم تجميع مثل هذه الاستعلامات باستخدام نفس إصدار CodeQL المستخدم في استعلاماتك الأخرى، مما قد يؤدي إلى حدوث أخطاء أثناء التحليل.

استخدام حزم استعلام CodeQL

إشعار

وظيفة إدارة حزمة CodeQL، بما في ذلك حزم CodeQL، هي حاليا في الإصدار التجريبي وتخضع للتغيير.

لإضافة حزمة استعلام CodeQL واحدة أو أكثر (بيتا)، أضف with: packs:إدخالاً داخل uses: github/codeql-action/init@v1 مقطع سير العمل. ضمن الحزم، يمكنك تحديد حزمة واحدة أو أكثر لاستخدامها، واختياريا، الإصدار الذي يجب تنزيله. في حالة عدم تحديد إصدار، يتم تنزيل أحدث إصدار. إذا كنت ترغب في استخدام الحزم غير المتوفرة للجمهور، تحتاج إلى تعيين GITHUB_TOKEN متغير البيئة إلى سر لديه حق الوصول إلى الحزم.

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

  • يتم تنزيل أحدث إصدار من pack1 ، ويتم تشغيل جميع الاستعلامات الافتراضية.
  • يتم تنزيل الإصدار 1.2.3 من pack2 ، ويتم تشغيل جميع الاستعلامات الافتراضية.
  • يتم تنزيل أحدث إصدار من pack3 ذلك متوافق مع الإصدار 3.2.1، ويتم تشغيل جميع الاستعلامات.
  • يتم تنزيل الإصدار 4.5.6 من pack4 ، ويتم تشغيل الاستعلامات الموجودة في المسار/إلى/الاستعلامات فقط.
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

إشعار

بالنسبة لعمليات سير العمل التي تنشئ قواعد بيانات CodeQL للغات متعددة، يجب عليك بدلاً من ذلك تحديد حزم استعلام CodeQL في ملف التكوين.

استخدم الاستعلامات في حزم QL

لإضافة استعلام واحد أو أكثر، قم بإضافة with: queries:إدخال داخلuses: github/codeql-action/init@v3 قسم سير العمل. إذا كانت الاستعلامات في مستودع خاص، فاستخدم external-repository-token المعامل لتحديد رمز له حق الوصول لسحب المستودع الخاص.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

يمكنك أيضا تحديد مجموعات الاستعلام في قيمة queries. مجموعات الاستعلام هي مجموعات من الاستعلامات، يتم تجميعها عادة حسب الغرض أو اللغة.

مجموعات الاستعلام التالية مضمنة في مسح التعليمات البرمجية CodeQL وهي متاحة للاستخدام:

مجموعة الاستعلام ‏‏الوصف
security-extended استعلامات من المجموعة الافتراضية، بالإضافة إلى استعلامات أقل خطورة ودقة
security-and-quality استعلامات من security-extended، بالإضافة إلى استعلامات الصيانة والموثوقية

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

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

اجمع بين الاستعلامات من ملف سير العمل وملف التكوين المخصص

إذا كنت تستخدم أيضاً ملف تكوين للإعدادات المخصصة، فسيتم استخدام أي حزم أو استعلامات إضافية محددة في سير العمل بدلاً من تلك المحددة في ملف التكوين. إذا كنت تريد تشغيل المجموعة المجمعة من الحزم أو الاستعلامات الإضافية، فبادئة قيمة packs أو queries في سير العمل بالرمز + .

في المثال التالي، + يضمن الرمز استخدام الحزم والاستعلامات الإضافية المحددة مع أي محدد في ملف التكوين المشار إليه:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries