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

مكتمل

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

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

استعلامات إضافية في ملف التكوين المخصص

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

في ملف سير العمل، استخدم المعامل config-file للإجراء init لتحديد المسار إلى ملف التكوين الذي تريد استخدامه. يقوم هذا المثال بتحميل ملف التكوين ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

يمكن أن يكون ملف التكوين موجودا داخل المستودع الذي تقوم بتحليله أو في مستودع خارجي. يتيح لك استخدام مستودع تخزين خارجي تحديد خيارات التكوين لمستودعات تخزين متعددة في مكان واحد. عند الرجوع إلى ملف التكوين الموجود في مستودع تخزين خارجي، يمكنك استخدام بناء الجملة OWNER/REPOSITORY/FILENAME@BRANCH. على سبيل المثال: octo-org/shared/codeql-config.yml@main.

إذا كان ملف التكوين موجوداً في مستودع تخزين خاص خارجي، فاستخدم external-repository-token المعلمةinit للإجراء لتحديد رمز مميز له حق الوصول إلى المستودع الخاص.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

تمت كتابة الإعدادات في ملف التكوين بتنسيق YAML.

حدد حزم استعلام CodeQL في ملفات التكوين المخصصة

إشعار

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

يمكنك تحديد حزم استعلام CodeQL في صفيف. يختلف التنسيق عن التنسيق المستخدم من قبل ملف سير العمل.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

التنسيق الكامل لتحديد حزمة استعلام هو scope/name[@version][:path]. كلاهما version اختياري path . version هو نطاق إصدار semver. إذا كان مفقودا، يتم استخدام أحدث إصدار.

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

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

حدد استعلامات إضافية في تكوين مخصص

يمكنك تحديد استعلامات إضافية في صفيف queries . يحتوي كل عنصر من عناصر الصفيف على معلمة uses بقيمة تعرف ملف استعلام واحد أو دليلا يحتوي على ملفات استعلام أو ملف تعريف مجموعة استعلام.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

اختياريا، يمكنك إعطاء كل عنصر صفيف اسما، كما هو موضح في ملف التكوين المثال التالي:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

تعطيل الاستعلامات الافتراضية

إذا كنت تريد تشغيل الاستعلامات المخصصة فقط، فيمكنك تعطيل استعلامات الأمان الافتراضية باستخدام disable-default-queries: true. يجب عليك أيضا استخدام هذه العلامة إذا كنت تحاول إنشاء مجموعة استعلام مخصصة تستبعد قاعدة معينة. هذا يتجنب تشغيل جميع الاستعلامات مرتين.

استبعاد استعلامات محددة من التحليل

يمكنك إضافة exclude وتصفية include إلى ملف التكوين المخصص، لتحديد الاستعلامات التي تريد استبعادها أو تضمينها في التحليل، مثل:

• استعلامات محددة من المجموعات الافتراضية (securityو security-extendedsecurity-and-quality).
• استعلامات محددة لا تهمك نتائجها.
• جميع الاستعلامات التي تنشئ تحذيرات وتوصيات.

يمكنك استخدام exclude عوامل تصفية مشابهة لتلك الموجودة في التكوين الملف التالي لاستبعاد الاستعلامات التي تريد إزالتها من التحليل الافتراضي. في مثال ملف التكوين التالي، يتم استبعاد الاستعلامين js/redundant-assignment و js/useless-assignment-to-local من التحليل.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

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

الأمور التي يجب مراعاتها عند استخدام عامل التصفية excludes :

• ترتيب عوامل التصفية مهم. تحدد إرشادات عامل التصفية الأولى التي تظهر بعد الإرشادات حول الاستعلامات وحزم الاستعلام ما إذا كانت الاستعلامات مضمنة أو مستبعدة بشكل افتراضي.
• يتم تنفيذ الإرشادات اللاحقة بالترتيب والإرشادات التي تظهر لاحقا في الملف لها الأسبقية على الإرشادات السابقة.

حدد الدلائل لمسحها ضوئيا

بالنسبة للغات المفسرة التي يدعمها CodeQL (Python وRupe وJavaScript/TypeScript)، يمكنك تقييد مسح التعليمات البرمجية إلى الملفات في دلائل معينة عن طريق إضافة paths صفيف إلى ملف التكوين. يمكنك استبعاد الملفات الموجودة في أدلة معينة من التحليل عن طريق إضافة مصفوفة paths-ignore.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

إشعار

• paths يجب عدم الخلط بين الكلمات الأساسية وpaths-ignore، المستخدمة في سياق ملف تكوين فحص التعليمات البرمجية، مع نفس الكلمات الأساسية عند استخدامها on.<push|pull_request>.paths في سير العمل. عند استخدامها للتعديل on.<push|pull_request> في سير عمل، فإنها تحدد ما إذا كان سيتم تشغيل الإجراءات عندما يقوم شخص ما بتعديل التعليمات البرمجية في الدلائل المحددة.
• أحرف ?نمط عامل التصفية و +[]! غير معتمدة وسيتم مطابقتها حرفيا.
• يمكن أن تكون الأحرف ** في بداية السطر أو نهايته فقط، أو محاطة بشرطة مائلة، ولا يمكنك خلط ** والأحرف الأخرى. على سبيل المثال: foo/**و **/fooو foo/**/bar كلها بنية مسموح بها، ولكنها **foo ليست كذلك. ومع ذلك، يمكنك استخدام نجوم مفردة مع أحرف أخرى، كما هو موضح في المثال. ستحتاج إلى اقتباس أي شيء يحتوي على حرف *.

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

يمكنك بسرعة تحليل أجزاء صغيرة من monorepo عند تعديل التعليمات البرمجية في أدلة معينة. ستحتاج إلى استبعاد الدلائل في خطوات الإصدار واستخدام الكلمات الرئيسية paths-ignore وpaths لـ on.<push|pull_request> في سير عملك.